Skip to content

Contributing to Arcane

Set up the Arcane development environment and submit a pull request.

Run Arcane locally and get your change merged. The dev environment runs the frontend and backend in Docker with hot reload.

  • Report bugs using the issue template.
  • Suggest features in Discussions. Proposals and voting happen there; maintainers open linked implementation issues when work is ready.
  • Ask development questions in Discussions.
  • Contribute code (frontend, backend, DevOps), documentation, or testing.
  • Translate via Crowdin. See Translating Arcane.

You need Docker and Docker Compose, just, and Vite+ for the Node toolchain, formatting, linting, and pre-commit hooks outside Docker. Go checks also need Go and golangci-lint on your machine.

Install Vite+:

Terminal window
curl -fsSL https://vite.plus | bash

Run every command from the project root (arcane/) unless stated otherwise.

  1. Fork and clone the repository, then enter it:
Terminal window
git clone https://github.com/getarcaneapp/arcane.git
Terminal window
cd arcane
  1. Check Docker and the Compose config:

    Terminal window
    docker info
    docker compose version
    docker compose -f docker/compose.dev.yaml -p arcane-dev config
  2. Start the development environment. This starts both services with hot reload, installs dependencies inside Docker, and creates persistent storage for dev data.

    Terminal window
    ./scripts/development/dev.sh start
  3. Confirm the stack is up:

    Terminal window
    ./scripts/development/dev.sh status
    curl -f http://localhost:3000
    curl -f http://localhost:3552/api/health
  4. Enable the pre-commit hooks once, so format checks run on staged files:

    Terminal window
    vp hooks enable

Open the project root (arcane/) and install the recommended Docker, Go, and Svelte/TypeScript extensions. Use Ctrl/Cmd+Shift+P → Tasks: Run Task for Start, Stop, Restart, Rebuild, Logs, and Open Frontend. Ctrl/Cmd+Shift+B starts the environment. The Clean task removes the development containers and volumes, including their data.

  1. Create a branch:

    Terminal window
    git switch -c feat/project-labels
    git switch -c fix/issue-123
  2. Edit code. Vite reloads the frontend and Air rebuilds and restarts the backend. Watch logs with ./scripts/development/dev.sh logs, or logs frontend / logs backend for one service.

  3. Format, then lint:

    Terminal window
    just format all
    just lint all

    Fix everything just lint all reports. Frontend formatting and lint rules live in the root vite.config.ts; Go rules live in .golangci.yml.

  4. Run the tests for what you changed, such as just test backend or just test cli.

  5. Commit using Conventional Commits. Types are feat, fix, docs, style, refactor, test, and chore:

    Terminal window
    git commit -m "feat: add user authentication"
    git commit -m "fix: resolve Docker volume mounting issue"

Keep each PR to one feature or fix, link issues with Closes #123 or Fixes #456, and respond to review feedback. Update the documentation if you change APIs or add features. Before you submit, check that:

  • The code builds in the development environment
  • Frontend and backend both run, and hot reload works for each
  • There are no lint errors
  • Commit messages follow the conventional format
  • The PR description explains the change and why it’s needed
Terminal window
./scripts/development/dev.sh start
./scripts/development/dev.sh status
./scripts/development/dev.sh stop
./scripts/development/dev.sh restart
./scripts/development/dev.sh rebuild
./scripts/development/dev.sh logs [frontend|backend]
./scripts/development/dev.sh shell frontend
./scripts/development/dev.sh shell backend

Use restart after config changes and rebuild after dependency changes.

The repository is a Go workspace (go.work) with three modules:

Directory Module path
backend/ getarcane.dev/arcane/v3
cli/ getarcane.dev/cli/v3
types/ getarcane.dev/types/v3

Shared API types live in types/, imported as getarcane.dev/types/v3.

Migrations are Goose Go files in backend/internal/database/migrations, one per schema change.

  1. Add NNNNN_name.go, numbered one past the latest file. Goose reads the version from the filename.
  2. Put raw SQL for SQLite and Postgres in top-level constants. Don’t import GORM, domain packages, or types/.
  3. Register it in init() with goose.AddMigrationContext(run(sqliteUp, postgresUp), run(sqliteDown, postgresDown)). Pass the same constant twice when both dialects match.
  4. Add an up/down test in backend/internal/database/database_test.go.

Version 94 is a baseline equal to Arcane v2.17.1. Older databases upgrade to v2.17.1 first.

just --list shows every target. Common ones:

Task Command
Rebuild and start the Docker dev environment just dev docker
Follow Docker dev logs just dev logs
Run frontend and backend without Docker just dev all
Run a local agent against a manager ARCANE_AGENT_TOKEN=<token> just dev agent
Build the frontend or backend just build single frontend, just build single backend
Run tests just test backend, just test cli, just test e2e
Format and lint just format all, just lint all, just format frontend, just lint backend
Install dependencies just deps install all

Run checks inside the Docker dev environment

Section titled “Run checks inside the Docker dev environment”
Terminal window
docker compose -f docker/compose.dev.yaml -p arcane-dev exec frontend vp -C frontend run check
docker compose -f docker/compose.dev.yaml -p arcane-dev exec backend go vet ./...