From 62809439dab3d28cc6f3d5a57e9f0a04d66d795d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krist=C3=B3f=20T=C3=B3th?= Date: Tue, 17 Apr 2018 17:39:57 +0200 Subject: [PATCH] Continue writing docs --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 48 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 223eaa2..52fab07 100644 --- a/README.md +++ b/README.md @@ -91,14 +91,18 @@ solvable └── src challenge source code ``` +Note that our baseimage *requires* the `nginx`, `supervisor` and `frontend` folders to be in these **exact** locations, used as described below. This is a contract your image **must** comply. + +The `src` directory is not a concept of TFW and you can call it however you like and put it's contens anywhere, just be sure to adjust your `Dockerfile` accordingly. + ### nginx All TFW based challenges expose a single port defined in the `TFW_PUBLIC_PORT` envvar which is set to `8888` by default. This means that in order to listen on more than a single port we must use a reverse proxy. -Any `.conf` files in the `solvable/nginx/components` will be automatically included in the nginx configuration. +Any `.conf` files in `solvable/nginx/` will be automatically included in the nginx configuration. In case you want serve a website or service you must proxy it through `TFW_PUBLIC_PORT`. -This is really easy: just create a config file in `solvable/nginx/components` similar to this one: +This is really easy: just create a config file in `solvable/nginx/` similar to this one: ``` location /yoururl { proxy_pass http://127.0.0.1:3333; @@ -106,12 +110,18 @@ location /yoururl { ``` After this you can access the service running on port `3333` at `http://localhost:8888/yoururl` +You can learn about configuring nginx in [this](https://www.digitalocean.com/community/tutorials/understanding-the-nginx-configuration-file-structure-and-configuration-contexts) handy little tutorial. + ### supervisor In most Docker conainers there is a single running process with `PID 1`. Using TFW you can run as many processes as you want to using supervisord. -To run your own webservice for instance you need to create a config file in `solvable/supervisor/components` similar to this one: +Any `.conf` files in the `solvable/supervisor/` will be included in the supervisor configuration. +The programs you define this way are easy to manage (starting/stopping/restarting) using the `supervisorctl` command line tool or our built-in event handler. +You can even configure your processes to start with the container by including `autostart=true` in the configuration file. + +To run your own webservice for instance you need to create a config file in `solvable/supervisor/` similar to this one: ``` [program:yourprogram] @@ -123,6 +133,8 @@ autostart=true This starts the `/home/user/example/server.py` script using `python3` after your container entered the running state (because of `autostart=true`). +You can learn more about configuring supervisor [here](http://supervisord.org/configuration.html). + ### frontend This is a clone of the `frontend-tutorial-framework` repository with dependencies installed in `solvable/frontend/node_modules`. @@ -130,3 +142,36 @@ This is a clone of the `frontend-tutorial-framework` repository with dependencie ### src This folder contains the source code of the challenge. + +``` +solvable/src +├── tfw_server.py tutorial-framework server +├── event_handler_main.py event handlers implemented in python +└── test_fsm.py example FSM +``` + +The core of the framework is the `TFWServer` class, which is instanciated in `tfw_server.py`. +This class handles the forwarding of the messages from the frontend to the event handlers connecting to it via ZMQ and manages the FSM. +As you can see this file is set up to start with the container in `solvable/supervisor/tfw_server.conf`. + +`event_handler_main.py` contains example usage of our pre-defined event handlers written in Python3. +As you can see they run in a separate process (set up in `solvable/supervisor/event_handlers.conf`). +These event handlers could be implemented in any language that has ZMQ bindings. + +## Baby steps + +When creating your own challange the process should be something like this: +1. Using our install script to bootstrap your dev environment +2. Creating an FSM that describes your challenge + - This is done in `solvable/src/test_fsm.py` +3. Creating a `TFWServer` instance and setting it up to run: + - Creating a server app: `solvable/src/tfw_server.py` + - Setting it up to run: `solvable/supervisor/tfw_server.conf` +4. Creating event handlers connecting to the `TFWServer` handling events you want to handle: + - Creating an event handler server: `solvable/src/event_handler_main.py` + - Setting it up to run: `solvable/supervisor/event_handlers.conf` +5. Modifying the frontend in `solvable/frontend` to fit your challenge + - This usually involves using our pre-made components + - And perhaps doing some of your own stuff, like: + - Sending messages then handling these in event handlers + - Sending triggers to step the FSM