Docker Setup

This guide will help you get Arcadia running quickly using Docker Compose.

Prerequisites

Docker and Docker Compose installed
Git (to clone the repository)

If running docker compose doesn’t work, you may have an older version of the docker cli installed and may need to use docker-compose instead.

Also don’t forget to use sudo if you aren’t in the docker group!

Quick Setup

Configuration:
```
cp config.example.yml config.yml
```

The template is written for a local setup. Every key that must change under Docker carries a docker: note right above it, giving the value to use: inside the Docker network the services reach each other by container name (db, redis, tracker, …) rather than by localhost. Apply all of them.

api.host must be 0.0.0.0 and not 127.0.0.1, otherwise the backend won’t listen on the Docker virtual interface.

frontend.api_base_url must be http://127.0.0.1:5173. CORS in the browser won’t allow requests to a different host or port from within the frontend file server. The file frontend/docker/nginx.conf forwards api requests to the backend container.

The frontend section is inlined in the frontend bundle when its image is built, so changing it requires docker compose build frontend.

Start all services:
```
docker compose up -d
```
This command will:
- Build the backend and frontend images
- Start PostgreSQL database
- Run database migrations automatically
- Start the backend API server
- Start the frontend development server
Access the application:
- Frontend: http://localhost:5173
- Backend API: http://localhost:8080/api/

The backend and the tracker are built without optimizations, which keeps the builds short. Pass --build-arg PRODUCTION_BUILD=true to build them in release mode.

Individual Service Management

If you prefer to start services individually:

Database Only

docker compose up db -d

Redis Only

docker compose up redis -d

Backend Api Only

docker compose up backend -d

Frontend Only

docker compose up frontend -d

Development Features

Auto-rebuild with Compose Watch

For development, you can use Compose Watch to automatically rebuild when source code changes:

docker compose up --watch

Or when running attached (without -d), press W to enable watch mode.

Adding Test Data

You can optionally add “fake” data (fixtures) to the database for development:

docker exec -i arcadia_db psql -U arcadia -d arcadia < backend/storage/migrations/fixtures/fixtures.sql

The default test user is picolo with password test.

Exporting Test Data

If you added some new test data and wish to include it in your commit, you can export it like so:

docker exec -i arcadia_db pg_dump -U arcadia -d arcadia --data-only --inserts --column-inserts > backend/storage/migrations/fixtures/fixtures.sql && sed -i '/SELECT pg_catalog.set_config(\x27search_path\x27, \x27\x27, false);/d' migrations/fixtures/fixtures.sql

1 line generated by pgdump must be removed as it prevents the collage_entry fixtures from being inserted (the trigger somehow can’t be interprted). If someone has an explanation, please let us know/open a PR!

Manual Database Setup (if needed)

Arcadia automatically runs migrations on launch, but if you need to manually set up the database:

cargo install sqlx-cli
DATABASE_URL=postgresql://arcadia:password@localhost:4321/arcadia cargo sqlx database setup

sqlx-cli only reads DATABASE_URL, it does not know about config.yml. Use the credentials of the database section, with the port published on the host (4321 by default).

Troubleshooting

If services fail to start, check logs with: docker compose logs [service-name]
To rebuild images: docker compose build
To reset everything: docker compose down -v && docker compose up -d

Keyboard shortcuts

Arcadia Documentation