Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Developer Setup

Development Containers (Optional)

If you don’t want to install another toolchain on your system, You can also use devcontainers instead. If you don’t know, think of isolated minimal virtual machines that come with the tools required to build Arcadia (or anything else really).

If you have Docker (recommended!) installed and use Visual Studio Code, all you need is to have the Dev Containers extension installed and “reopening your folder in a container”. You can find that option in your Command Palette, or by clicking on the new status bar item in the left bottom corner.

You can also use GitHub Codespaces to build Arcadia in the cloud without having to download anything but streams of text, although it’s not as free as a local dev container.

Open in GitHub Codespaces

It isn’t required to use them but can be useful in some cases (especially if you’re using an immutable OS).

Required Tools

You need these to make meaningful contributions to Arcadia, outside the cases of documentation for example.

  • Prettier for proper formatting of the frontend’s code.
  • sqlx-cli for managing database related stuff, including migrations.
  • Docker for setting up dependencies. Optional but HIGHLY recommended!
  • Insomnia for testing the backend’s API. You could also use any other client if you want.

Configuration Setup

Everything is configured by a single config.yml at the root of the repository. A quick way to get started is cp config.example.yml config.yml: that sample documents every key and is the reference for what each one does.

The one environment variable left: DATABASE_URL

The sqlx query macros check the queries against a real database at compile time, and sqlx only reads DATABASE_URL. It is needed for cargo build, cargo clippy and cargo sqlx prepare, never by the running services. Write it in a .env file at the root of the repository (git ignored), it is picked up from every crate directory:

echo 'DATABASE_URL=postgresql://arcadia:password@localhost:4321/arcadia' > .env

Docker builds don’t need it, they build with SQLX_OFFLINE=true against the committed .sqlx caches.

Building and Running

API

# Build the backend
cargo build -p arcadia-api

# Run the backend binary
./target/debug/arcadia-api

# For optimized builds
cargo build -p arcadia-api --release
./target/release/arcadia-api

Frontend

# Install dependencies
npm install

# Build and run development server
npm run dev

# For production build
npm run build

Development Workflow

Backend Development

# For development with auto-rebuild on changes
cd backend/api
cargo run

# Build and test
cargo build -p arcadia-api
cargo test

# Code quality checks
cargo clippy --fix --allow-dirty
cargo fmt --all

Frontend Development

cd frontend

# Development server with hot reload
npm run dev

# Run tests
npm run test:unit

# Lint and format
npm run lint
npm run format