mrtoth/test-tutorial-framework
1
0
Fork 0
mirror of https://github.com/avatao-content/test-tutorial-framework synced 2024-11-15 02:27:18 +00:00
Code Issues Releases Wiki Activity

Resolve TODOs in README

Browse Source
This commit is contained in:
Kristóf Tóth 2018-04-25 17:44:12 +02:00
parent 1a295d5fd6
commit 26801bed52
1 changed files with 27 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
README.md
View File

@ -14,7 +14,7 @@ TFW consists of 3 repositories:
See the documentation of each in their `README.md` files. See the documentation of each in their `README.md` files.
To learn the stuff you need to know about TFW in order to get started you should consult the `baseimage-tutorial-framework` repo first. To learn the stuff you need to know about TFW in order to get started you should consult the [baseimage-tutorial-framework](https://github.com/avatao-content/baseimage-tutorial-framework) repo first.
Getting started with creating challenges using the framework – *setting up a development environment, building, running and such* – is documented here. Getting started with creating challenges using the framework – *setting up a development environment, building, running and such* – is documented here.
@ -26,7 +26,7 @@ Just copy and paste the following command in a terminal:
> You have trust issues regarding the public key infrastructure? You can request a checksum authenticated version of the installer command from our team! > You have trust issues regarding the public key infrastructure? You can request a checksum authenticated version of the installer command from our team!
This will set up a dev environment based on `test-tutorial-framework` just for you: This will set up a dev environment based on [test-tutorial-framework](https://github.com/avatao-content/test-tutorial-framework) just for you:
- it builds the latest release of the framework Docker baseimage locally - it builds the latest release of the framework Docker baseimage locally
- it pins `solvable/Dockerfile` to use the this image - it pins `solvable/Dockerfile` to use the this image
- it includes the latest frontend in `solvable/frontend` with dependencies installed - it includes the latest frontend in `solvable/frontend` with dependencies installed
@ -41,7 +41,7 @@ It is advisable to run the frontend locally while developing to avoid really loo
### Doing it manually ### Doing it manually
In case you **must** do it for some reason you can build & run manually. In case you **must** *really* do it then you can build & run manually.
Note that this is relatively painful and you should use the `hack/tfw.sh` script when possible. Note that this is relatively painful and you should use the `hack/tfw.sh` script when possible.
Building without frontend – execute from project root: Building without frontend – execute from project root:
@ -50,7 +50,7 @@ Building without frontend – execute from project root:
This will create a Docker image without the frontend, which you can run locally. For procudtion builds exclude the argument `--build-arg NOFRONTEND=1` to include a frontend instance. This will create a Docker image without the frontend, which you can run locally. For procudtion builds exclude the argument `--build-arg NOFRONTEND=1` to include a frontend instance.
Running – execute: Execute the following command to run the image:
`docker run --rm -p 8888:8888 -e AVATAO_SECRET=secret test-tutorial-framework` `docker run --rm -p 8888:8888 -e AVATAO_SECRET=secret test-tutorial-framework`
@ -92,10 +92,10 @@ solvable
└── src example 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. Note that our baseimage *requires* the `nginx`, `supervisor` and `frontend` folders to be in these **exact** locations and to be 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 your version anywhere, just be sure to adjust your `Dockerfile` accordingly. The `src` directory contains a simple example of using TFW
It contains a simple example of using TFW.
### nginx ### nginx
@ -103,7 +103,7 @@ All TFW based challenges expose a single port defined in the `TFW_PUBLIC_PORT` e
This means that in order to listen on more than a single port we must use a reverse proxy. This means that in order to listen on more than a single port we must use a reverse proxy.
Any `.conf` files in `solvable/nginx/` 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`. In case you want to 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/` similar to this one: This is really easy: just create a config file in `solvable/nginx/` similar to this one:
```text ```text
location /yoururl { location /yoururl {
@ -117,10 +117,10 @@ You can learn about configuring nginx in [this](https://www.digitalocean.com/com
### supervisor ### supervisor
In most Docker conainers there is a single process running (it gets `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. When working with TFW you can run as many processes as you want to by using supervisord.
Any `.conf` files in the `solvable/supervisor/` directory 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. 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 your 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: To run your own webservice for instance you need to create a config file in `solvable/supervisor/` similar to this one:
@ -143,9 +143,8 @@ This is a clone of the `frontend-tutorial-framework` repository with dependencie
You can modify it to fit your needs, but this requires some Angular knowledge (not much at all). 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. If all you want to do is starting a simple web application and to send some messages you can mostly skip the Angluar knowledge bit.
Refer to the example in this repo.
**TODO: example non-angular webapp**
### src ### src
@ -168,19 +167,24 @@ As you can see this file is set up to start with the container in `solvable/supe
As you can see they run in a separate process (set up in `solvable/supervisor/event_handlers.conf`). 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. These event handlers could be implemented in any language that has ZMQ bindings.
Note that you don't have to use all our event handlers.
Should you want to avoid using a feature, you can just delete the appropriate event handler from `event_handler_main.py`.
It is genarally a good idea to separate these files from the rest of the stuff in `solvable`, so it is a good practice to create an `src` directory.
## Baby steps ## Baby steps
When creating your own challange the process should be something like this: When creating your own challenge the process should be the following:
1. Using our install script to bootstrap your dev environment 1. Use our install script to bootstrap your dev environment
2. Creating an FSM that describes your challenge 2. Create an FSM that describes your challenge
- An example is 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: 3. Create a `TFWServer` instance and set it up to run:
- Creating a server app: `solvable/src/tfw_server.py` - Create a server app: `solvable/src/tfw_server.py`
- Setting it up to run: `solvable/supervisor/tfw_server.conf` - Set it up to run: `solvable/supervisor/tfw_server.conf`
4. Creating event handlers connecting to the `TFWServer` handling events you want to handle: 4. Create event handlers connecting to the `TFWServer` handling events you want to process:
- Creating an event handler server: `solvable/src/event_handler_main.py` - Create an event handler server: `solvable/src/event_handler_main.py`
- Setting it up to run: `solvable/supervisor/event_handlers.conf` - Set it up to run: `solvable/supervisor/event_handlers.conf`
5. Modifying the frontend in `solvable/frontend` to fit your challenge 5. Modify the frontend in `solvable/frontend` to fit your challenge
- This usually involves using our pre-made components - This usually involves using our pre-made components
- And perhaps doing some of your own stuff, like: - And perhaps doing some of your own stuff, like:
- Sending messages then handling these in event handlers written in step 4 - Sending messages then handling these in event handlers written in step 4