Merge pull request #10 from joaofazolo/development

Release candidate
joaofazolo · Feb 15, 2023 · b373c0e · b373c0e
2 parents bcc80c3 + 98eb43c
commit b373c0e
Show file tree

Hide file tree

Showing 16 changed files with 321 additions and 179 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -2,38 +2,48 @@
     "docker.commands.composeUp": [
         {
             "label": "dev-match",
-            "template": "docker-compose -f docker-compose.yml ${configurationFile} up --build",
+            "template": "docker compose -f docker-compose.yml ${configurationFile} up --build",
             "match": "dev"
         },
         {
             "label": "prod-match",
-            "template": "docker-compose -f docker-compose.yml ${configurationFile} up",
+            "template": "docker compose -f docker-compose.yml ${configurationFile} up",
             "match": "prod"
         },
+        {
+            "label": "env-match",
+            "template": "docker compose ${configurationFile} up",
+            "match": "env"
+        },
         {
             "label": "secrets-match",
-            "template": "docker-compose ${configurationFile} up",
+            "template": "docker compose ${configurationFile} up",
             "match": "secrets"
         },
         {
-            "label": "env-match",
-            "template": "docker-compose ${configurationFile} up",
-            "match": "variables"
+            "label": "networks-match",
+            "template": "docker compose ${configurationFile} up",
+            "match": "networks"
         }
     ],
     "docker.commands.composeDown": [
+        {
+            "label": "env-match",
+            "template": "docker compose ${configurationFile} down",
+            "match": "env"
+        },
         {
             "label": "secrets-match",
-            "template": "docker-compose ${configurationFile} down",
+            "template": "docker compose ${configurationFile} down",
             "match": "secrets"
         },
         {
-            "label": "env-match",
-            "template": "docker-compose ${configurationFile} down",
-            "match": "variables"
+            "label": "networks-match",
+            "template": "docker compose ${configurationFile} down",
+            "match": "networks"
         },
         {
-            "template": "docker-compose -f docker-compose.yml ${configurationFile} down"
+            "template": "docker compose -f docker-compose.yml ${configurationFile} down"
         }
     ]
 }
diff --git a/README.md b/README.md
@@ -4,9 +4,9 @@ BOCA Online Contest Administrator (known simply as BOCA) is an administration sy
 
 BOCA is implemented mainly in PHP and makes use of a PostgreSQL database in the backend. It is a good example of a monolithic system, in which the user interface and database access are all interwoven, rather than containing architecturally separate components. The problem is compound due to the low readability and poor code structuring, which is hard to extend and has been barely updated in recent years.
 
-The boca-docker project is a use case of how we can take advantage of microservices architecture and containerization technology (i.e., Docker) to deploy applications in a more convenient and faster way. After quite some reverse engineering, we provide a dockerized version of BOCA's main components (web app, online automated judge and database) aiming at easying the customization, extensibility and automation of the operational effort required to deploy, run and scale BOCA.
+The _boca-docker_ project is a use case of how we can take advantage of microservices architecture and containerization technology (i.e., Docker) to deploy applications in a more convenient and faster way. After quite some reverse engineering, we provide a dockerized version of BOCA's main components (web app, online automated judge and database) aiming at easying the customization, extensibility and automation of the operational effort required to deploy, run and scale BOCA.
 
-This work started as part of the undergraduate final year project carried out by João Vitor Alves Fazolo under supervision of Prof. Dr. Rodrigo Laiola Guimaraes at Universidade Federal do Espírito Santo ([UFES](https://www.ufes.br/)).
+This work started as part of the undergraduate final year project carried out by João Vitor Alves Fazolo under supervision of Prof. Dr. Rodrigo Laiola Guimaraes at Universidade Federal do Espirito Santo ([UFES](https://www.ufes.br/)).
 
 ## REQUIREMENTS:
 
@@ -24,17 +24,17 @@ docker images -a
 docker container ls -a
 ```
 
-* Download the `docker-compose.yml` and `docker-compose.prod.yml` files, and place them in the shell current directory. Then,
+* Download the `docker-compose.yml` and `docker-compose.prod.yml` files, and place them in the current work directory. Then,
 
 ```bash
-docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
 ```
 
 Voilà! The application should be running now.
 
-* Open a web browser and visit the URL http://localhost:8000/boca. First, create and activate a BOCA contest (user: system | password: boca). Then, login as admin  (user: admin | password: boca) to manage users, problems, languages etc. NOTE: consider changing these passwords later on.
+* Open a web browser and visit the URL http://localhost:8000/boca. First, create and activate a BOCA contest (user: _system_ | password: _boca_). Then, login as admin (user: _admin_ | password: _boca_) to manage users, problems, languages etc. NOTE: consider changing these passwords later on.
 
-* The autojudge will work only after restarting the boca-jail container.
+* The autojudge will work only after restarting the `boca-jail` container.
 
 ```bash
 docker stop docker stop boca-docker_boca-jail_1
@@ -44,7 +44,7 @@ docker start docker stop boca-docker_boca-jail_1
 * To stop the application (considering that the shell is in the same directory):
 
 ```bash
-docker-compose -f docker-compose.yml -f docker-compose.prod.yml down
+docker compose -f docker-compose.yml -f docker-compose.prod.yml down
 ```
 
 ## HOW TO DEPLOY IT TO A SWARM:
@@ -71,93 +71,13 @@ docker stack rm boca-stack
 
 ## HOW TO ADD CUSTOM CONFIGURATION:
 
-There are many ways to customize the boca-docker application. Without trying to support every possible use case, here are just a few that we have found useful.
+There are many ways to customize the _boca-docker_ application. Without trying to support every possible use case, here are just a few that we have found useful.
 
-### Environment Variables
+* **Environment Variables:** shows the correct syntax for the various ways one can change pre-defined configuration values to keep the _boca-docker_ application flexible and organized. See documentation [here](tests/env/README.md).
 
-The boca-docker application uses several environment variables which are easy to miss. The variables required are `POSTGRES_PASSWORD` (`boca-db` service) and `BOCA_DB_SUPER_PASSWORD` (`boca-web` service), the rest are optional.
+* **Docker Secrets:** an alternative way to passing sensitive information via environment variables, causing the initialization scripts to load the values for those variables from files present in the containers. See documentation [here](tests/secrets/README.md).
 
-For an example, check the YAML file in the `tests/variables` folder. To run:
-
-#### ... via docker-compose
-
-```bash
-docker-compose -f tests/variables/docker-compose.yml up -d
-```
-
-#### ... or docker stack deploy
-
-```bash
-docker stack deploy --compose-file tests/variables/docker-compose.yml boca-stack
-```
-
-**`BOCA_DB_HOST`**
-
-This optional environment variable, which can be set in the `boca-web` and `boca-jail` services, defines the address/host name of the PostgreSQL server. This is useful if you are connecting to an external server or a docker container named something other than the default `boca-db`.
-
-**`BOCA_DB_SUPER_USER`**
-
-This optional environment variable is used in conjunction with `BOCA_DB_SUPER_PASSWORD` (`boca-web` service) to manage the database. This environment variable must be the superuser for PostgreSQL. If it is not specified, then the default user of `postgres` will be used.
-
-**Note:** If specified, this parameter and the `POSTGRES_USER` variable (`boca-db` service) must be set with the same value.
-
-**`BOCA_DB_SUPER_PASSWORD`**
-
-This environment variable is required for the `boca-web` service (web app) to manage the database (`boca-db` service). It must not be empty or undefined. This environment variable must be the superuser password for PostgreSQL. The default superuser is defined by the `BOCA_DB_SUPER_USER` environment variable.
-
-**Note:** It must have the same value of the `POSTGRES_PASSWORD` variable (`boca-db` service).
-
-**`BOCA_DB_USER`** and **`BOCA_DB_PASSWORD`**
-
-Optional in the `boca-web` and `boca-jail` services, these variables are used in conjunction to change the credentials of the unprivileged database user in the web app and online judge, respectively, that can manage the PostgreSQL database but not alter its schema. If they are not specified, then the default values will be used.
-
-**`BOCA_DB_NAME`**
-
-This optional environment variable can be used to define a different name for the default database that is created when the `boca-web` service is first started. If it is not specified, then a default value will be used.
-
-**`BOCA_PASSWORD`**
-
-This optional environment variable can be specified in the `boca-web` service (web app) to define the initial password for the system and admin users. If not set, the default value is `boca`. These passwords can be individually updated later on via the BOCA web interface.
-
-**`BOCA_KEY`**
-
-This optional environment variable can be specified in the `boca-web` service to set the secret key in HTTP headers. It must be any random large sequence of characters. If it is undefined, then the default value will be used.
-
-**`POSTGRES_USER`**
-
-This optional environment variable is used in conjunction with `POSTGRES_PASSWORD` (`boca-db` service) to set a user and its password. This variable will create the specified user with superuser power and a database with the same name. If it is not specified, then the default user of `postgres` will be used.
-
-**Note:** Be aware that if this parameter is specified, the `BOCA_DB_SUPER_USER` variable (`boca-web` service) must be defined with the same value.
-
-**`POSTGRES_PASSWORD`**
-
-This environment variable is required to setup the `boca-db` service (PostgreSQL database). It must not be empty or undefined. This environment variable sets the superuser password for PostgreSQL. The default superuser is defined by the `POSTGRES_USER` environment variable.
-
-**Note:** The `BOCA_DB_SUPER_PASSWORD` variable (`boca-web` service) must be set with the same value.
-
-**`BOCA_WEB_HOST`**
-
-This optional environment variable, which can be set in the `boca-jail` service, defines the address/host name of the web application. Although `boca-jail` does not interact with the `boca-web` service directly, the original configuration keeps this reference (not certain why!). Nevertheless, if set, it must be named after the web app service (default: `boca-web`).
-
-### Docker Secrets
-
-As an alternative to passing sensitive information via environment variables, `_FILE` may be appended to some of the previously listed environment variables, causing the initialization scripts to load the values for those variables from files present in the containers. In particular, this can be used to load passwords from Docker secrets stored in `/run/secrets/<secret_name>` files. 
-
-Currently, this is supported for `BOCA_DB_SUPER_USER`, `BOCA_DB_SUPER_PASSWORD`, `BOCA_DB_USER`, `BOCA_DB_PASSWORD`, `BOCA_DB_NAME`, `BOCA_PASSWORD`, `BOCA_KEY`, `POSTGRES_PASSWORD`, and `POSTGRES_USER`. 
-
-For an example, check the YAML file in the `tests/secrets` folder. To run:
-
-#### ... via docker-compose
-
-```bash
-docker-compose -f tests/secrets/docker-compose.yml up -d
-```
-
-#### ... or docker stack deploy
-
-```bash
-docker stack deploy --compose-file tests/secrets/docker-compose.yml boca-stack
-```
+* **Networking:** shows how to add network isolation between services in the _boca-docker_ application. See documentation [here](tests/networks/README.md).
 
 ## HOW TO BUILD IT:
 
@@ -171,15 +91,15 @@ cd boca-docker
 * Then, compose it up with the command below (this might take a while, sit back and relax):
 
 ```bash
-docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
 ```
 
 Follow the instructions [above](#quick-start) to set up the application.
 
 * To stop it:
 
 ```bash
-docker-compose -f docker-compose.yml -f docker-compose.dev.yml down
+docker compose -f docker-compose.yml -f docker-compose.dev.yml down
 ```
 
 * Alternatively, it is possible to build images without launching the application.
@@ -215,7 +135,7 @@ docker push ghcr.io/joaofazolo/boca-docker/boca-jail:1.1.0
 
 ## LICENSE:
 
-Copyright 2020-2022 Universidade Federal do Espirito Santo (Ufes)
+Copyright Universidade Federal do Espirito Santo (Ufes)
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
@@ -234,4 +154,4 @@ This program is released under license GNU GPL v3+ license.
 
 ## SUPPORT:
 
-Please report any issues with boca-docker at https://github.com/joaofazolo/boca-docker/issues
+Please report any issues with _boca-docker_ at https://github.com/joaofazolo/boca-docker/issues
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
@@ -1,5 +1,5 @@
 #========================================================================
-# Copyright 2020-2022 Universidade Federal do Espirito Santo (Ufes)
+# Copyright Universidade Federal do Espirito Santo (Ufes)
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -23,22 +23,22 @@ version: '3.8'
 services:
 
     boca-base:
-        image: boca-base
+        image: boca-base:latest
         build: 
             context: .
             dockerfile: docker/dev/base/Dockerfile
 
     boca-web:
-        image: boca-web
+        image: boca-web:latest
         build: 
             context: .
             dockerfile: docker/dev/web/Dockerfile
-        # CAUTION: this bind will overwrite BOCA website. For future development...
+        # CAUTION: this bind mount will overwrite BOCA website. For future development...
         # volumes:
         #     - ./src:/var/www/boca/src
 
     boca-jail:
-        image: boca-jail
+        image: boca-jail:latest
         build: 
             context: .
             dockerfile: docker/dev/jail/Dockerfile
@@ -48,8 +48,9 @@ services:
     #         - db-data:/var/lib/postgresql/data
 
     boca-adminer:
-        image: adminer
-        container_name: boca-adminer
+        image: adminer:latest
+        environment:
+            - ADMINER_DEFAULT_SERVER=boca-db
         ports:
             - 8080:8080
 

diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml
@@ -1,5 +1,5 @@
 #========================================================================
-# Copyright 2020-2022 Universidade Federal do Espirito Santo (Ufes)
+# Copyright Universidade Federal do Espirito Santo (Ufes)
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -23,7 +23,7 @@ version: '3.8'
 services:
     # web app
     boca-web:
-        image: ghcr.io/joaofazolo/boca-docker/boca-web
+        image: ghcr.io/joaofazolo/boca-docker/boca-web:latest
         depends_on:
             - boca-db
         deploy:
@@ -40,18 +40,15 @@ services:
                     memory: 512M
             restart_policy:
                 condition: on-failure
-        networks:
-            - frontend
-            - backend
 
     # online judge
     boca-jail:
-        image: ghcr.io/joaofazolo/boca-docker/boca-jail
+        image: ghcr.io/joaofazolo/boca-docker/boca-jail:latest
         depends_on:
             - boca-db
         deploy:
             mode: replicated
-            replicas: 1
+            replicas: 2
             placement:
                 max_replicas_per_node: 8
             resources:
@@ -63,12 +60,9 @@ services:
                     memory: 512M
             restart_policy:
                 condition: on-failure
-        networks:
-            - backend
 
     # database
     boca-db:
-        image: postgres
         deploy:
             mode: global
             placement:
@@ -83,10 +77,3 @@ services:
                     memory: 1024M
             restart_policy:
                 condition: on-failure
-        networks:
-            - backend
-
-networks:
-    frontend: # visible to proxy
-    backend: # hidden from the outside world
-        internal: true
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -1,5 +1,5 @@
 #========================================================================
-# Copyright 2020-2022 Universidade Federal do Espirito Santo (Ufes)
+# Copyright Universidade Federal do Espirito Santo (Ufes)
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -24,7 +24,6 @@ services:
 
     # web app
     boca-web:
-        image: boca-web
         environment:
             # database configuration
             # privileged user password
@@ -33,13 +32,12 @@ services:
             - 8000:80
 
     # online judge
-    boca-jail:
-        image: boca-jail
-
+    # boca-jail:
+
     # database
     boca-db:
-        image: postgres
+        image: postgres:14-alpine
         environment:
             # database configuration
             # privileged user password
-            POSTGRES_PASSWORD: superpass
+            - POSTGRES_PASSWORD=superpass
diff --git a/docker/dev/base/Dockerfile b/docker/dev/base/Dockerfile
@@ -1,5 +1,5 @@
 #========================================================================
-# Copyright 2020-2022 Universidade Federal do Espirito Santo (Ufes)
+# Copyright Universidade Federal do Espirito Santo (Ufes)
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

diff --git a/docker/dev/jail/Dockerfile b/docker/dev/jail/Dockerfile
@@ -1,5 +1,5 @@
 #========================================================================
-# Copyright 2020-2022 Universidade Federal do Espirito Santo (Ufes)
+# Copyright Universidade Federal do Espirito Santo (Ufes)
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by

diff --git a/docker/dev/jail/init.sh b/docker/dev/jail/init.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 #========================================================================
-# Copyright 2020-2022 Universidade Federal do Espirito Santo (Ufes)
+# Copyright Universidade Federal do Espirito Santo (Ufes)
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by