Skip to content

TheArchiver — Setup

Self-hosted, plugin-based web content archiver. Saves web pages, Reddit posts, GitHub repos, news articles, videos, and more via a simple API call or browser share sheet. Runs as a Docker container on LXC 129 (archival) alongside Ladder, Byparr, and browserless. Auth via oauth2-proxy + PocketID.

Infrastructure

Host LXC ID Internal External CPU RAM Disk
Debian LXC 129 192.168.1.129:3002 https://archiver.eva-00.network 3 cores (shared) 4 GiB (shared) 16 GiB

Storage Layout

Data Location Notes
SQLite DB + app data /opt/the-archiver/data (local rootfs) Fast I/O for database
Downloaded/archived content /mnt/archiver/downloads (urahara bind mount) Growth-prone, bulk storage
Plugins /opt/the-archiver/plugins (local rootfs) Community + custom plugins

Proxmox bind mount: /mnt/pve/urahara/archiver/downloads -> /mnt/archiver/downloads

Architecture

                    +-------------------+
                    |  the-archiver     |
  Port 3002 (web)   |  (Next.js + SQLite)|
  <----------------->  /data volume     |
                    |  /downloads vol   |
                    |  /plugins vol     |
                    +-------------------+
                             |
              oauth2-proxy on LXC 119:8594
                             |
              Caddy (archiver.eva-00.network)

TheArchiver is a single-container deployment — no external database or Redis required. The plugin system uses drop-in TypeScript modules matched by URL pattern. Community plugins are installable from the Plugins tab in the UI.

Key Features

  • Dashboard with real-time queue monitoring via SSE
  • REST API for programmatic URL submission
  • Plugin system with community marketplace
  • Scheduled archiving with cron expressions
  • File browser with video thumbnails and previews
  • ntfy push notifications on completion/failure
  • PWA support (add to iOS/Android home screen)

Observability

Logs

Container logs collected via Alloy Docker discovery, shipped to Loki.

Query Purpose
{container_name="the-archiver"} All app logs
{container_name="the-archiver"} \|= "error" Errors only
{container_name="the-archiver"} \|= "download" Download activity

Access: Grafana -> Explore -> Loki -> Enter query

IaC

Artifact Path
Playbook ansible/playbooks/archival.yml
Workflow .forgejo/workflows/archival.yml
Docker Compose services/the-archiver/docker-compose.yml
Caddy entry services/caddy/Caddyfile -> archiver.eva-00.network
Glance entry services/glance/glance.yml -> Knowledge section
OAuth2 proxy services/external-proxies/docker-compose.yml -> port 8594

The archival playbook deploys TheArchiver alongside Ladder, Byparr, and browserless on the same LXC.

Auth

Component Details
Auth method oauth2-proxy on LXC 119 (port 8594)
OIDC Provider PocketID (auth.eva-00.network)
Callback URL https://archiver.eva-00.network/oauth2/callback
PocketID Client ID 9455f710-20b7-4fbc-a9ad-d47e8bfb3d2b
API bypass /api/download is excluded from auth (--skip-auth-regex)

TheArchiver has no built-in authentication. Web UI access is gated by oauth2-proxy. The /api/download endpoint is open for iOS Shortcut and automation use.

Secrets

Vault path: secret/data/external-oauth2-proxies (shared)

Key Purpose
archiver_client_id PocketID OIDC client ID
archiver_client_secret PocketID OIDC client secret
archiver_cookie_secret oauth2-proxy cookie encryption key

Environment Variables

Variable Value Purpose
DOWNLOAD_LOCATION /downloads Root archive directory (urahara mount)
NTFY_URL http://192.168.1.119:2586/archiver Push notifications

Plugin System

Plugins extend TheArchiver with custom download handlers matched by URL pattern. When a URL is submitted, enabled plugins are checked in priority order — first match handles the download.

Installing Plugins

  1. Community Marketplace: Plugins tab -> Community -> Browse and install
  2. ZIP Upload: Plugins tab -> Import .zip file
  3. Manual: Place plugin folder in /opt/the-archiver/plugins/ on LXC 129

Plugin Capabilities

  • Custom file browser views (e.g., Reddit-style layout for social media)
  • File preview handlers for unsupported types
  • Custom thumbnail rendering
  • Per-plugin settings in the Settings UI

API Reference

Submit URL for Archiving

# POST with JSON body
curl -X POST https://archiver.eva-00.network/api/download \
  -H "Content-Type: application/json" \
  -d '{"url": "https://reddit.com/r/selfhosted/comments/..."}'

# GET with query parameter
curl "https://archiver.eva-00.network/api/download?url=https://example.com"

Other Endpoints

Method Path Purpose
GET / Health check (200 = OK)
GET /api/queue List pending downloads
GET /api/history Download history
GET /api/failed List failures
POST /api/failed/:id/retry Retry failed download
GET /api/files?path=... Browse downloaded files
GET /api/schedules List scheduled downloads
POST /api/schedules Create scheduled download
GET /api/settings Retrieve settings
GET /api/plugins List installed plugins

iOS Shortcut

Create an Apple Shortcut to archive URLs from the iOS/macOS Share Sheet:

Setup Steps

  1. Open the Shortcuts app
  2. Create a new Shortcut
  3. Tap Add Action and search for URL
  4. Set the URL to: https://archiver.eva-00.network/api/download
  5. Add a Get Contents of URL action:
  6. Method: POST
  7. Headers: Content-Type = application/json
  8. Request Body: JSON
  9. Add key url with value Shortcut Input
  10. (Optional) Add a Show Notification action to confirm
  11. Tap the Share Sheet toggle to enable receiving URLs
  12. Name it "Archive" or "Save to Archiver"

Usage

From Safari, YouTube, Reddit, or any app: tap Share -> Archive. The URL is sent to TheArchiver and appears in the queue.

No authentication is needed — the /api/download endpoint bypasses oauth2-proxy.

Notifications

TheArchiver sends push notifications via ntfy to the archiver topic at http://192.168.1.119:2586/archiver. Subscribe in the ntfy app or at https://ntfy.eva-00.network/archiver to receive download completion and failure alerts.

Forgejo Mirror

The upstream repository is mirrored to Forgejo for local reference:

  • TheArchiver: https://git.eva-00.network/mirrors/TheArchiver
  • Community Plugins: https://git.eva-00.network/mirrors/TheArchiver-CommunityPlugins

Mirrors auto-sync from GitHub every 8 hours.