Maintenance, Backups & Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
Archivum is designed as a self-hosted, local-first system where maintenance focuses on ensuring the integrity of derived data and the availability of local services. Because the system treats Markdown files as the canonical source of truth, most maintenance tasks involve rebuilding derived indexes (Qdrant, Kuzu) or performing health checks to keep the knowledge base clean.
The system utilizes a Docker-based architecture where data persistence is managed through named volumes, ensuring that wiki content, raw uploads, and database states survive container restarts and upgrades. Troubleshooting generally involves inspecting service logs, validating tool schemas via the Model Context Protocol (MCP) inspector, or verifying environment configurations.
Sources: archivum-prd-v1.0.md:15-20, README.md:195-205, Progress.md:10-15
System Maintenance & Index Rebuilding
Archivum maintains several derived data stores that are indexed from the primary Markdown files. If these indexes (Vector or Graph) become corrupted or out of sync, they can be completely rebuilt using the System API.
Index Architecture
The system uses Qdrant for semantic search and Kuzu for graph relationships. The maintenance flow involves clearing these derived stores and re-processing the canonical Markdown files to re-populate them.
The diagram shows how the System API triggers a complete refresh of derived stores from the primary Markdown and SQLite storage.
Sources: apps/backend/archivum/api/system.py:61-75, README.md:195-208
Rebuild Endpoints
A manual rebuild can be triggered via a POST request to the backend. This is necessary if the user manually modifies Markdown files outside of the Archivum editor or if a database migration occurs.
| Endpoint | Method | Description | Role Required |
|---|---|---|---|
/api/rebuild-indexes | POST | Wipes and repopulates Qdrant and Kuzu from Markdown | Owner |
/api/audio-support | GET | Checks status of Whisper and FFmpeg for media ingest | Owner |
Sources: apps/backend/archivum/api/system.py:46-75, README.md:210-213
Wiki Linting & Health Checks
Archivum includes a linting system to identify structural issues within the knowledge base, such as broken wikilinks or orphan pages (pages with no inbound or outbound connections).
Automated Analysis
The linting process scans the Markdown content for [[wikilink]] patterns and cross-references them with the page metadata stored in SQLite.
This sequence illustrates the request-response cycle for generating a wiki health report.
Sources: apps/backend/archivum/api/system.py:84-89, apps/frontend/src/pages/LintPage.tsx:18-30
Issue Types and Resolutions
The system categorizes linting issues and provides mechanisms for automated or manual fixes.
| Issue Type | Description | Resolution Strategy |
|---|---|---|
broken_wikilink | Reference to a slug that does not exist. | API replaces link with plain text or valid slug. |
orphan_page | A page with zero inbound or outbound links. | Manual fix: Add link or delete page. |
contradictory_claims | (MCP Only) Logic inconsistencies detected by LLM. | Manual review of flagged content. |
Sources: apps/backend/archivum/api/system.py:100-120, apps/backend/archivum/mcp/server.py:182-195, apps/frontend/src/pages/LintPage.tsx:75-125
Backups & Data Persistence
Archivum adheres to a "local-first" storage philosophy. All data is persisted in Docker volumes, which must be backed up to ensure recovery.
Storage Locations
If running via the standard docker-compose.yml, data is distributed across specific volumes:
| Store | Purpose | Backup Priority |
|---|---|---|
wiki_data | Canonical Markdown wiki pages | CRITICAL |
raw_data | Original source files (PDFs, images, etc.) | HIGH |
db_data | SQLite database (Auth, Metadata, Logs) | HIGH |
kuzu_data | Graph relationships | MEDIUM (Derived) |
qdrant_data | Vector embeddings | MEDIUM (Derived) |
Sources: README.md:195-205, archivum-prd-v1.0.md:275-285
Cleanup Operations
The uninstall.sh script provides options for selective data removal. By default, it preserves volumes, but they can be wiped using specific flags:
--volumes: Deletes all wiki data, raw uploads, and database volumes.--images: Removes locally built Docker images.--files: Removes the installation directory.
Sources: README.md:86-100
Troubleshooting & Debugging
Troubleshooting Archivum involves validating environment variables, checking container logs, and verifying the MCP server connectivity.
Logging
Logs are the primary tool for diagnosing ingest failures or API errors. Use the following commands to inspect service activity:
# View backend ingestion and API logs
docker compose logs -f backend
# View MCP server activity (stdio/SSE interactions)
docker compose logs -f mcp
Sources: README.md:220-225, apps/backend/archivum/mcp/server.py:40-50
Dependency Verification
For media features (audio/video transcription), specific system dependencies are required. The system API can diagnose missing components:
# Diagnostics from apps/backend/archivum/api/system.py:20-35
"dependencies": {
"openai_whisper": whisper_available, # Requires 'audio' extra
"ffmpeg": ffmpeg_available, # Requires system-level install
}
Sources: apps/backend/archivum/api/system.py:20-40
MCP Validation
If AI clients (like Claude Desktop or Cursor) cannot connect, the MCP Inspector should be used to validate the server transports:
- stdio:
npx @modelcontextprotocol/inspector --cli ... - SSE:
npx @modelcontextprotocol/inspector http://127.0.0.1:8001/sse
Sources: README.md:265-275, archivum-prd-v1.0.md:250-260
Summary
Maintenance in Archivum is simplified by the reliance on Markdown as the source of truth. Most operational issues can be resolved by rebuilding derived indexes via the System API or performing linting checks to resolve broken links. Data integrity is maintained through Docker volumes, and troubleshooting focuses on log inspection and dependency validation for advanced features like media ingestion.