OAPI — Otter API

OAPI is the asynchronous Rust API (Axum + Tokio) behind the Antre des Loutres community. It generates Discord and Minecraft profile cards, monitors the community infrastructure, handles Discord authentication and exposes community data stored in PocketBase.

Table of contents

• Features
• Architecture
• Prerequisites
• Getting started
• Configuration
• Usage
• Deployment
• Testing and quality
• Documentation
• Contributing
• License

Features

Architecture

OAPI uses a layered architecture. Each layer only depends on the layers below it.

Static web pages are in public/, front-end tests in tests/, deployment files in deploy/. See docs/architecture.md for details.

External dependencies: PocketBase (data storage), the Discord API (OAuth2, profiles) and the Mojang API (Minecraft skins).

Prerequisites

• Rust stable, 1.85 or later (edition 2024)
• Node.js 18 or later, to run the front-end tests
• A reachable PocketBase instance and its administrator credentials
• A Discord application (client ID, client secret, redirect URL)
• Docker and Docker Compose, for production deployment only

Getting started

git clone https://github.com/matheo-1712/OAPI.git
cd OAPI
cp .env.example .env

Fill in .env (see Environment variables), then start the server:

cargo run

The server listens on http://127.0.0.1:3000 by default.

[!WARNING] Daily tasks are disabled by default and enabled in production by deploy/config.production.yaml. When enabled, they run at startup, including the purge of Discord accounts on the configured PocketBase. See docs/daily_tasks.md.

Configuration

Configuration files

Configuration is loaded in this order, each source overriding the previous one:

1. default_config.yaml: default values and complete structure. Committed.
2. config.yaml: local overrides (host, port, monitored services, roles, scheduler). Ignored by Git. A commented template is created on first run when the file is missing.
3. Environment variables: secrets and environment mode.

See docs/configuration.md for every key.

Environment variables

Defined in .env, see .env.example. Never commit .env.

Usage

API routes are under the /api prefix (configurable with server.routes.base).

Generated images are written to generated_images/, outside public/. They are only served to the profile owner or to an administrator.

Deployment

Production runs with Docker Compose behind a reverse proxy that terminates TLS. The container listens on port 9003 and joins the PocketBase Docker network.

docker compose up -d --build

Production requires OAPI_ENV=production and an HTTPS DISCORD_REDIRECT_URL. Production settings are in deploy/config.production.yaml. The full procedure is in docs/production.md.

Testing and quality

The project follows a zero-warnings policy. CI (.github/workflows/ci.yml) runs formatting, Clippy, tests, release build and a Semgrep scan on every push to master and feat/*, and on every pull request to master.

Run the same checks locally before pushing:

cargo fmt --all -- --check

cargo clippy --all-targets --all-features -- -D warnings

cargo test --all-features

node --test tests/*.test.cjs

Documentation

Documentation is written in French. English versions are available for some pages.

Contributing

1. Create a branch from master named feat/<topic> or fix/<topic>.
2. Add tests for every new feature or bug fix.
3. Make sure all checks in Testing and quality pass.
4. Write commit messages following Conventional Commits (feat(scope): …, fix(scope): …, docs(scope): …).
5. Open a pull request to master.

License

Distributed under the MIT License. See LICENSE.

Maintained by matheo-1712.