From 2875d3eb594c5ecae4bde73f47751b29fc452304 Mon Sep 17 00:00:00 2001 From: Pierre-Olivier Mercier Date: Thu, 9 Sep 2021 15:00:23 +0200 Subject: [PATCH] Update README.md --- README.md | 99 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 79 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index cde41337..1f4d6fff 100644 --- a/README.md +++ b/README.md @@ -6,20 +6,74 @@ to be robust, so it uses some uncommon technics like client certificate for authentication, lots of state of the art cryptographic methods and aims to be deployed in a DMZ network architecture. +This is a [monorepo](https://danluu.com/monorepo/), containing several +micro-services : + +- `admin` is the web interface and API used to control the challenge + and doing synchronization. +- `backend` is an inotify reacting service that handles submissions + checking and team's files generation. +- `dashboard` is a public interface to explain and follow the + conquest, aims to animate the challenge for visitors. +- `frontend` is only responsible for receiving submissions. It is the + only dynamic part accessibe to players, so it's codebase is reduce + to the minimum. It does not parse or try to understand players + submissions, it just write it down to a file in the file + system. Parsing and treatment is made by the `backend`. +- `qa` is an interface dedicated to challenge development, it stores + reports to be treated by challenges creators. +- `remote/scores-sync-zqds` is an inotify reacting service that allows + us to synchronize scores with the ZQDS scoring platform. +- `repochecker` is a side project to check offline for synchronization + issues. + +In the production setup, each micro-service runs in a dedicated +container, isolated from each other. Moreover, two physical machines +should be used: + +- `deimos` communicates with players: displaying the web interface, + authenticate teams and players, storing contest files and handling + submissions retrieval without understanding them. It can't access + `phobos` so its job stop after writing requests on the filesystem. +- `phobos` is hidden from players, isolated from the network. It can + only access `deimos` via a restricted ssh connection, to retrieve + requests from `deimos` filesystem and pushing to it newly generated + static files. + +So, the general filesystem is organized this way: + +- `DASHBOARD` contains files structuring the content of the dashboard + screen(s). +- `FILES` stores the contest file to be downloaded by players. To be + accessible without authentication and to avoid bruteforce, each file + is placed into a directory with a hashed name (the original file + name is preserved). It's rsynced as is to `deimos`. +- `PKI` takes care of the PKI used for the client certiciate + authorization process, and more generaly, all authentication related + files (htpasswd, dexidp config, ...). Only the `shared` subdirectory + is shared with `deimos`, private key and teams P12 don't go out. +- `SETTINGS` stores the challenge config as wanted by admins. It's not + always the config in use: it uses can be delayed waiting for a + trigger. +- `SETTINGSDIST` is the challenge configuration in use. It is the one + shared with players. +- `startingblock` keep the `started` state of the challenge. This + helps `nginx` to know when it can start distributing exercices + related files. +- `TEAMS` stores the static files generated by the `backend`, there is + one subdirectory by team (id of the team), plus some files at the + root, which are common to all teams. There is also symlink pointing + to team directory, each symlink represent an authentication + association (certificate ID, OpenID username, htpasswd user, ...). +- `submissions` is the directory where the `frontend` writes + requests. It creates subdirectories at the name of the + authentication association, as seen in `TEAMS`, `backend` then + resolve the association regarding `TEAMS` directory. There is also a + special directory to handle team registration. Local developer setup --------------------- -### The importance of clone location - -This is a [monorepo](https://danluu.com/monorepo/), primarly intended for Go -programming. If you want to be able to do programming stuff, you should take -care of the path where you clone this repository, as it should be located -inside [your `GOPATH`](https://github.com/golang/go/wiki/SettingGOPATH): - - git clone https://git.nemunai.re/fic/server.git $GOPATH/src/srs.epita.fr/fic-server - - ### Using Docker Use `docker-compose build`, then `docker-compose up` to launch the infrastructure. @@ -52,17 +106,17 @@ a database (currently supporting only MySQL/MariaDB), a Go compiler for the revi 1. First, you'll need to retrieve the dependencies: - go get -d srs.epita.fr/fic-server/admin - go get -d srs.epita.fr/fic-server/backend - go get -d srs.epita.fr/fic-server/dashboard - go get -d srs.epita.fr/fic-server/frontend + go mod vendor 2. Then, build the three Go projects: - go build -o $GOPATH/src/srs.epita.fr/fic-server/fic-admin srs.epita.fr/fic-server/admin - go build -o $GOPATH/src/srs.epita.fr/fic-server/fic-backend srs.epita.fr/fic-server/backend - go build -o $GOPATH/src/srs.epita.fr/fic-server/fic-dashboard srs.epita.fr/fic-server/dashboard - go build -o $GOPATH/src/srs.epita.fr/fic-server/fic-frontend srs.epita.fr/fic-server/frontend + go build -o fic-admin ./admin + go build -o fic-backend ./backend + go build -o fic-dashboard ./dashboard + go build -o fic-frontend ./frontend + go build -o fic-qa ./qa + go build -o fic-repochecker ./repochecker + ... 3. Before launching anything, you need to create a database: @@ -102,5 +156,10 @@ a database (currently supporting only MySQL/MariaDB), a Go compiler for the revi This last server runs the public dashboard. It serves all file, without the need of a webserver. It listens on port 8082 by default. -For the moment, a web server is mandatory to serve static files, look at the -samples given in the `configs/` directory. +For the moment, a web server is mandatory to serve static files, look +at the samples given in the `configs/nginx` directory. You need to +pick one base configation flavor in the `configs/nginx/base` +directory, and associated with an authentication mechanism in +`configs/nginx/auth` (named the file `fic-auth.conf` in `/etc/nginx`), +and also pick the corresponding `configs/nginx/get-team` file, you +named `fic-get-team.conf`.