Network, HTTPS, & Custom Domains
Relevant source files
The following files were used as context for generating this wiki page:
Archivum is designed as a self-hosted, local-first knowledge base that prioritizes data privacy while allowing for flexible remote access. The networking architecture leverages a tiered security model, using Docker bridge networking for internal service communication and Caddy as a reverse proxy for external traffic management and automatic TLS termination.
The system supports three primary access methods: direct LAN access for local devices, Tailscale for authenticated remote access without port forwarding, and token-gated Cloudflare Tunnels for public sharing of specific wiki content. This architecture ensures that sensitive data remains within the home network unless explicitly shared.
Sources: archivum-prd-v1.0.md:435-442, README.md:275-285
Internal Service Architecture
Archivum utilizes a Docker Compose stack where all services are connected via a bridge network, typically named wiki-net or archivum-net. This prevents direct exposure of backend databases to the host machine or external network.
Service Ports and Roles
| Service | Internal Port | Host Port (Default) | Role |
|---|---|---|---|
| Web UI | 8080 | 8473 | React + Vite frontend interface. |
| REST API | 8000 | 8000 | Ingestion, search, and wiki CRUD operations. |
| MCP Server | 8001 | 8001 | SSE and stdio transport for AI agents. |
| Qdrant | 6333 | 6333 (Optional) | Vector database for semantic search. |
| Neo4j | 7474 | 7474 (Optional) | Graph database for relationship storage. |
| Caddy | 80, 443 | 80, 443 | Reverse proxy and TLS manager. |
Sources: archivum-prd-v1.0.md:377-385, README.md:275-285
Networking Flow Diagram
The following diagram illustrates the flow of a user request through the Caddy reverse proxy to the internal services.
The Caddy proxy acts as the single entry point for all HTTP/HTTPS traffic, routing requests based on path and hostname.
Sources: archivum-prd-v1.0.md:377-385, README.md:275-285
HTTPS and TLS Configuration
Archivum uses Caddy to handle automatic HTTPS. When a custom domain is configured via the ARCHIVUM_HOST environment variable, Caddy automatically provisions and renews TLS certificates via Let's Encrypt.
Implementation Requirements
- Hostname: Set
ARCHIVUM_HOSTin the.envfile to your registered domain. - Contact Email: The
Caddyfilemust be updated with a valid email address to satisfy Let's Encrypt requirements. - Port Access: Ports 80 (for ACME HTTP-01 challenges) and 443 (for HTTPS traffic) must be reachable from the internet.
Sources: README.md:154-167, README.md:195-200
DNS Setup
To enable external access, users must configure A records at their DNS provider:
| Record Name | Type | Target | Purpose |
|---|---|---|---|
yourdomain.com | A | Public IP | Main access to the Wiki UI and API. |
share.yourdomain.com | A | Public IP | Dedicated subdomain for token-gated share links. |
Sources: README.md:172-182
Remote Access and Security Layers
The networking model follows a zero-trust approach for remote connections, utilizing three distinct layers of access.
The diagram shows how different user roles are routed through specific network layers to ensure security.
1. Tailscale Network
Tailscale provides a secure VPN layer. It allows the owner and invited guests to reach Archivum via its stable Tailscale IP without modifying home router settings or port forwarding. This provides full access to the UI, API, and MCP server.
Sources: archivum-prd-v1.0.md:435-442, archivum-prd-v1.0.md:444-448
2. Cloudflare Tunnel
For sharing wiki content with the public without opening inbound firewall ports, Archivum supports Cloudflare Tunnels. This layer is scoped to a specific subdomain (e.g., share.archivum.dev) and is restricted to read-only views of specific pages or query results.
Sources: archivum-prd-v1.0.md:449-450, README.md:243-261
3. LAN Direct
On the local home network, users can access the system directly via the host machine's local IP or localhost. This is typically used for initial setup and management.
Sources: archivum-prd-v1.0.md:435-442
Public Publishing & Share Subdomains
Archivum supports public publishing through three modes: Page Share Links, Query Permalinks, and Public Wiki.
- Token-Gated Access: Share links use unguessable 32-byte URL-safe base64 tokens (
/share/{token}). - Restricted Rendering: The share subdomain only serves paths matching
/share/*,/public*,/api/share/*, and/api/public/*. All other paths return a 404 error to prevent unauthorized access to the editor or administrative settings. - Security Controls: Public pages are sanitized using DOMPurify (client-side) and
bleach(server-side) to prevent XSS.
Sources: archivum-prd-v1.0.md:520-530, README.md:204-208, apps/frontend/src/pages/PublicWikiPage.tsx:64-70
Configuration Summary
The following environment variables control networking and publishing behavior:
| Variable | Default | Description |
|---|---|---|
ARCHIVUM_HOST | localhost | The public hostname used by Caddy for TLS. |
MCP_PORT | 8001 | The port the MCP server binds to for SSE. |
ARCHIVUM_FRONTEND_PORT | 8473 | The host port mapped to the frontend container. |
PUBLIC_WIKI_ENABLED | false | Enables the /public and /api/public/pages endpoints. |
Sources: README.md:129-148, apps/backend/archivum/mcp/server.py:35-40
Conclusion
Archivum's networking architecture provides a balance between the convenience of cloud-like sharing and the security of self-hosted infrastructure. By utilizing Caddy for automatic TLS and supporting private VPN layers like Tailscale, it ensures that a user's knowledge base remains protected while remaining accessible across devices and through controlled public links.