From 4f2a434e2b81359280bf8dd90e7d7048d5be037c Mon Sep 17 00:00:00 2001 From: Roberto Alsina Date: Sun, 30 Jun 2024 17:58:19 -0300 Subject: [PATCH] updated README --- README.md | 144 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 131 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 7fde795..d66bbe4 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,145 @@ -# faaso +# FaaSO -TODO: Write a description here +FaaSO is a simple, small, fast, efficient way to deploy your code, written +in pretty much any language, into your own infrastructure. -## Installation +Or at least that's the plan, although it's not all that yet. -TODO: Write installation instructions here +## 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](https://crystal-lang.org) 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 -TODO: Write usage instructions here +You need a server, with docker. In that server, build it as explained above. +You can run the `faaso-proxy` with something like this: -## Development +``` +docker run --network=faaso-net -v /var/run/docker.sock:/var/run/docker.sock -p 8888:8888 faaso-proxy +``` -TODO: Write development instructions here +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`: + +```crystal +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: + +```yml +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](https://kemalcr.com/) 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 either 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``` + +Or, once you built it, you can run it, and you will be able to see it using +`docker ps`: + +```faaso up myfunko``` + +### 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 -1. Fork it () -2. Create your feature branch (`git checkout -b my-new-feature`) -3. Commit your changes (`git commit -am 'Add some feature'`) -4. Push to the branch (`git push origin my-new-feature`) -5. Create a new Pull Request +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](https://github.com/your-github-user) - creator and maintainer +- [Roberto Alsina](https://github.com/ralsina) - creator and maintainer