Code repository author: Alexandre Harano
Mata-mata is a popular expression for single-elimination tournament in Brazil.
This project provides a simple REST API implementation of single-elimination tournament management with features as creating new tournaments, registering competitors, retrieving the matches lists, win-lose management, and other actions.
Documentation for this project are stored in docs
directory
with a descriptive index.md file
.
asciinema demo from cloning to running the project:
While running the project, it is possible to access the interactive OpenAPI documentation.
This project uses the twelve-factor app methodology.
Environment variables in this project can be stored using a .env
(dot env) file.
For initial setup, a sample is provided as .env.sample
.
However, because the currently recommended way to run this project in development mode relies on
Docker Compose,
it is preferable to adjust the values in
the docker-compose.yml
file.
A description of each of the variables is provided as the following list.
DATABASE_URL
: a string value to be used as an Engine Configuration URL
First, clone this repo:
$ git clone https://github.com/ayharano/matamata.git
After cloning the repository, change the directory to the project root. All instructions below, including configuring the virtual environment and running the project, depend on being in the project root directory.
To maintain consistency between individual commits,
this repo is adopting the use of pre-commit
.
The recommended way to install it for this repo is by installing via pipx
.
After installing pipx
, issue the following commands:
$ pipx install pre-commit
$ pre-commit install --install-hooks --overwrite
pre-commit
is configured to also run per push and pull requests in GitHub workflow.
After installing Docker Compose, open a terminal pointing to the project root and run:
$ docker compose up web
It will launch the FastAPI app using uvicorn backed by a PostgreSQL instance as the app's RDBMS. This way, we don't need local setup of the project, besides the use of Docker containers.
Note that this Docker Compose setup was chosen to facilitate development. An actual deployment of the app in a production environment would require some changes.
One of the configurations to facilitate the development process is to
bind the
migrations
,
tests
and
source code container directories and
some project root files to the Docker host filesystem,
meaning that whenever a change is applied after editing,
they will be instantly replicated within a running container.
The docker-compose.yml
file provides four services:
- Test database container (PostgreSQL 16)
- App database container (PostgreSQL 16)
- Tests container
- Web app container
Tests and Web app containers are built using
a multi-stage build
strategy in a single app.Dockerfile
.
The Test Database PostgreSQL container uses an ephemeral volume to create the storage only during the test suite running.
The App Database PostgreSQL container uses a local postgresql-data
volume to
persist database data between runs.
The base container prepared in app.Dockerfile
has
a non-root user on
a Debian distro instance with
Python 3.12 configured and provides a
virtual environment
with some Python package building/installation dependencies.
Although we don't refer to the base container in the Docker Compose file, it is prepared as a base image for other Python-based containers.
The tests container installs Python packages to run the test suite,
apply the pending migrations in a test database, and
runs the test suite.
It binds the project's
migrations
,
src
,
and
tests
directories, and some project root files within the container.
We established the successful run of the tests suite a requirement for running the Web app container.
The Web app container installs the required Python packages for the FastAPI app to run,
apply the pending migrations in an app database, and
runs the ASGI web server uvicorn
with
this project application.
It binds the project's
migrations
,
and
src
directories, and some project root files within the container.
As we replaced the local development setup of the project to relying on the use of Docker Compose, we have moved and adjusted the previous instructions in a separate document.
Whenever we feel like running the test suite, issue the following command in the project root:
$ docker compose up tests
To run the FastAPI matamata
application, issue the following command in the project root:
$ docker compose up web
The Web app container will run the ASGI web server uvicorn
with
this project application.
By default, it will run on https://127.0.0.1:8000
To access the interactive OpenAPI documentation, just access https://127.0.0.1:8000/docs/
All the client access can be done in the URL that the server is running as the root of the system.
- Python 3.12+
- uvicorn 0.27+
- FastAPI 0.109+
- Pydantic Settings 2.1
- SQLAlchemy 2.0
- SQLAlchemy-Utils 0.41
- Alembic 1.13
- psycopg 3.1
- pytest 7.4
- pytest-cov 4.1
- factory_boy 3.3