🎈 boca-docker

What Is BOCA?
Why boca-docker?
Requirements
Quick Start
How To Deploy It To A Swarm
How To Add Custom Configuration
How To Run On Different Ubuntu Release Images
How To Build It (For Development)
How To Publish It
How To Contribute
Known Issues
License
Support

What Is BOCA?

BOCA Online Contest Administrator (known simply as BOCA) is an administration system to held programming contests (e.g., ACM-ICPC, Maratona de Programação da SBC). According to the developers, its main features are portability, concurrency control, multi-site and distributed contests, and a simple web interface (for details refer to https://github.com/cassiopc/boca).

BOCA is implemented mainly in PHP and makes use of a PostgreSQL database in the backend (see architecture below). 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 complex code structuring, which is hard to adapt and to extend.

Why boca-docker?

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 (see illustration below). After quite some reverse engineering, we provide a multi-platform/arch Docker version of BOCA's main components (web app, online automated judge and database) aiming at easing the customization, extensibility and automation of the operational effort required to deploy, run and scale BOCA.

Original architecture	boca-docker architecture

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

Requirements

Install Docker Desktop;
Install Git (only for building and publishing).

Quick Start

Open a Terminal window and make sure the Docker engine is up and running:

# List docker images
docker images -a
# List containers
docker container ls -a

Download the docker-compose.yml and docker-compose.prod.yml files, and place them in the current work directory. Then,
```
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. Find out more information on how to setup a contest here. For general questions about BOCA consider looking at this forum.
To stop the application (considering that the shell is in the same directory):
```
docker compose -f docker-compose.yml -f docker-compose.prod.yml down
```

How To Deploy It To A Swarm

Create the stack (make sure Docker Engine is already running in swarm mode):

docker stack deploy --compose-file docker-compose.yml -c docker-compose.prod.yml boca-stack

Then, check if the stack is running:
```
docker stack services boca-stack
```
Open a web browser and follow the instructions described above;
To bring the stack down:
```
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.

Environment Variables: shows the correct syntax for the various ways one can change predefined configuration values to keep the boca-docker application flexible and organized. See documentation here;
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;
Networking: shows how to add network isolation between services in the boca-docker application. See documentation here;
Volumes: demonstrates how to store data outside the database container, so that the state of the application persists even after the container stops. See documentation here;
Migrations: illustrates how to backup and restore BOCA's database to facilitate migration from one boca-docker instance to another. See documentation here;
Healthcheck: allows a check to be configured in order to determine whether or not the PostgreSQL container is "healthy." This is a particularly neat use case given that the other services depend on that to work. See documentation here;
Multiple Platforms: shows the syntax for selecting an image that matches a specific OS and architecture (alternatively, Docker does that automatically). See documentation here.

How To Run On Different Ubuntu Release Images

To run the boca-docker application built on top of different versions of Ubuntu images, please edit the docker-compose.prod.yml file with an alternative tag from the table below.

Tag name	BOCA version	Ubuntu version	Code name	Architecture
`latest`, `1.2`, `1.2-jammy`, `1.2.2`, `1.2.2-jammy`	1.5	22.04 LTS	Jammy Jellyfish	`amd64`, `arm/v7`, `arm64/v8`, `ppc64le`, `s390x`
`1.2-focal`, `1.2.2-focal`	1.5	20.04 LTS	Focal Fossa	`amd64`, `arm/v7`, `arm64/v8`, `ppc64le`, `s390x`
`nightly`, `nightly-jammy`	1.5	22.04 LTS	Jammy Jellyfish	`amd64`, `arm/v7`, `arm64/v8`, `ppc64le`, `s390x`
`nightly-focal`	1.5	20.04 LTS	Focal Fossa	`amd64`, `arm/v7`, `arm64/v8`, `ppc64le`, `s390x`

For example, to use BOCA version 1.5 running on Ubuntu 20.04 LTS (Focal Fossa) on any supported architecture:

...
services:
  ...

  # web app
  boca-web:
      image: ghcr.io/joaofazolo/boca-docker/boca-web:1.2-focal
  ...

  ...
  # online judge
  boca-jail:
      image: ghcr.io/joaofazolo/boca-docker/boca-jail:1.2-focal
  ...

Deprecated Image Tags

The following image tags have been deprecated and are no longer receiving updates:

1.2.1
1.2.0
1.1.0
1.0.0

How To Build It (For Development)

Clone this repository and set it as your working directory:

git clone https://github.com/joaofazolo/boca-docker.git
cd boca-docker

Then, compose it up with the command below (this might take a while, sit back and relax):
```
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
```
NOTE: Keep in mind that these Docker images are created for and to run on the default platform (i.e. linux/amd64). This works for the majority of development machines and cloud providers versions. To build target-specific or multi-platform Docker images consult the documentation;
Follow the instructions above to set up the application;

To stop it:

docker compose -f docker-compose.yml -f docker-compose.dev.yml down

Alternatively, it is possible to build images without launching the application.

docker build -t boca-base . -f docker/dev/base/Dockerfile
docker build -t boca-web . -f docker/dev/web/Dockerfile
docker build -t boca-jail . -f docker/dev/jail/Dockerfile

How To Publish It

NOTE: These instructions take into account the Docker images generated in the previous section (no multi-platform support).

After building, set the user and image tags accordingly. The IMAGE_ID's will show up with the docker images -a;

docker images -a
# boca-base only necessary for development
# docker tag IMAGE_ID_BOCA_BASE ghcr.io/joaofazolo/boca-docker/boca-base:1.2.2
docker tag IMAGE_ID_BOCA_WEB ghcr.io/joaofazolo/boca-docker/boca-web:1.2.2
docker tag IMAGE_ID_BOCA_JAIL ghcr.io/joaofazolo/boca-docker/boca-jail:1.2.2

Log in into GitHub's Container Registry using your username and personal access token (details here);
```
docker login ghcr.io
```

Push the container images to repository.

# boca-base only necessary for development
# docker push ghcr.io/joaofazolo/boca-docker/boca-base:1.2.2
docker push ghcr.io/joaofazolo/boca-docker/boca-web:1.2.2
docker push ghcr.io/joaofazolo/boca-docker/boca-jail:1.2.2

How To Contribute

If you would like to help contribute to this project, please see CONTRIBUTING.

Before submitting a PR consider building and testing a Docker image locally and checking your code with Super-Linter:

docker run --rm \
           -e ACTIONS_RUNNER_DEBUG=true \
           -e RUN_LOCAL=true \
           --env-file ".github/super-linter.env" \
           -v "$PWD":/tmp/lint \
           ghcr.io/super-linter/super-linter:latest

Known Issues

Rosetta for x86_64/amd64 emulation must be disabled on Apple Silicon (ARM-based chips) for the online automated judge (boca-jail) to work (tested on Apple M1, Docker Desktop 4.28.0, Engine: 25.0.3, Compose: v2.24.6-desktop.1, Mar 2024);

License

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 the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

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

joaofazolo / boca-docker