Skip to content

Installation

Requirements

  • A machine that stays on: a home server, a NAS, a Raspberry Pi 4 or 5, a virtual machine. The image exists for amd64 and arm64.
  • Docker with Compose, or Podman with podman compose.
  • About 125 MB to download, 350 MB on disk, plus your documents. The image includes Tesseract (about 100 MB), the program that reads identity documents.
  • Arca listens on port 8000, on plain HTTP: reach it on your local network, or put an HTTPS reverse proxy in front (see below).

Install with Docker

Pick the latest version among the repository's tags, for example v0.1.0:

mkdir arca && cd arca
curl -fsSLO https://gitlab.com/r0d0lphe/arca/-/raw/v0.1.0/compose.yaml
curl -fsSL -o .env https://gitlab.com/r0d0lphe/arca/-/raw/v0.1.0/.env.example

Edit .env before the first start:

  • ARCA_SECRET_KEY: generate it with python3 -c "import secrets; print(secrets.token_urlsafe(50))". It contains no $, which Compose would expand, truncating the key.
  • ARCA_ALLOWED_HOSTS: the names or addresses you type to reach Arca (arca.lan,192.168.1.20).
  • ARCA_TIME_ZONE: your time zone (Europe/Paris); it decides what today is.

Every setting is described in Configuration. Then start Arca and create your account:

docker compose up -d
docker compose exec arca python manage.py createsuperuser

Open http://<address>:8000, sign in, then follow First steps. Data (database and documents) lives in the arca-data volume, backups in arca-backups. At each start the container applies database migrations and runs a quick integrity check.

Turn backups on right away in Backups and keep the recovery key: see Automatic backups. Data and documents are not encrypted on the disk: read Security and privacy.

Podman works the same way: use podman instead of docker.

Install from source

With Docker, from a clone, build the image yourself:

git clone https://gitlab.com/r0d0lphe/arca.git arca && cd arca
cp .env.example .env
export COMPOSE_FILE=compose.yaml:compose.build.yaml
docker compose up -d --build

Keep COMPOSE_FILE set for every docker compose command in that directory (in your shell profile, or as a line of .env). It replaces the automatic compose.override.yaml: if you use one, add it to the list.

Without Docker:

uv sync
export ARCA_SECRET_KEY=… ARCA_ALLOWED_HOSTS=… ARCA_DATA_DIR=/path/to/data
uv run manage.py migrate
uv run manage.py createsuperuser
uv run --group docs mkdocs build      # this documentation
uv run manage.py collectstatic --noinput
uv run gunicorn config.wsgi --bind 0.0.0.0:8000

Reading identity documents from a photo needs the Tesseract program, which the Docker image includes. From source it is optional: install it with apt install tesseract-ocr (Debian, Ubuntu) or pacman -S tesseract tesseract-data-eng (Arch). Without it, Quick add works as before, with no photo screen; the Integrity page says so. Arca brings its own English model for Tesseract, so the reading is the same on every system.

Arca reads no .env file outside Docker: export the variables in the service that starts it.

Behind an HTTPS reverse proxy

To publish Arca through a reverse proxy (Pangolin, Traefik, Caddy, nginx…), keep Arca on plain HTTP inside your network and set:

ARCA_HTTPS=1
ARCA_CSRF_TRUSTED_ORIGINS=https://arca.example.org
ARCA_ALLOWED_HOSTS=arca.example.org
ARCA_TRUSTED_PROXIES=172.18.0.1

The proxy must send the X-Forwarded-Proto and X-Forwarded-For headers (most do). ARCA_TRUSTED_PROXIES is the address the proxy connects from, so that failed logins are counted per client: see Login security. Before making Arca reachable from the Internet, go through the checklist of Security and privacy.

Update

With Docker:

docker compose pull
docker compose up -d

With a pinned ARCA_VERSION, change it in .env first. Built from a clone: git pull, then docker compose up -d --build (with COMPOSE_FILE as above).

Migrations are applied when the container starts and only go forward: to go back to an older version, restore a backup made before the update (see Restore).

From source:

git pull
uv sync
uv run manage.py migrate
uv run --group docs mkdocs build
uv run manage.py collectstatic --noinput

then restart the service that runs gunicorn.

Run uv run manage.py extract_texts once: it reads the text of PDF documents saved before, so the search finds them.