Quick start

This guide starts the pinned Arkivra release candidate, PostgreSQL, and the required Docling document parser with Docker Compose. The generator can bundle Docling or connect Arkivra to an existing bare-metal, containerized, or remote service.

Prerequisites

Docker Engine with Docker Compose
OpenSSL
enough memory and CPU for Docling, or an existing Docling Serve endpoint reachable from Docker
enough disk space for PostgreSQL, uploaded files, extracted assets, and backups

The public image is ghcr.io/jasnan/arkivra:0.1.0-rc.1 and can be pulled from GitHub Container Registry without authentication.

Prepare the deployment

Create a private deployment directory:
Terminal window
```
mkdir arkivra && cd arkivra
umask 077
```
Use the Compose generator to set the public URL, choose where Docling runs, and download compose.yaml plus a generated .env file. The default bundles the tested Docling CPU image:
```
ARKIVRA_PUBLIC_URL=http://localhost:3210
ARKIVRA_DOCLING_URL=http://docling:5001
```
To use an existing Docling instance instead, select that option and enter the URL visible from inside the Arkivra container. Docling is required for document parsing and full-text search even when AI is not configured.

The generator writes the basic settings to .env. It creates the PostgreSQL password, authentication secret, and file-encryption key locally in your browser and never displays them or puts them in the Compose preview.
Keep both files in the private deployment directory. Do not print, share, or commit .env.
Terminal window
```
chmod 600 .env
```
Use the exact HTTPS origin served by your reverse proxy for a non-local deployment. The Docling URL must be reachable from inside the Arkivra container; it may be an internal DNS name, another Compose service name, or a hosted endpoint.
If Docling is running on the Docker host rather than on the internal Compose network, use a host address reachable from Docker. host.docker.internal is available by default in Docker Desktop but may need an explicit host-gateway mapping on Linux. Apple Silicon users can follow the Arkivra Docling companion repository for a native MLX/MPS setup and optional VLM configuration.

Start and verify Arkivra

Validate the interpolated configuration without printing or sharing its output:
Terminal window
```
docker compose config --quiet
```

Pull and start the services:

docker compose pull
docker compose up -d
docker compose ps

Check Arkivra:
Terminal window
```
curl http://localhost:3210/api/health
```
Open http://localhost:3210, register the first account, and sign in. When no active administrator exists, Arkivra promotes the oldest registered user after that user reaches an authenticated API route.

Database migrations run automatically before the web process starts. With the default generator choices, the expected result is healthy PostgreSQL, Docling, and Arkivra services.

Upload a test document

Open Vaults and create a vault.
Open the vault and select Upload → Upload files.
Choose a supported, non-empty document.
Open the transfers drawer to watch the upload, then wait for processing to complete.
Open Search and search for a phrase from the document.

If the upload completes but processing fails, verify that Docling is reachable from inside the Arkivra container. See Document processing and Maintenance and troubleshooting.

Before storing important documents

put Arkivra behind a trusted TLS reverse proxy and keep the default loopback bind when the proxy runs on the Docker host;
close public registration after creating the accounts you need;
configure SMTP before requiring email verification or relying on invitations and password resets;
create a backup and test the restore procedure;
preserve PostgreSQL, the Arkivra data volume or host directory, and the deployment secrets.

Continue with First steps for the main document workflow or Using Docker Compose for the deployment layout and update procedure.

Crafted with care by Jasnan Thachaparamban