From f46302483818266114cf0270aaad92edcf8da94f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Krist=C3=B3f=20T=C3=B3th?= Date: Tue, 17 Apr 2018 14:58:24 +0200 Subject: [PATCH] Update README with project structure description --- README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 75 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c1b0059..223eaa2 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,9 @@ TFW consists of 3 repositories: See the documentation of each in their `README.md` files. -Getting started with creating challenges using the framework – *setting up a development environment, building, running and such* – is documented here. +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` repo. +Getting started with creating challenges using the framework – *setting up a development environment, building, running and such* – is documented here. ## Setting up a development environment @@ -57,3 +57,76 @@ Running – execute: In case of a frontendless build (with `--build-arg NOFRONTEND=1`) you will need to run `yarn start` from the `solvable/frontend` directory as well. This will serve the frontend on `http://localhost:4200`. If you've created a production build (without `--build-arg NOFRONTEND=1`) you don't have to run the frontend locally and you can access the challenge on `http://localhost:8888`. + +## Getting our hands dirty + +The repository of a tutorial-framework based challenge is quite similar to a regular challenge. +The project root should look something like this: + +``` +your_repo +├── solvable +│ └── [TFW based Docker image] +├── controller +│ └── [solution checking] +├── metadata +│ └── [challenge descriptions, writeups, etc.] +└── 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`. + +From now on we are going to focus on the `solvable` image. + +### Basics of a TFW based challenge + +Let us take a closer look on `solvable`: + +``` +solvable +├── Dockerfile +├── nginx webserver configurations +├── supervisor process manager (init replacement) +├── frontend clone of the frontend-tutorial-framework repo with dependencies installed +└── src challenge source code +``` + +### 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. +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: +``` +location /yoururl { + proxy_pass http://127.0.0.1:3333; +} +``` +After this you can access the service running on port `3333` at `http://localhost:8888/yoururl` + +### 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: + +``` +[program:yourprogram] +user=user +directory=/home/user/example/ +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`). + +### frontend + +This is a clone of the `frontend-tutorial-framework` repository with dependencies installed in `solvable/frontend/node_modules`. + +### src + +This folder contains the source code of the challenge.