From f0a3f62847b6990da14679075f1fea97a8b7d426 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krist=C3=B3f=20T=C3=B3th?= Date: Tue, 17 Apr 2018 18:04:59 +0200 Subject: [PATCH] Fix and extend docs --- README.md | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 52fab07..19766e8 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ your_repo └── config.yml ``` -The only notable difference is that the `solvable` Docker image is a child image of our baseimage: `solvable/Dockerfile` begins with `FROM eu.gcr.io/avatao-challengestore/tutorial-framework`. +The only notable difference is that the `solvable` Docker image is a child of our baseimage: `solvable/Dockerfile` begins with `FROM eu.gcr.io/avatao-challengestore/tutorial-framework`. From now on we are going to focus on the `solvable` image. @@ -88,12 +88,13 @@ solvable ├── nginx webserver configurations ├── supervisor process manager (init replacement) ├── frontend clone of the frontend-tutorial-framework repo with dependencies installed -└── src challenge source code +└── src example 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. +The `src` directory is not a concept of TFW and you can call it however you like and put your version anywhere, just be sure to adjust your `Dockerfile` accordingly. +It contains a simple example of using TFW. ### nginx @@ -114,12 +115,12 @@ You can learn about configuring nginx in [this](https://www.digitalocean.com/com ### supervisor -In most Docker conainers there is a single running process with `PID 1`. +In most Docker conainers there is a single process running (it gets `PID 1`). Using TFW you can run as many processes as you want to using supervisord. -Any `.conf` files in the `solvable/supervisor/` will be included in the supervisor configuration. +Any `.conf` files in the `solvable/supervisor/` directory 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. +You can even configure your processes to start with the container by including `autostart=true` in your configuration file. To run your own webservice for instance you need to create a config file in `solvable/supervisor/` similar to this one: @@ -131,7 +132,7 @@ command=python3 server.py autostart=true ``` -This starts the `/home/user/example/server.py` script using `python3` after your container entered the running state (because of `autostart=true`). +This starts the `/home/user/example/server.py` script using `python3` after your container entered the running state (because of `autostart=true`, supervisor does not start programs by default). You can learn more about configuring supervisor [here](http://supervisord.org/configuration.html). @@ -139,9 +140,16 @@ You can learn more about configuring supervisor [here](http://supervisord.org/co This is a clone of the `frontend-tutorial-framework` repository with dependencies installed in `solvable/frontend/node_modules`. +You can modify it to fit your needs, but this requires some Angular knowledge (not much at all). + +If all you want to do is start a simple web application and send some messages you can mostly skip the Angluar knowledge bit. Refer to the example in this repo. + +**TODO: example non-angular webapp** + ### src -This folder contains the source code of the challenge. +This folder contains the source code of a server running TFW and an other server running our event handlers. +Note that this is not a part of the framework by any means, these are just simple examples. ``` solvable/src @@ -151,7 +159,8 @@ solvable/src ``` 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. +This class handles the forwarding of the messages from the frontend to the event handlers connecting to it via ZMQ. +It also 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. @@ -163,7 +172,7 @@ These event handlers could be implemented in any language that has ZMQ bindings. 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` + - An example is 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` @@ -173,5 +182,6 @@ When creating your own challange the process should be something like this: 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 messages then handling these in event handlers written in step 4 - Sending triggers to step the FSM + - Including images of cats