Update README.md

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`.