Docker Containers & Orchestration
Relevant source files
The following files were used as context for generating this wiki page:
Archivum is designed as a self-hosted, AI-powered knowledge base that runs entirely within a Docker-orchestrated environment. The system leverages Docker Compose to manage a multi-service stack, ensuring that all components—from the web UI to the vector database—can be deployed with a single command. This architecture prioritizes data privacy by keeping information on the home network and simplifies the deployment of complex AI infrastructure including graph and vector databases.
Sources: archivum-prd-v1.0.md:14-25, README.md:10-15
Service Architecture
The Archivum stack consists of several specialized containers that communicate over a dedicated bridge network. The orchestration is defined in docker-compose.yml, which manages dependencies, environment variables, and health checks to ensure service availability.
Core Services
The following table summarizes the primary services defined in the orchestration layer:
| Service | Image/Context | Default Port | Role |
|---|---|---|---|
| Backend | ./apps/backend | 8000 (Internal) | FastAPI server handling ingestion, search, and wiki CRUD. |
| Frontend | ./apps/frontend | 8473 (Host) | React + Vite web interface. |
| MCP | Dockerfile.mcp | 8001 | Model Context Protocol server for AI agent integration. |
| Qdrant | qdrant/qdrant | 6333 | Vector database for semantic search. |
| Ollama | ollama/ollama | 11434 | Optional service for fully local LLM and embeddings. |
| Caddy | caddy:2-alpine | 80, 443 | Reverse proxy with automatic TLS termination. |
Sources: docker-compose.yml:3-147, README.md:162-171
Service Dependency Flow
The orchestration ensures that services start in the correct order. For instance, the backend depends on qdrant being healthy, and the mcp and caddy services depend on the backend and frontend respectively.
The diagram shows the communication paths and dependency relationships between the containerized services.
Sources: docker-compose.yml:46-48, 98-101, 145-147
Networking and Security
All services are joined to the archivum-net bridge network. This isolated network prevents external access to sensitive components like the vector database or the internal API unless explicitly routed through the Caddy proxy.
Orchestration Security Features
- Non-root Containers: Services are designed to run as non-root users to limit the impact of potential compromises.
- Port Isolation: Qdrant and internal database ports are not exposed to the host by default, accessible only within the internal Docker network.
- Restart Policies: All core services use the
unless-stoppedrestart policy to ensure the stack recovers from system reboots or unexpected crashes. - TLS Termination: Caddy handles automatic TLS via Let's Encrypt for domains specified in the
ARCHIVUM_HOSTenvironment variable.
Sources: archivum-prd-v1.0.md:380-405, docker-compose.yml:158-160, README.md:103-115
Data Persistence and Volumes
Archivum uses named Docker volumes to ensure that user data, wiki content, and database indexes survive container restarts and updates. Markdown files are treated as the canonical source of truth, stored in the wiki_data volume.
| Volume Name | Container Path | Purpose |
|---|---|---|
wiki_data | /data/wiki | Canonical store for Markdown wiki pages. |
raw_data | /data/raw | Original ingested source files (Read-only for most services). |
db_data | /data | SQLite database for auth, metadata, and ingest logs. |
kuzu_data | /data/kuzu | Persistent storage for the embedded graph database. |
qdrant_data | /qdrant/storage | Vector indexes for semantic search. |
caddy_data | /data | TLS certificates and managed site data. |
This diagram illustrates how persistent volumes are mapped from the host system into various containers in the stack.
Sources: docker-compose.yml:149-156, README.md:173-182
Installation and Management
The orchestration is managed through two primary methods: interactive installers and direct Docker Compose commands.
Orchestration Lifecycle
- Configuration: The
install.pyscript orarchivum-cligenerates a.envfile containing API keys and database paths. - Bootstrapping: The system uses
docker-compose.images.ymlby default to pull pre-built images from the GitHub Container Registry (GHCR), avoiding local build times for users. - Execution: The command
docker compose -f docker-compose.yml -f docker-compose.images.yml up -dis used to launch the stack in detached mode.
Key Orchestration Commands
- Start Stack:
docker compose up -d - Stop Stack:
docker compose down - View Logs:
docker compose logs -f backend - Rebuild (Dev):
docker compose up -d --build
Sources: scripts/install.py:330-348, packages/archivum-cli/src/install.js:28-33, README.md:58-65
Conclusion
The Docker-based orchestration of Archivum provides a robust, portable, and secure environment for managing a personal knowledge base. By containerizing complex dependencies like Qdrant and Kuzu, and using Caddy for automated networking, Archivum ensures that non-technical users can deploy a high-performance AI stack with minimal overhead while maintaining complete ownership of their data.