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

Set up environment files:

# Copy example environment files to actual file
cp backend/api/.env.example backend/api/.env
cp backend/storage/.env.example backend/storage/.env
cp backend/periodic-tasks/.env.example backend/periodic-tasks/.env
cp frontend/.env.example frontend/.env
cp shared/.env.example shared/.env
cp tracker/.env.example tracker/.env

Now that the `.env` files are created, all 6 of them need to be modified to use the host name of each Docker container.

Make sure that all environment variables with urls have the correct host and port to the correct container. For example, in any variable named DATABASE_URL, replace localhost with db. In any variable named ARCADIA_API_BASE_URL, replace localhost with backend, etc.

In backend/api/.env, the variable ACTIX_HOST must be set to 0.0.0.0 instead of 127.0.0.1 because the backend won’t listen on the Docker virtual interface otherwise.

In frontend/.env, set VITE_API_BASE_URL to http://127.0.0.1:5173/api. 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.

Start all services:
```
docker compose --env-file backend/api/.env up -d
```
Note: the --env-file option is necessary as it will make the REDIS_PASSWORD environment variable available before the container is ran (and not only for the container itself, it is not the same as the compose attribute env_file).

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:5137
- Backend API: http://localhost:8080/api/

Individual Service Management

If you prefer to start services individually:

Database Only

docker compose up db -d

Redis Only

docker compose --env-file backend/api/.env 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 > 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
cargo sqlx database setup

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