Installation & Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
Archivum is a self-hosted, AI-powered knowledge base designed to run on home servers via Docker. The primary goal of the installation process is to provide a "one-command" setup that boots a full stack, including a Web UI, REST API, and Model Context Protocol (MCP) server. The system is architected to ensure that all data remains local, leveraging Docker volumes for persistence across updates.
The installation facilitates the transition from manual knowledge management to an automated, agent-led workflow. Once installed, Archivum allows users to ingest various file formats and URLs, which an AI agent then processes into markdown wiki pages, semantic embeddings, and graph relationships.
Sources: README.md:1-12, archivum-prd-v1.0.md:15-28
Server Installation Methods
Archivum provides multiple paths for installation depending on the user's environment and level of technical requirement.
One-Command Bootstrap
The recommended path for Linux, macOS, and Windows users is the bootstrap script, which automates the environment check (Node.js and Docker), downloads runtime files to ~/archivum, and launches the guided setup.
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/pranavkannepalli/archivum/main/scripts/bootstrap.sh | bash
# Windows PowerShell
irm https://raw.githubusercontent.com/pranavkannepalli/archivum/main/scripts/bootstrap.ps1 | iex
Sources: README.md:20-36
Manual Docker Deployment
Users can manually clone the repository and use Docker Compose to bring up the services. This requires manual configuration of the .env file with necessary API keys and secrets.
git clone https://github.com/pranavkannepalli/archivum.git
cd archivum
cp .env.example .env
docker compose -f docker-compose.yml -f docker-compose.images.yml up -d --no-build
Sources: README.md:73-78
Installation Workflow
The following diagram illustrates the sequence of actions performed by the automated installation scripts to initialize the Archivum environment.
The workflow ensures that all dependencies are met before attempting to pull images or start the application stack.
Sources: README.md:25-32
Core Service Architecture
Upon successful installation, Archivum exposes several endpoints for different interaction modes. The stack is segmented into frontend, backend, and specialized indexing services.
| Service | Container Name | Port | Description |
|---|---|---|---|
| Web UI | archivum-frontend | 80 / 8473 | React + Vite interface with CodeMirror 6 editor. |
| REST API | archivum-backend | 8000 | FastAPI backend for ingestion, search, and CRUD. |
| MCP Server | archivum-mcp | 8001 | SSE/stdio server for AI client integrations. |
| Vector DB | archivum-qdrant | 6333 | Qdrant for semantic search embeddings. |
| Proxy | archivum-caddy | 443 / 80 | Caddy for TLS termination and reverse proxy. |
Sources: README.md:189-204, archivum-prd-v1.0.md:383-392
Initial Configuration
Configuration is primarily handled via environment variables in the .env file. These variables define LLM providers, security secrets, and database paths.
Essential Variables
ANTHROPIC_API_KEY: Required for extraction and synthesis if using Anthropic.JWT_SECRET: Used for signing authentication tokens.OWNER_PASSWORD: Sets the initial admin password.MCP_API_KEY: Bearer token for secure MCP server access.
Sources: README.md:131-140
Local LLM Support
For users requiring fully local operations, Archivum supports Ollama. Setting LLM_EXTRACTION_PROVIDER, LLM_SYNTHESIS_PROVIDER, and EMBED_PROVIDER to ollama redirects all AI processing to a local instance.
Sources: README.md:143-150, archivum-prd-v1.0.md:836-840
MCP Client Setup
A key feature of Archivum is its built-in MCP server, which allows external AI agents (like Claude Desktop, Cursor, or Windsurf) to interact with the knowledge base.
Integration Flow
The following sequence diagram shows how an external AI client interacts with the Archivum MCP server to retrieve information from the wiki.
This flow enables agents to perform semantic search and retrieval without direct access to the database files.
Sources: apps/backend/archivum/mcp/server.py:53-65, README.md:227-248
Local Development Setup
Developers can run Archivum without building full Docker images by using uv for Python services and running the frontend via npm.
Backend Development
- Start Qdrant:
docker compose up -d qdrant - Install dependencies:
uv sync - Run FastAPI:
uv run uvicorn archivum.main:app --reload
Frontend Development
- Navigate to
apps/frontend - Install:
npm install - Run:
npm run dev
Sources: README.md:104-129
Maintenance & Uninstallation
Archivum includes scripts for updating the stack and performing clean removals while preserving data volumes by default.
- Update:
./update.shpulls new images and restarts the stack while preserving.envand volumes. - Uninstall:
./uninstall.shremoves containers. Use flags like--volumesto delete all data or--imagesto remove local images.
Sources: README.md:61-71, README.md:92-100
Final knowledge base integrity can be maintained via the lint_wiki tool, which checks for broken wikilinks and orphan pages.
Sources: apps/backend/archivum/mcp/server.py:157-178, Progress.md:27