faaso/README.md

FaaSO

FaaSO is a simple, small, fast, efficient way to deploy your code, written in pretty much any language, into your own infrastructure.

Or at least that's the plan, although it's not all that yet.

A VERY Important Note Or Two

Do NOT try this unless you are very familiar with Docker, security, programming, and maybe a dozen other things. This is NOT safe to run. You will be giving alpha-level software access to your Docker, which means it could do horrible, horrible things to all your containers and, to be honest, your whole system as well as maybe other systems around you.

It tries NOT to do that, but hey, I may not be perfect, you know.

Hell, as of this writing the password is hardcoded as "admin/admin", folks.

OTOH, FaaSO aims to be very, very clear and obvious on what it does. It's mostly a very opinionated frontend for docker.

So, when you build a funko (it's explained below) you are building a docker image. When you run one? You are running a docker container.

You can always do anything manually. You can create a funko without using the FaaSO runtimes. You can instantiate any docker image as a funko. You can export your funko as a totally standalone containerized app.

The Name

FaaSO means Functions as a Service Omething. The meaning of the O is still not decided, I'll figure something out.

Building

Assuming you have a working Crystal setup, a working docker command and a checkout of the source code for FaaSO you can install it:

Build the binaries and docker image: make proxy

This will give you:

• bin/faaso the CLI for faaso
• A docker image called faaso-proxy which is the "server" component.

Usage

You need a server, with docker. In that server, build it as explained above. You can run the faaso-proxy with something like this:

docker run --network=faaso-net -v /var/run/docker.sock:/var/run/docker.sock -p 8888:8888 faaso-proxy

That will give faaso-proxy access to your docker, and expose the functionality in port 8888.

What it Does

Funkos

In FaaSO you (the user) can create Funkos. Funkos are the moral equivalent of AWS lambdas and whatever they are called in other systems. In short, they are simple programs that handle web requests.

For example, here is a hello world level funko written using Crystal, a file called funko.cr:

get "/" do
  "Hello World Crystal!"
end

Because FaaSO needs some more information about your funko to know how to use it, you also need a metadata file funko.yml in the same folder:

name: hello
runtime: crystal

If you have those two files in a folder, that folder is a funko, which is called hello and FaaSO knows it's written in Crystal. In fact, it knows (because the crystal runtime explains that, don't worry about it yet) that it's part of an application written in the Kemal framework and it knows how to create a whole container which runs the app, and how to check its health, and so on.

But the funko has the interesting bits of the app.

The full details of how to write funkos are still in flux, so not documenting it for now. Eventually, you will be able to just write the parts you need to write to create funkos in different languages. It's easy!

So what can a funko do?

Once you have a funko, you can build it, which will give you a docker image.

faaso build --local myfunko/

Or you can export it and get rid of all the mistery of how your funko really works:

faaso export myfunko/ myfuko-exported

Or, once you built it, you can run it, and you will be able to see it using docker ps:

faaso scale myfunko 1

Here scale myfunko 1 simply means "run one instance of myfunko". You can run more than one, although currently only one is used by the proxy.

The FaaSO proxy

The proxy has a few goals:

1. You can connect to it using faaso and have it build/run/etc your funkos.

   • This builds the funko in your machine: faaso build -l myfunko/
   • This builds the funko in the server pointed at by FAASO_SERVER: faaso build myfunko/

   Yes, they are exactly the same thing. In fact, if you don't use the -l flag, faaso just tells the proxy "hey proxy, run your copy of faaso over there and build this funko I am uploading"

2. It automatically reverse-proxies to all funkos.

   If you deployed a funko called hello and your faaso proxy is at http://myserver:8888 then the / path in your funko is at http://myserver:8888/funko/hello/

   This proxying is automatic, you don't need to do anything. As long as you build the image for your funko in the server and then start the funko in the server? It should work.

3. It provides an administrative interface.

   This is still very early days, and is not usable by normal people.

Contributing

Until FaaSO is in somewhat better shape, I don't want external contributions beyond bugfixes, since I am redesigning things all the time.

Contributors

• Roberto Alsina - creator and maintainer