We picked these apps for technical usefulness rather than GitHub stars, and we have tried to be straightforward about the trade-offs. One habit worth keeping throughout: a public VPS does not mean an app should accept anonymous users. Several entries belong behind authentication, HTTPS, or another access-control layer.

The short list is: Vaultwarden for passwords, Paperless-ngx for documents, FreshRSS for feeds, Forgejo for Git, Umami for analytics, changedetection.io for page monitoring, ntfy for push notifications, SearXNG for private metasearch, Actual for budget synchronization, and linkding for bookmarks.

How these self-hosted apps were selected

We checked every project as of July 19, 2026 against five requirements: active maintenance, an open-source license verified in the canonical repository, an official Docker or self-host installation path, a reason to run continuously on an Internet-connected host, and an operational caveat worth planning around. “Best” here means the app clears those filters and earns its keep on an always-on server, with trade-offs we can explain honestly. The ten apps are listed in no particular order.

Awesome-Selfhosted was the discovery baseline. As of July 19, 2026, it contained 1,249 software entries across 94 categories, including 698 Docker-tagged entries; its GitHub repository had about 306,462 stars when checked. Use the recommended HTML catalog for browsing. The GitHub Markdown list is generated and retained as a legacy interface.

Those numbers describe the catalog as a whole; a listing is a discovery signal, not a security audit or a deployment endorsement. License labels can also lag canonical sources. As of the same July 19, 2026 check, Vaultwarden is listed there as GPL-3.0 although its repository declares AGPL-3.0, while Forgejo is listed as MIT although its canonical Codeberg repository uses GPL-3.0-or-later. Those mislabels are why we verified each license at the source.

Quick comparison

The table describes workload shape rather than invented RAM minimums. A mostly idle service can become busy with many users, aggressive polling, large imports, or long retention.

1. Vaultwarden: password synchronization

Vaultwarden gives individuals, families, and small teams a lightweight sync server for the Bitwarden clients they already use. It is an unofficial implementation of the Bitwarden client API, not a Bitwarden, Inc. product. Choose the official Bitwarden server when exact upstream behavior, formal support, or organizational compliance takes priority.

The current license is AGPL-3.0. Its official installation path supports a single application container through Docker, Podman, or Compose, normally behind an HTTPS reverse proxy. Mobile, desktop, browser, and CLI clients can all reach one stable VPS endpoint without opening a home network.

Treat the server as a high-value target. Disable open registration when it is unnecessary, protect the admin interface and token, enable MFA where appropriate, and keep the image current. Backups need the database, attachments, and configuration rather than a copy of the disposable container. The Vaultwarden Docker tutorial walks through registration lockdown, client synchronization, SQLite-safe backup, and an isolated restore test.

2. Paperless-ngx: searchable document storage

Paperless-ngx watches an inbox, runs OCR, applies metadata, and makes scanned paperwork searchable from different devices. That processing can continue on an always-on VPS while your laptop is offline.

The project uses GPL-3.0. Its official setup guide recommends Docker Compose, with the web application, a Redis-compatible broker, and a database as distinct responsibilities. Current guidance recommends PostgreSQL for new installations. Tika and Gotenberg are optional additions for relevant Office document formats.

OCR and conversion create short CPU and memory bursts, while originals and indexes create lasting storage pressure. The harder issue is trust: Paperless-ngx states that documents are stored in clear text and should not run on an untrusted host. Use authenticated HTTPS, harden the host, restrict administrative access, and encrypt backup destinations. Decide whether the VPS operator, host configuration, and recovery copies are suitable before uploading identity, tax, medical, or legal records. A local server is the safer fit when that trust requirement cannot be met. The Paperless-ngx Docker Compose guide works through PostgreSQL setup, a real OCR acceptance test, and an empty same-version restore.

3. FreshRSS: an always-on feed reader

FreshRSS keeps polling feeds after your personal devices go to sleep. It also synchronizes subscriptions, read state, and favorites across browsers and compatible mobile clients. Publishers that support WebSub can deliver updates directly.

FreshRSS is AGPL-3.0, and the project maintains an official Docker deployment. It is a PHP application with a choice of SQLite, PostgreSQL, MariaDB, or MySQL. Small private installs can keep the shape simple; larger ones can move the database out of the app container.

Feed count, refresh frequency, full-text scraping, and retention drive load. Schedule refresh jobs deliberately, watch slow or failed sources, and avoid hammering publishers. Database and configuration backups matter more than container backups. Use the FreshRSS Docker guide to configure the private first-run path and refresh scheduler.

4. Forgejo: Git hosting for a small team

Webhooks need a reachable endpoint, and Git over SSH or HTTPS benefits from a stable hostname. Forgejo supplies both, alongside repositories, issues, pull requests, packages, and releases for a developer or small team.

The canonical license is GPL-3.0-or-later. Forgejo provides an official container installation and can start with SQLite or use an external database. The server may be modest when traffic is low, but repository history, Git LFS objects, packages, release files, and Actions artifacts can fill NVMe storage much sooner than the web interface suggests.

Forgejo Actions runners are separate from the server. They execute workflow code and need their own isolation, patching, capacity, and trust policy. Do not size the forge as if runners were free background threads. Disable public registration unless you are prepared to handle spam and abuse. The Forgejo Docker guide keeps server deployment separate from runner trust decisions.

5. Umami: web analytics on your own collector

Every site measured by Umami sends events to its collection endpoint. Hosting that endpoint on an always-on VPS gives several sites one reachable collector and one operator-controlled dashboard.

Umami has an MIT license. Its installation guide covers Docker Compose and prebuilt images, but this is not a single-container database-free service. PostgreSQL is required, and current documentation specifies PostgreSQL 12.14 or newer and recommends UTC.

Event volume, data retention, bot traffic, and report queries determine database growth and load. Set retention with storage in mind, back up PostgreSQL consistently, and monitor ingestion rather than judging capacity from dashboard activity. Self-hosting controls where the collector runs; it does not remove privacy, consent, or data-retention obligations. The Umami Docker deployment pairs PostgreSQL backup and restore with a tested reverse-proxy path.

6. changedetection.io: scheduled page monitoring

Price, stock, policy, and content pages rarely change on your schedule. changedetection.io checks them on its own schedule and can send results to browser extensions, notification services, or API integrations. A VPS supplies the continuous scheduler and outbound Internet access.

The project is Apache-2.0, with official Docker and Compose instructions. Basic HTML fetches are relatively simple. JavaScript-heavy targets may need WebDriver, Playwright, or the recommended browser service, which adds Chromium processes and much more variable CPU and memory use.

Network behavior is often the limiting factor. Target sites may rate-limit or block a data center IP, and more compute will not fix that. Set sensible intervals, respect target policies, and do not turn the service into an aggressive scraper. If optional AI summaries are enabled, monitored content is sent to the configured external AI provider, so review that data flow before using it on private pages. Start with the plain HTTP fetcher in the changedetection.io Docker Compose guide and add browser automation only when a target requires it.

7. ntfy: HTTP push notifications

A backup job can send one HTTP request to ntfy, and a subscribed phone or browser can receive the result. The same small interface works for cron, CI, monitoring, and home automation. Hosting it on a VPS makes it reachable across otherwise separate networks.

ntfy is dual-licensed under Apache-2.0 and GPL-2.0. The official self-hosting guide supports a compact Go server, with SQLite used by default for persistence.

The easy publish model can also be dangerously open. A guessable topic name is not access control. Configure authentication, deny-by-default permissions where appropriate, HTTPS, rate limits, and persistent volumes. Retained messages and attachments consume disk and monthly transfer. Default SQLite storage is single-writer, so it should not be presented as a horizontally scalable cluster. The ntfy Docker guide starts from a closed access policy.

8. SearXNG: private metasearch with external dependencies

SearXNG aggregates results from multiple search sources; it does not build an independent web index. A private VPS instance keeps the interface and its preferences available across your devices.

SearXNG uses AGPL-3.0, and the project publishes an official container installation. Run it as an authenticated private service. An unrestricted domain invites bot traffic, raises the chance that upstream engines classify the VPS address as abusive, and may violate a provider’s acceptable-use rules.

Queries still go to upstream engines. Those services can return CAPTCHAs, throttle requests, or block data center IPs, so self-hosting does not remove the external dependency. The official limiter uses Valkey and helps control inbound bots, but it cannot guarantee acceptance by an upstream provider or replace access control. The private SearXNG Docker Compose deployment puts Caddy authentication in front of Valkey-backed limiting and exact trusted-proxy handling.

9. Actual: private budget synchronization

Actual is local-first, but its server lets devices and users synchronize a budget without leaving one laptop online. End-to-end encryption is optional, requires a second password, and must be enabled separately for each budget. The VPS is a private sync endpoint, not a public finance portal or a business accounting system.

Actual has an MIT license and an official Docker installation path. Put the server behind a correctly configured reverse proxy with HTTPS, enable authentication and end-to-end encryption for each budget, keep it updated, and test backups. Exposing its raw application port is not a finished deployment.

Financial records increase the cost of a weak setup. Protect credentials, restrict access where practical, and verify that a restored server can reopen and synchronize the budget. Bank-sync tokens are stored separately from budget data and are not covered by Actual’s end-to-end encryption; a server administrator or hosting provider with database access can read them. If your only device already provides enough local-first functionality, the extra Internet-facing service may not be worth maintaining. In the Actual Budget Docker Compose guide, server login, optional budget E2EE, two-client sync, and full-state recovery remain distinct tests.

10. linkding: centralized bookmarks

Bookmarks become more useful when the same searchable collection follows you between browsers and devices. linkding provides that endpoint for extensions, a bookmarklet, REST clients, and mobile apps. It is small enough to operate without turning bookmark capture into an infrastructure project.

The project is MIT-licensed. Its installation guide covers Docker, Compose, user creation, persistent storage, and reverse-proxy setup. SQLite is the default and PostgreSQL is available.

The basic deployment is straightforward, but the latest-plus image adds Chromium-based page archiving. That image is larger, browser processes use more memory, and saved snapshots make disk consumption grow with the collection. Back up the persistent database and archived assets rather than the replaceable container. If full archival is the primary job, a dedicated archive system may be a better fit than turning every bookmark into a snapshot. The linkding Docker Compose guide combines a private administrator bootstrap with application backups, isolated recovery, and tested egress blocks.

Why some popular self-hosted apps are absent

Home Assistant is usually most useful near local radios, sensors, and household devices. A VPS can host parts of the stack, but moving the primary controller away from the LAN adds dependence on the Internet path and complicates local hardware access.

Pi-hole and AdGuard Home are DNS resolvers first. Running one on a VPS can work only for clients reached through a deliberately restricted private-access design, but exposing an open recursive resolver is an abuse and amplification risk. A VPS-first recommendation needs complete access controls and resolver safeguards, not a public port 53 recipe.

Jellyfin and Immich are dominated by media storage, upload and download transfer, thumbnail or transcoding work, and sometimes GPU requirements. A storage-oriented home server or dedicated media host is often a better match than a general-purpose VPS with a monthly transfer quota.

Nextcloud can run well on a VPS, but it brings a larger operations footprint: database tuning, caching, background jobs, upgrades, file locking, storage growth, and recovery planning. It deserves a dedicated architecture guide rather than a casual place in a compact VPS-first list.

Shared deployment rules

Put each public web interface behind a maintained reverse proxy with valid TLS. Bind internal application and database ports to localhost or a private container network. Disable open registration unless it is intentional, use unique credentials, and enable MFA where the app supports it.

Container updates still require judgment. Pin stable versions or review release notes before automated updates, and keep a rollback path. Back up application data, databases, uploads, encryption material, and configuration. A running container does not prove that its data can be restored.

Watch disk growth in the places each app creates durable data: document originals, Git objects, analytics events, notification attachments, and page archives. Observe real CPU and memory use during OCR or browser automation before setting tight container limits. Apps that fetch arbitrary URLs also need outbound controls and protection against requests to internal metadata or private services.

Choosing VPS resources and location

Application count is a poor sizing metric. Workload shape, concurrency, retained data, and failure tolerance matter more. A few mostly idle private services behave differently from PostgreSQL analytics ingestion, document OCR, Chromium fetchers, or an Actions runner, even if both deployments contain the same number of containers.

For a few of the lighter services here, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is a comfortable starting point. Add heavier jobs such as OCR, Chromium fetchers, or analytics ingestion and Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB) buys useful headroom, while Max (4 vCPU, 16 GB RAM, 160 GB NVMe, 4 TB) suits a fuller stack. Measure the heaviest jobs, watch how durable data grows, and keep an eye on monthly transfer if you host analytics collection, attachments, package hosting, or large Git operations.

Every plan includes daily backups, a 1 Gbps port, and full root access. Our VPS plans are unmanaged, so you run Linux, Docker, TLS, and the applications yourself and keep full control. Treat the daily backups as a safety net: pair them with application-consistent database dumps, off-server copies, and the occasional restore test.

Choose Tokyo or Singapore based on the people, websites, and upstream APIs that will use the service. If your users are in mainland China, it is worth a few minutes on the Tokyo Looking Glass and Singapore Looking Glass from their access networks. We carry the three major mainland carriers over CTGNet (formerly China Telecom CN2 GIA, AS23764 / AS4809), China Unicom Premium (CUP, AS9929 / AS10099), and China Mobile International N2 (CMIN2, AS58807), and the best judge of any route is a test of the actual path at the hours that matter to you.

When you have a feel for the workload, compare it against Riven Cloud pricing. Start with the service whose failure you can recover from, confirm its backup restore, then add the next one. An app earns its place when its always-on benefit is worth its biggest caveat.

This guide deploys Actual Budget 26.7.0, the current release when we checked on July 18, 2026, from the official Docker Hub image on a Debian or Ubuntu VPS. Docker publishes port 5006 only on loopback. You set the server password through an SSH tunnel before Caddy exposes budget.example.com, then test a real budget from two clients.

Prerequisites

You need:

• a Debian or Ubuntu VPS with root or sudo access;
• an A record for budget.example.com pointing to the VPS, plus an AAAA record only when IPv6 is configured and filtered correctly;
• TCP 80 and 443 open for Caddy, along with your administrative SSH port;
• a modern browser on two devices, or two isolated browser profiles;
• encrypted storage outside the VPS for budget exports and server backups.

First install Docker Engine and the Compose plugin. Docker’s convenience script is the fastest route; if running a downloaded script as root is against your policy, your distribution’s packages work too. Then add Caddy and UFW:

curl -fsSL https://get.docker.com | sudo bash
sudo docker compose version

sudo apt update
sudo apt install -y caddy ufw

Allow SSH before enabling the firewall. Replace port 22 if the host uses another administrative SSH port; our guide to securing SSH on a VPS covers moving the port and hardening logins without locking yourself out:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Mirror those inbound rules in any provider firewall. Do not open port 5006 publicly.

Create the Actual Budget Compose project

The official Docker configuration runs one actual-server service, mounts /data, and uses node scripts/health-check.js as its health check. The file below keeps that health check and adds a pinned version, a loopback-only host port, and log rotation.

As of the 26.7.0 image (checked July 18, 2026), the image creates an actual account with UID/GID 1001, but its OCI configuration does not select that account, so the container runs as root by default; a later image may change this, so recheck after upgrades. Create a root-owned data directory to match. Do not add user: "1001:1001" until you have proved that startup, writes, upgrades, backup, and restore all work under that override.

sudo install -d -m 750 /opt/actual
sudo install -d -m 750 /opt/actual/actual-data
cd /opt/actual

Create /opt/actual/compose.yaml:

sudo tee compose.yaml > /dev/null <<'YAML'
services:
  actual_server:
    image: docker.io/actualbudget/actual-server:26.7.0
    container_name: actual-server
    restart: unless-stopped
    ports:
      - "127.0.0.1:5006:5006"
    volumes:
      - ./actual-data:/data
    healthcheck:
      test: ["CMD-SHELL", "node scripts/health-check.js"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 20s
    logging:
      options:
        max-size: "10m"
        max-file: "3"
YAML

/data/server-files/account.sqlite stores the hashed server password, sessions, and the server’s budget-file registry. Budget blobs live under /data/user-files. The server configuration reference documents those paths and the supported environment variables. Keeping the defaults puts the whole server state under one mount.

Start it and check the listener:

cd /opt/actual
sudo docker compose up -d --wait --wait-timeout 120
curl -fsS http://127.0.0.1:5006/health
sudo ss -lntp | grep ':5006'

The health endpoint should return {"status":"UP"}, and the listener must show 127.0.0.1:5006, not 0.0.0.0:5006 or [::]:5006.

Initialize the password through an SSH tunnel

An uninitialized Actual server asks the first visitor to set its server password. Do that privately before adding a public Caddy route.

From your workstation, open a tunnel and leave it running:

ssh -N -L 5006:127.0.0.1:5006 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:5006. Set a long, unique server password and store it in a password manager. This is the login password for the server, not an end-to-end encryption password.

Sign out, reload the page, and sign in again. Also try a wrong password. If the original setup screen reappears or the wrong password works, check the actual-data ownership and container logs before continuing.

The official password reset procedure runs a script inside the container, which means anyone with root or Docker access can reset the server authentication boundary. Limit administrative access to the VPS accordingly.

Add Caddy without replacing Actual’s security headers

Actual needs HTTPS and cross-origin isolation for the SharedArrayBuffer used by its browser-side SQLite engine. The server sets these response headers itself:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

The official reverse-proxy guide warns that duplicate COOP or COEP headers can cause a fatal SharedArrayBufferMissing error. Caddy passes the upstream headers through, so use a plain reverse proxy and do not add another copy.

Create the site after the private password test has passed. Keep site snippets in a separate imported file so adding Actual does not erase other Caddy hosts; the conditional import appends the top-level import only when the main file lacks it:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/actual.caddy > /dev/null <<'CADDY'
budget.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:5006
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Caddy obtains and renews the certificate once DNS and both firewalls allow TCP 80/443. Check the public path and the headers:

curl -fsS https://budget.example.com/health
curl -fsSI https://budget.example.com/ | grep -i '^cross-origin'

The header check should print exactly one Cross-Origin-Opener-Policy: same-origin and one Cross-Origin-Embedder-Policy: require-corp. Open the browser console and confirm there is no SharedArrayBufferMissing error.

Prove budget creation and two-client sync

A healthy endpoint proves that Node can answer a request. It does not prove that a budget can be written, downloaded, decrypted, or synchronized.

In the first browser:

1. Sign in at https://budget.example.com.
2. Create a budget named VPS restore test.
3. Add an account named Checking test with an opening balance of 1,000.
4. Add a transaction for 12.34 with payee Compose test and a note containing today’s date.
5. Wait for the sync indicator to settle, then reload and confirm the balance and transaction remain.

Open a private window, a separate browser profile, or a second device with no Actual local storage. Sign in to the same server, select the cloud budget, and let it download. Confirm the account, exact transaction amount, payee, note, and resulting balance.

Make a second change from that client, such as changing the note to Second client sync works. Wait for sync, return to the first client, and confirm the edit arrives. Avoid simultaneous edits to the same field during this acceptance test. Actual supports concurrent clients, but a deterministic test is easier to diagnose.

Decide whether to enable budget encryption

Actual’s sync documentation describes optional end-to-end encryption per budget. Enabling it creates a second password that should differ from the server login password. The client encrypts budget data before upload, and each new device needs that second password once to derive the key.

Four boundaries matter:

• Encryption is optional and applies per budget, not automatically to every file on the server.
• It cannot be switched off in place. Returning to an unencrypted file requires an export and import.
• If every local copy is gone and the encryption password is forgotten, the budget cannot be recovered. A device that still has a local copy may reset sync and create a new key.
• Local browser or desktop data remains unencrypted. Use full-disk encryption on every client device.

If you enable encryption, open the budget settings, choose Enable encryption, save the second password separately, and repeat the clean second-client download. The second client must ask for the encryption password and then show the same transaction.

Bank sync has a different trust boundary. Actual’s bank-sync documentation states that API keys, secrets, and bank-sync tokens are stored on the server, outside budget E2EE. A server administrator, hosting provider, or attacker with direct database access can read them. Keep those credentials out of Compose files, shell history, screenshots, and tickets, and encrypt backups that may contain them. Actual also requires the user to trigger bank sync; this guide does not assume an unattended schedule.

Export each budget and back up all of /data

Actual provides a portable application backup. Open each budget, go to its settings, choose Export Data, and save the Actual ZIP. The official backup and restore guides use that ZIP for import into a new budget. Export every budget separately and keep the old budget until the imported copy has been checked.

The ZIP is not the complete server. A stopped archive of /data also covers authentication, sessions, the server’s file registry, all budget blobs, and server-side bank-sync state. Take both.

Create a consistent archive with Actual stopped:

cd /opt/actual
sudo install -d -m 700 /var/backups/actual
archive="/var/backups/actual/actual-$(date +%F-%H%M%S).tar.gz"

sudo docker compose stop actual_server
sudo tar --numeric-owner --xattrs --acls -C /opt/actual \
  -czf "$archive" actual-data compose.yaml
sudo docker compose start actual_server

sudo chmod 600 "$archive"
sudo sha256sum "$archive" | sudo tee "$archive.sha256" > /dev/null
sudo chmod 600 "$archive.sha256"
curl -fsS --retry 12 --retry-delay 5 --retry-all-errors \
  http://127.0.0.1:5006/health

Encrypt the archive and the ZIP exports, then copy them off the VPS. A backup that exists only on the same disk is not a disaster-recovery copy.

Restore the same version in isolation

Test the archive without touching production. The drill below verifies the checksum, extracts into a fresh directory, and runs a separate Compose project on loopback port 15006 with an internal Docker network that has no external route. That last control keeps the restored server from contacting real bank-sync providers.

BACKUP=$(ls -1 /var/backups/actual/actual-*.tar.gz | sort | tail -n 1)
sudo sha256sum -c "$BACKUP.sha256"

restore_dir="/opt/actual-restore-$(date +%Y%m%d%H%M%S)"
sudo install -d -m 700 "$restore_dir"
sudo tar --numeric-owner --xattrs --acls -C "$restore_dir" -xzf "$BACKUP"
cd "$restore_dir"

Create compose.restore.yaml in that directory:

services:
  actual_server:
    image: docker.io/actualbudget/actual-server:26.7.0
    ports:
      - "127.0.0.1:15006:5006"
    volumes:
      - ./actual-data:/data
    healthcheck:
      test: ["CMD-SHELL", "node scripts/health-check.js"]
      interval: 20s
      timeout: 10s
      retries: 6
      start_period: 20s
    networks:
      - restore_only
    restart: "no"

networks:
  restore_only:
    internal: true

Start only the isolated copy:

sudo docker compose -p actual-restore \
  -f compose.restore.yaml up -d --wait --wait-timeout 180
curl -fsS http://127.0.0.1:15006/health

Tunnel workstation port 15006 to the restored listener, sign in, open VPS restore test, and verify the known balance and transaction. If E2EE is enabled, supply its separate password. Do not click Bank Sync; the internal network should make any accidental provider connection fail, but restraint is still part of the test.

Also import one application ZIP as a new budget and compare accounts, balances, categories, and transactions. That proves both recovery paths. Tear down the isolated project after recording the result:

sudo docker compose -p actual-restore -f compose.restore.yaml down

Upgrade with a data-aware rollback

Read the Actual release notes before changing versions. Export every budget, take a stopped full backup, and complete the isolated restore first. Then replace the version tag in compose.yaml with the reviewed target:

cd /opt/actual
sudo docker compose pull actual_server
sudo docker compose up -d --wait --wait-timeout 180
curl -fsS https://budget.example.com/health
curl -fsS https://budget.example.com/info

The info endpoint should report the new version. Repeat login, budget opening, a new transaction, and second-client sync, and check the COOP and COEP headers again. Actual may migrate budget or server data during an upgrade, so switching the image back is not a complete rollback. If the upgrade fails, stop the new container, keep the upgraded /data for diagnosis, and restore the old 26.7.0 image definition together with the pre-upgrade /data archive. Start that matched pair and rerun the acceptance test.

Choosing a Riven Cloud VPS for Actual Budget

Actual Budget is a light workload. For a household or small-team budget server, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is plenty, with room left over for a couple of other small containers. Step up to Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB transfer) or Max (4 vCPU, 16 GB RAM, 160 GB NVMe, 4 TB transfer) if you plan to co-host heavier services (our best self-hosted apps guide has candidates worth pairing with a budget server) or want more space for years of budgets and backup archives on the same disk.

Every plan has a 1 Gbps port, full root access, and a choice of Tokyo or Singapore, so pick the location closest to the people who open and sync budgets. If you connect from mainland China, it is worth a minute to run the Tokyo Looking Glass and Singapore Looking Glass from your own carrier before deciding. The Riven Cloud VPS pricing page has the current plan details.

Our plans are unmanaged, so you run the stack yourself and keep full control, and every plan includes daily backups on our side. Those cover whole-host recovery nicely; keep the per-budget ZIP exports, the stopped /data archive, and the restore drill above in your routine as well, since application-level recovery is the part only you can test.

Security limits and non-fit cases

Keep port 5006 on loopback, patch the host and container, restrict Docker access, and monitor failed logins and disk usage. Use unique server and E2EE passwords. Treat bank tokens and every full backup as financial secrets. Do not co-host Actual with untrusted containers that get the Docker socket or broad access to /opt/actual.

Self-hosting Actual works best when someone clearly owns TLS, updates, monitoring, encrypted off-server backups, and restore tests. If your situation calls for managed key custody, audited access controls, high availability, or a contractual SLA, a hosted service with the right bank-integration model will serve you better; optional budget E2EE does not make bank credentials unreadable to the server operator, so it cannot stand in for that kind of control.

The stack follows the official core plus Valkey architecture and pins the official SearXNG image tag 2026.7.13-9e25585ae. Caddy adds TLS and bcrypt-backed Basic authentication. Only Caddy publishes host ports; SearXNG port 8080 and Valkey port 6379 stay inside a fixed Docker subnet.

The limiter needs accurate client addresses and Valkey state, but it only shapes request behavior after authentication; deciding who may use the service stays Caddy’s job.

Prepare the VPS and DNS

You need a Debian or Ubuntu VPS with root or sudo access, an A record for search.example.com, and an AAAA record only when IPv6 works end to end. TCP 80 and 443 must reach the VPS for Caddy. Keep the administrative SSH port open, and leave 8080 and 6379 closed in UFW, security groups, and the provider firewall; only Caddy needs to be reachable from outside.

Install Docker Engine and the Compose plugin with Docker’s convenience script (inspect it first if that worries you; on a tightly managed host, use your distribution’s packages instead), then confirm the domain resolves:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo bash get-docker.sh
sudo docker compose version
getent ahosts search.example.com

The sudo docker compose version check above is the only privileged docker call in this guide; the later docker commands run unprivileged, so add your user to the docker group (sudo usermod -aG docker $USER, then log out and back in) or run them with sudo yourself.

If UFW is active, retain its working SSH rule and add only the public web ports:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

The old searxng/searxng-docker repository is archived, so skip it for a new deployment. As of July 18, 2026, the maintained container template lives in the SearXNG core repository and defines core plus valkey.

Generate the configuration and secret

Create a private project directory, an application secret, and a Caddy password hash. SearXNG’s entrypoint generates a random secret when it creates a missing settings.yml; because this setup supplies its own settings file, it sets SEARXNG_SECRET explicitly. The Caddy password lives only in a transient shell variable, and .env stores the bcrypt hash rather than the plaintext.

sudo install -d -m 750 -o "$USER" -g "$USER" /opt/searxng
cd /opt/searxng
umask 077
install -d -m 700 core-config
read -rp 'Private SearXNG username: ' SEARCH_USER
case "$SEARCH_USER" in
  ''|*[!A-Za-z0-9._-]*)
    echo 'Use only letters, digits, dot, underscore, or hyphen' >&2
    exit 1
    ;;
esac
read -rsp 'Private SearXNG password: ' SEARCH_PASSWORD
printf '\n'
SEARCH_PASSWORD_HASH=$(docker run --rm \
  caddy:2-alpine \
  caddy hash-password --algorithm bcrypt --plaintext "$SEARCH_PASSWORD")
unset SEARCH_PASSWORD
{
  printf 'SEARXNG_SECRET=%s\n' "$(openssl rand -hex 32)"
  printf 'SEARCH_USER=%s\n' "$SEARCH_USER"
  printf "SEARCH_PASSWORD_HASH='%s'\n" "$SEARCH_PASSWORD_HASH"
  printf '%s\n' \
    'SEARXNG_BASE_URL=https://search.example.com/' \
    'SEARXNG_BIND_ADDRESS=0.0.0.0' \
    'SEARXNG_PORT=8080' \
    'SEARXNG_LIMITER=true' \
    'SEARXNG_PUBLIC_INSTANCE=false' \
    'SEARXNG_IMAGE_PROXY=true' \
    'SEARXNG_VALKEY_URL=valkey://valkey:6379/0'
} > .env
chmod 600 .env
unset SEARCH_USER SEARCH_PASSWORD_HASH

Keep the secret and bcrypt hash unchanged across ordinary restarts and restores, and keep .env out of tickets, shell transcripts, and repositories. SearXNG’s server settings reference documents the server overrides. SEARXNG_PUBLIC_INSTANCE=false matches this authenticated deployment; access control comes from Caddy, not that flag.

Create /opt/searxng/core-config/settings.yml:

use_default_settings: true

Create /opt/searxng/core-config/limiter.toml:

[botdetection]
ipv4_prefix = 32
ipv6_prefix = 48
trusted_proxies = [
  "172.30.0.2/32"
]

[botdetection.ip_limit]
filter_link_local = false
link_token = true

[botdetection.ip_lists]
block_ip = []
pass_ip = []
pass_searxng_org = true

The limiter documentation explains how SearXNG walks forwarded addresses past trusted proxies. The /32 trusts only Caddy’s fixed address inside the private 172.30.0.0/24 proxy subnet. Trusting every RFC1918 range would allow another container or an accidentally exposed proxy to supply a forged client address. Add a pass_ip only for a monitored source you control; passed addresses also skip other bot checks.

Create the core, Valkey, and Caddy services

Create /opt/searxng/Caddyfile:

search.example.com {
    encode zstd gzip
    basic_auth {
        {$SEARCH_USER} {$SEARCH_PASSWORD_HASH}
    }
    reverse_proxy core:8080
}

Caddy is not part of the official SearXNG Compose template; this integration relies on its documented automatic HTTPS and reverse proxy behavior. Caddy sets the forwarded host, scheme, and client chain and ignores spoofed incoming forwarded values by default.

Create /opt/searxng/compose.yml:

services:
  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    environment:
      SEARCH_USER: ${SEARCH_USER}
      SEARCH_PASSWORD_HASH: ${SEARCH_PASSWORD_HASH}
    networks:
      proxy:
        ipv4_address: 172.30.0.2

  core:
    image: searxng/searxng:2026.7.13-9e25585ae
    env_file:
      - ./.env
    volumes:
      - ./core-config:/etc/searxng
      - core-data:/var/cache/searxng
    networks:
      proxy:
        ipv4_address: 172.30.0.3
    depends_on:
      valkey:
        condition: service_healthy
    restart: unless-stopped

  valkey:
    image: valkey/valkey:9-alpine
    command: valkey-server --save 30 1 --loglevel warning
    volumes:
      - valkey-data:/data
    networks:
      proxy:
        ipv4_address: 172.30.0.4
    healthcheck:
      test: ["CMD", "valkey-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 6
    restart: unless-stopped

networks:
  proxy:
    ipam:
      config:
        - subnet: 172.30.0.0/24

volumes:
  core-data:
  valkey-data:
  caddy-data:
  caddy-config:

The SearXNG service has no ports entry. Valkey has neither ports nor a password because only containers on this project network can reach it; publishing 6379 would break that boundary. The core service loads the whole mode-600 .env file through env_file, which is where it gets SEARXNG_SECRET. Caddy deliberately does not: its environment block passes only the username and bcrypt hash, which Compose interpolates from the same .env in the project directory, so the application secret never enters the Caddy container. Basic credentials are safe in transit only over TLS, so do not publish an HTTP-only route.

Start the deployment and inspect all three services:

cd /opt/searxng
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100 core valkey caddy

Test Valkey, TLS, search, and the limiter

Read the credentials, then check the state service and the authenticated HTTPS path:

cd /opt/searxng
SEARCH_USER=$(sed -n 's/^SEARCH_USER=//p' .env)
read -rsp 'Private SearXNG password: ' SEARCH_PASSWORD
printf '\n'
docker compose exec valkey valkey-cli ping
curl -fsSI -u "$SEARCH_USER:$SEARCH_PASSWORD" https://search.example.com/

Valkey must return PONG and the authenticated request must succeed. Next, prove that an unauthenticated request is refused and that Docker has not opened the private ports on the host:

curl -sS -o /dev/null -w '%{http_code}\n' https://search.example.com/
sudo ss -lntp | grep -E ':(8080|6379)\b'

The first command must print 401; the second must print nothing.

The default output format is HTML, so test with a real search rather than a JSON endpoint. Send browser-like headers and require at least one rendered result:

curl -fsS \
  -u "$SEARCH_USER:$SEARCH_PASSWORD" \
  -A 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/126 Safari/537.36' \
  -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
  -H 'Accept-Language: en-US,en;q=0.8' \
  -H 'Accept-Encoding: gzip, deflate, br' \
  --compressed \
  --data-urlencode 'q=SearXNG metasearch' \
  https://search.example.com/search \
  -o /tmp/searxng-search.html
grep -q '<article class="result ' /tmp/searxng-search.html
rm /tmp/searxng-search.html

Repeat the search in a real browser and open one result. If the page fills with engine errors, the search did not really succeed; the error messages and logs will tell you why.

Now send an intentionally bot-like burst. The limiter checks more than request counts, including request headers and user-agent behavior, so exact rejection timing depends on the current limiter.toml:

for request in $(seq 1 20); do
  curl -sS -o /dev/null -w '%{http_code}\n' \
    -u "$SEARCH_USER:$SEARCH_PASSWORD" \
    -A 'curl/limiter-test' \
    'https://search.example.com/search?q=limiter-test'
done | sort | uniq -c

docker compose logs --since=10m core valkey caddy | \
  grep -Ei 'limiter|bot|429|403|valkey|error' || true
unset SEARCH_PASSWORD

The burst should produce blocked responses, commonly 403 or 429, while the browser-like search stays usable. If every request appears to come from 172.30.0.2, stop and fix trusted_proxies; raising limits would only hide the proxy error. Check the logs for Valkey connection failures. The limiter is not access control: it can throttle an accepted request, but only Caddy’s authentication decides whether a request reaches SearXNG.

Understand the privacy boundary

SearXNG’s own-instance documentation explains that it does not forward a user’s cookies to search engines and presents generated request profiles. The selected upstream engines still receive the search terms because they need the query to return results. They normally see the VPS exit IP instead of the user’s IP.

A private instance used by one person can still be linkable through its stable exit address, timing, and query content. Multiple authenticated users send more queries from one data-center IP and may trigger upstream rate limits, CAPTCHA challenges, or an IP block; SearXNG cannot promise that every engine stays available. And to repeat the house rule from the top: please keep Tor, relay, and open-proxy functionality off this deployment, as our AUP does not allow them.

Back up configuration and both data volumes

SearXNG has no application-level backup tool. This procedure follows its documented persistent paths and Docker’s volume backup guidance. It stops the whole project so the core cache and the Valkey snapshot belong to one recovery point:

cd /opt/searxng
umask 077
install -d -m 700 backups
core_volume=$(docker inspect -f \
  '{{range .Mounts}}{{if eq .Destination "/var/cache/searxng"}}{{.Name}}{{end}}{{end}}' \
  "$(docker compose ps -q core)")
valkey_volume=$(docker inspect -f \
  '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Name}}{{end}}{{end}}' \
  "$(docker compose ps -q valkey)")
stamp=$(date +%F-%H%M%S)

docker compose stop
sudo tar -czf "backups/searxng-config-$stamp.tar.gz" \
  compose.yml Caddyfile .env core-config
docker run --rm -v "$core_volume:/source:ro" -v "$PWD/backups:/backup" \
  alpine:3.22 \
  tar -C /source -czf "/backup/searxng-core-$stamp.tar.gz" .
docker run --rm -v "$valkey_volume:/source:ro" -v "$PWD/backups:/backup" \
  alpine:3.22 \
  tar -C /source -czf "/backup/searxng-valkey-$stamp.tar.gz" .
docker compose start

sudo chown "$USER":"$USER" backups/*"$stamp"*
chmod 600 backups/*"$stamp"*
sha256sum backups/*"$stamp".tar.gz > "backups/searxng-$stamp.sha256"

The configuration archive contains SEARXNG_SECRET, so encrypt all three archives and copy them off the VPS. Back up Caddy’s caddy-data volume too if you want to preserve its certificate state, and steer clear of docker compose down -v around these volumes; the -v flag deletes them.

Rehearse an isolated same-version restore

Use a disposable VPS when possible. The same-host drill below uses timestamped names for its directory, network, containers, and volumes, never joins the production Caddy, and starts the same image versions that produced the backup. Keep the commands and the later cleanup in one shell.

cd /opt/searxng
config_archive=$(ls -1 /opt/searxng/backups/searxng-config-*.tar.gz | sort | tail -n 1)
backup_stamp=$(basename "$config_archive" .tar.gz)
backup_stamp=${backup_stamp#searxng-config-}
sha256sum -c "backups/searxng-$backup_stamp.sha256"

restore_id="$(date +%Y%m%d%H%M%S)"
restore_dir="/opt/searxng-restore-$restore_id"
sudo install -d -m 700 -o "$USER" -g "$USER" "$restore_dir"
cd "$restore_dir"
tar -xzf "$config_archive"
docker network create "searxng-restore-$restore_id"
docker volume create "searxng-restore-core-$restore_id"
docker volume create "searxng-restore-valkey-$restore_id"

docker run --rm -v "searxng-restore-core-$restore_id:/restore" \
  -v /opt/searxng/backups:/backup:ro \
  alpine:3.22 \
  tar -C /restore -xzf "/backup/searxng-core-$backup_stamp.tar.gz"
docker run --rm -v "searxng-restore-valkey-$restore_id:/restore" \
  -v /opt/searxng/backups:/backup:ro \
  alpine:3.22 \
  tar -C /restore -xzf "/backup/searxng-valkey-$backup_stamp.tar.gz"

docker run -d --name "searxng-restore-valkey-$restore_id" \
  --network "searxng-restore-$restore_id" --network-alias valkey \
  -v "searxng-restore-valkey-$restore_id:/data" \
  valkey/valkey:9-alpine \
  valkey-server --save 30 1 --loglevel warning

docker run -d --name "searxng-restore-core-$restore_id" \
  --network "searxng-restore-$restore_id" \
  --env-file .env -e SEARXNG_BASE_URL=http://127.0.0.1:18080/ \
  -p 127.0.0.1:18080:8080 \
  -v "$PWD/core-config:/etc/searxng" \
  -v "searxng-restore-core-$restore_id:/var/cache/searxng" \
  searxng/searxng:2026.7.13-9e25585ae

docker logs --tail=50 "searxng-restore-core-$restore_id"

Tunnel port 18080, open the restored instance, and run a real search. Verify customized engines and cached data. The drill omits Caddy on purpose, so it proves data and basic function recovery only; it cannot validate Basic authentication, the trusted-proxy chain, or per-client limiter behavior. Remove the test resources when finished:

docker rm -f "searxng-restore-core-$restore_id" "searxng-restore-valkey-$restore_id"
docker volume rm "searxng-restore-core-$restore_id" "searxng-restore-valkey-$restore_id"
docker network rm "searxng-restore-$restore_id"
sudo rm -r "$restore_dir"

Update images and templates separately

For an image update, back up and restore-test first, review the upstream commit, and bump the SearXNG tag. Change Valkey or Caddy only when you mean to update them. Then redeploy:

cd /opt/searxng
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose logs --tail=100 core valkey caddy

Repeat the Valkey, TLS, browser-like search, and limiter checks. Keep the previous image set and backup together; a safe rollback restores both rather than assuming newer data is backward compatible.

Template maintenance is a separate review. SearXNG’s official instructions may change service names, environment defaults, mounts, or Valkey options without changing your pinned image. Compare the current container/docker-compose.yml, .env.example, settings.template.yml, and searx/limiter.toml in the core repository with your local files. Avoid overwriting .env, settings.yml, or limiter.toml blindly, because that can replace the secret or discard your local proxy controls.

Choosing a Riven Cloud VPS for SearXNG

For a personal or small-team instance, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) runs this whole stack comfortably. All plans come with a 1 Gbps port and full root access; our VPS are unmanaged, so you run the stack yourself and keep full control over it. If you enable many engines, serve several authenticated users, or proxy a lot of images, Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB) gives the cache and transfer more headroom.

We offer Tokyo and Singapore. Pick the location that reaches both you and your upstream engines well. If you are on a mainland China network, test the Tokyo Looking Glass and Singapore Looking Glass from your own carrier at the hours you actually search; the two cities can behave quite differently. Current specs and prices are on the Riven Cloud VPS plans page.

Every plan includes daily provider-side backups, and they make a good safety net. They can catch Valkey and the other volumes at different write points, though, so keep the stopped archives, the protected secret, and the encrypted off-server copies above as your primary recovery path.

Security limits and non-fit cases

SearXNG has no built-in login of its own, which is why this deployment leans on Caddy Basic authentication. Test the logged-out denial as well as authenticated assets and form posts, keep the limiter enabled, patch all three images, watch logs and transfer, and keep Valkey off the public Internet. And please leave the Basic auth in place: an unauthenticated instance is open to the whole Internet, draws abuse traffic quickly, and runs against our AUP. The limiter slows bots down, but it is not a substitute for authentication.

Self-hosting is not the right fit for every case, and that is worth being honest about. If you need contractual availability, abuse handling, stable engine coverage, or a guaranteed clean exit reputation, a managed search product will serve you better. The same goes when upstream CAPTCHAs and IP blocks are unacceptable, when users need strong anonymity against traffic correlation, or when nobody has time to keep the limiter rules and restore drills current. SearXNG improves what upstream engines learn about you; it does not make searches invisible to them.

The deployment below runs changedetection.io 0.55.8 on a Debian or Ubuntu VPS. Caddy terminates HTTPS at change.example.com; the application itself listens only on 127.0.0.1:5000.

The install itself is only a few files. The ongoing work, and where this guide spends most of its time, is deciding what the service may reach and making sure its data can actually be restored. A good rule of thumb: use the smallest fetcher that can monitor the target, and remember that every watch URL is a network request your server makes on someone’s behalf.

Prepare the VPS, DNS, and firewall

You need a VPS with root or sudo access, an A record for change.example.com, an AAAA record only when IPv6 works end to end, and encrypted backup storage outside the VPS. TCP 80 and 443 must reach Caddy. Keep your administrative SSH port open, and leave TCP 5000 closed in UFW and the provider firewall; Caddy reaches the application over loopback.

Install Docker Engine and the Compose plugin with Docker’s convenience script (inspect it first if that worries you; on a tightly managed host, use your distribution’s packages instead):

curl -fsSL https://get.docker.com -o get-docker.sh
sudo bash get-docker.sh
sudo docker compose version
sudo apt update
sudo apt install -y caddy jq ufw

That version check aside, the rest of this guide runs docker without sudo, so either add your user to the docker group (sudo usermod -aG docker $USER, then log out and back in) or prefix the docker commands with sudo.

This firewall example assumes SSH listens on port 22. Change that rule before enabling UFW if your server uses another port.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Apply the same inbound policy at the hosting-provider firewall, and confirm the domain resolves to this server with getent ahosts change.example.com.

Create the Docker Compose project

The official 0.55.8 Compose file uses one application container, a named volume at /datastore, and the correct loopback port binding. Keep that architecture for the baseline deployment.

sudo install -d -m 750 -o "$USER" -g "$USER" /opt/changedetection
cd /opt/changedetection
umask 077

Create /opt/changedetection/compose.yml:

services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io:0.55.8
    container_name: changedetection
    hostname: changedetection
    environment:
      BASE_URL: "https://change.example.com"
      USE_X_SETTINGS: "1"
      LLM_FEATURES_DISABLED: "true"
      HIDE_REFERER: "true"
      TZ: "UTC"
    volumes:
      - changedetection-data:/datastore
    ports:
      - "127.0.0.1:5000:5000"
    logging:
      options:
        max-size: "10m"
        max-file: "3"
    restart: unless-stopped

volumes:
  changedetection-data:

BASE_URL gives notifications the public HTTPS origin. USE_X_SETTINGS=1 lets the application honor proxy host and scheme headers. That setting is safe here because Docker accepts port 5000 only from the VPS loopback path and Caddy controls the forwarded headers. Do not combine it with a public 0.0.0.0:5000 binding.

LLM_FEATURES_DISABLED=true prevents watched content and diffs from being sent to an LLM provider through the application’s AI features. HIDE_REFERER=true applies a referrer policy so monitored sites do not learn the changedetection.io hostname when an operator follows a link. Neither setting makes stored watch data public-safe.

Validate and start the service:

cd /opt/changedetection
docker compose config --quiet
docker compose up -d
docker compose logs --tail=50 changedetection
sudo ss -lntp | grep ':5000'

The listener must show 127.0.0.1:5000, never 0.0.0.0:5000 or [::]:5000.

Set the password before public exposure

changedetection.io is not a multi-user application with a first-account wizard. A default installation has no password. The official password documentation instructs operators to set one in Settings.

Leave Caddy unconfigured. From your workstation, open an SSH tunnel and keep it running:

ssh -N -L 5000:127.0.0.1:5000 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:5000, open Settings, set a strong unique password, and save. Sign out, reload the page, and confirm the password is required and works. This order prevents an Internet visitor from choosing or bypassing the initial protection.

If the password is ever lost, follow the upstream reset procedure but use this deployment’s real container name, changedetection. Reset access only from an authenticated administrative session, then set a new password immediately.

Add Caddy only after the password works

Create a tiny test resource on the same HTTPS origin. It gives the later watch test a URL you control rather than making a third-party site part of service health.

sudo install -d -m 750 -o root -g caddy /srv/changedetection-test
printf '%s\n' 'changedetection test version 1' | \
  sudo tee /srv/changedetection-test/probe.txt > /dev/null
sudo chown root:caddy /srv/changedetection-test/probe.txt
sudo chmod 640 /srv/changedetection-test/probe.txt

Keep the site in an imported snippet so it does not replace any existing Caddy hosts:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/changedetection.caddy > /dev/null <<'CADDY'
change.example.com {
    handle /changedetection-probe.txt {
        root * /srv/changedetection-test
        rewrite * /probe.txt
        file_server
    }

    handle {
        reverse_proxy 127.0.0.1:5000
    }
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsS https://change.example.com/changedetection-probe.txt

Caddy’s automatic HTTPS obtains and renews the certificate when DNS and ports 80/443 are correct. The public root should now show the password-protected application.

Verify system information and a real change

Find the API key under Settings > API. The official API authenticates requests with the x-api-key header. Read the key without adding it to shell history:

read -rsp 'changedetection.io API key: ' CD_API_KEY
printf '\n'
export CD_API_KEY
export CD_URL='https://change.example.com'

curl -fsS -H "x-api-key: $CD_API_KEY" \
  "$CD_URL/api/v1/systeminfo" | jq

Confirm that version is 0.55.8 and review queue_size, overdue_watches, uptime, and watch_count.

Create a watch using the default html_requests fetcher, trigger it, and wait for the first snapshot:

probe="$CD_URL/changedetection-probe.txt"
watch_uuid=$(curl -fsS -X POST "$CD_URL/api/v1/watch" \
  -H "x-api-key: $CD_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -nc --arg url "$probe" \
    '{url:$url,title:"Controlled Compose test",fetch_backend:"html_requests"}')" \
  | jq -er '.uuid')

curl -fsS -H "x-api-key: $CD_API_KEY" \
  "$CD_URL/api/v1/watch/$watch_uuid?recheck=true"

for attempt in $(seq 1 24); do
  watch_json=$(curl -fsS -H "x-api-key: $CD_API_KEY" \
    "$CD_URL/api/v1/watch/$watch_uuid")
  if [ "$(jq -r '.last_checked // 0' <<<"$watch_json")" -gt 0 ]; then
    jq '{last_checked,last_error,history_n,fetch_backend}' <<<"$watch_json"
    break
  fi
  sleep 5
done

Change the controlled file, trigger another check, and wait until the API reports at least two snapshots:

printf '%s\n' 'changedetection test version 2' | \
  sudo tee /srv/changedetection-test/probe.txt > /dev/null
sudo chown root:caddy /srv/changedetection-test/probe.txt
sudo chmod 640 /srv/changedetection-test/probe.txt

curl -fsS -H "x-api-key: $CD_API_KEY" \
  "$CD_URL/api/v1/watch/$watch_uuid?recheck=true"

for attempt in $(seq 1 24); do
  history_count=$(curl -fsS -H "x-api-key: $CD_API_KEY" \
    "$CD_URL/api/v1/watch/$watch_uuid/history" | jq 'length')
  [ "$history_count" -ge 2 ] && break
  sleep 5
done

curl -fsS -H "x-api-key: $CD_API_KEY" \
  "$CD_URL/api/v1/watch/$watch_uuid/difference/previous/latest?format=text"
curl -fsS -X DELETE -H "x-api-key: $CD_API_KEY" \
  "$CD_URL/api/v1/watch/$watch_uuid" > /dev/null
unset CD_API_KEY

The diff must show the change from version 1 to version 2. One pass through this test exercises DNS, TLS, authentication, queueing, outbound HTTP, snapshot persistence, and diff generation.

Back up the stopped datastore

/datastore holds watches, history, snapshots, headers, notification URLs, browser steps, and application secrets. An archive of it may contain credentials or tokens, so give it mode 600, encrypt it, and copy it off the VPS.

Stop the container first so nothing writes mid-archive, then tar the volume from a helper container:

cd /opt/changedetection
umask 077
install -d -m 700 backups
datastore_volume=$(docker inspect -f \
  '{{range .Mounts}}{{if eq .Destination "/datastore"}}{{.Name}}{{end}}{{end}}' \
  changedetection)
archive="backups/changedetection-$(date +%F-%H%M%S).tar.gz"

docker compose stop changedetection
docker run --rm \
  -v "$datastore_volume:/datastore:ro" \
  -v "$PWD/backups:/backup" \
  alpine:3.22 \
  tar -C /datastore -czf "/backup/$(basename "$archive")" .
docker compose start changedetection

sudo chown "$USER":"$USER" "$archive"
chmod 600 "$archive"
tar -tzf "$archive" > /dev/null
sha256sum "$archive" > "$archive.sha256"

Keep compose.yml, the Caddy configuration, and the checksum alongside the archive in encrypted backup storage.

Rehearse an isolated same-version restore

Restore into a throwaway environment rather than over production. The drill below builds a throwaway volume, network, and container with a timestamped name and starts the same 0.55.8 image that produced the backup. Keep the commands and the later cleanup in one shell:

cd /opt/changedetection
BACKUP=$(ls -1 backups/changedetection-*.tar.gz | sort | tail -n 1)
sha256sum -c "$BACKUP.sha256"

restore_id="changedetection-restore-$(date +%Y%m%d%H%M%S)"
docker volume create "$restore_id"
docker network create --internal "$restore_id"

docker run --rm \
  -v "$restore_id:/datastore" \
  -v "$PWD/backups:/backup:ro" \
  alpine:3.22 \
  tar -C /datastore -xzf "/backup/$(basename "$BACKUP")"

docker run -d --name "$restore_id" \
  --network "$restore_id" \
  -p 127.0.0.1:15000:5000 \
  -v "$restore_id:/datastore" \
  ghcr.io/dgtlmoon/changedetection.io:0.55.8
docker logs --tail=50 "$restore_id"

Tunnel port 15000, log in with the restored password, inspect a few watches and their histories, and run the API system-information check against the restored copy. The internal Docker network blocks scheduled fetches and notification callbacks from leaving the test environment, so fetch errors are expected. Do not connect optional browser automation to production credentials during a recovery drill. Remove the test resources when finished:

docker rm -f "$restore_id"
docker volume rm "$restore_id"
docker network rm "$restore_id"

Upgrade with a recovery point

Read the release notes, take a fresh cold backup, and rehearse its restore. Then bump the version tag in compose.yml and redeploy:

cd /opt/changedetection
docker compose config --quiet
docker compose pull changedetection
docker compose up -d
docker compose logs --tail=100 changedetection

Repeat /api/v1/systeminfo and the two-version watch test. Keep the previous image tag and archive until those checks pass. If an upgrade migrates stored data, rollback means restoring the old image and its pre-upgrade /datastore together. Changing the image tag back on its own may leave migrated data in an unsupported state.

Add a browser only for sites that require it

The baseline deliberately uses the pure HTTP html_requests fetcher. It consumes less memory, does not execute target JavaScript, and stays within changedetection.io’s request-fetching path. Dynamic pages may require the optional Playwright-compatible Sockpuppetbrowser service shown in the official Compose file.

Treat that as a separate change. The upstream example at the time of writing uses dgtlmoon/sockpuppetbrowser:latest and may add SYS_ADMIN; its own comment says that capability may be excessive. Pin a specific browser tag, test whether it runs without the capability, set CPU, memory, process, and screenshot limits, and publish neither its port 3000 nor a VNC port.

Place only changedetection.io and the browser on a dedicated Docker bridge. Private Docker networking prevents a public control port, but it does not restrict outbound destinations. Apply host or provider egress rules that deny cloud metadata, loopback, link-local, RFC1918, management, and storage networks while allowing the explicit container-to-container browser endpoint. Review those rules after every network change.

As of 0.55.8, changedetection.io blocks IANA-restricted addresses by default, rechecks DNS at fetch time, validates every redirect hop, and rejects file:// URLs, with defenses against DNS rebinding and URL-parser tricks; the ALLOW_IANA_RESTRICTED_ADDRESSES and ALLOW_FILE_URI switches both default to false. Resist the temptation to set ALLOW_IANA_RESTRICTED_ADDRESSES=true just to watch a NAS on your LAN. That global opt-in turns private addresses into valid targets for every permitted watch and makes stolen application access far more damaging. Browser traffic also needs network-layer controls because a full browser is not equivalent to the plain-request SSRF filter.

Those controls include fixes covered by the project’s SSRF security advisory. They reduce exposure in the supported configuration; they are not a reason to remove egress filtering or grant watch creation to untrusted users.

Choosing a Riven Cloud VPS for changedetection.io

For a personal watch list on the plain HTTP fetcher, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is a comfortable starting point. Every plan ships with a 1 Gbps port and full root access. These are unmanaged VPS, which means the stack is yours to run and yours to control. If you add browser workers, keep long snapshot histories, or watch many pages at short intervals, step up to Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB) for the extra memory and disk.

We offer Tokyo and Singapore. Pick the location that reaches both you and the sites you monitor well; a server close to your dashboard can still be far from a monitored origin. If you are on a mainland China network, the Tokyo Looking Glass and Singapore Looking Glass let you test real routes from your own connection before ordering. Current specs and prices are on the Riven Cloud VPS plans page.

Daily provider-side backups come with every plan and are a welcome safety net. Treat them as secondary, though: they can catch the application mid-write and they sit inside our recovery system, so the stopped /datastore archive, the encrypted off-server copy, and the restore drill above remain your primary recovery path.

Security limits and non-fit cases

A few habits keep the deployment healthy: keep the application password unique, protect API keys and notification tokens, review who can add watch URLs, and keep an eye on disk growth. Hiding the referrer does not make a fetch anonymous; the target still sees the VPS source IP, timing, request headers, and behavior, so be a polite client and respect site terms, robots policies where applicable, and sensible request rates.

Self-hosting is not always the right call, and that is fine. If nobody will own updates, outbound access policy, alert delivery, backups, and restore tests, the hosted changedetection.io service or another managed monitor will serve you better. A single VPS also cannot usefully monitor its own availability or network path, so give that job to an independent external monitor. And think twice when untrusted tenants can create arbitrary watches, when browser automation needs powerful access to internal systems, or when monitoring credentials call for formal secret management and audit controls.

This tutorial deploys Forgejo 16.0.0, the current release when this article was checked on July 17, 2026, on a fresh Debian or Ubuntu VPS. It uses the standard rootful Docker image and SQLite. Caddy terminates HTTPS for git.example.com, the web listener stays on 127.0.0.1:3000, and Git SSH uses public host port 2222. The path includes an actual clone, commit, and push rather than stopping when the dashboard loads.

SQLite suits a straightforward forge with low-to-moderate activity. Choose PostgreSQL before launch if you expect high concurrency or already operate it well. Changing databases also changes the backup and restore procedure.

Forgejo is one of ten projects in our broader guide to self-hosted apps for a VPS. That guide compares the candidates; this article covers the full deployment path for one of them.

Prerequisites

Prepare the following:

• a Debian or Ubuntu VPS with sudo or root access;
• an A record for git.example.com pointing to the VPS, and an AAAA record only when IPv6 is configured correctly;
• TCP 80 and 443 for the web proxy, TCP 2222 for Forgejo Git SSH, and your separate administrative SSH port;
• Git and an SSH client on your workstation;
• off-server storage large enough for repositories, SQLite, configuration, LFS objects, packages, and attachments.

Harden administrative access first with the secure SSH guide. This tutorial assumes the host’s own SSH daemon remains on port 22, so Forgejo can use 2222 without a collision. If you moved your administrative sshd to 2222, for example by following that guide’s worked example, pick a different host port for Forgejo’s Git SSH, such as 2223, and use it consistently in every firewall rule, port mapping, and clone URL below.

Install Docker Engine and the Compose plugin using Docker’s convenience script (read through it first if you want to see what it will change):

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo docker version

Because the script runs as root and adds Docker’s package repository, hosts with stricter policies should install Docker from the distribution’s packages instead. As of July 2026, Forgejo’s upgrade documentation requires Docker 20.10.6 or newer, which the version output confirms.

Install Caddy, Git, and UFW from the distro repository. See Caddy’s official package instructions if your distribution needs its upstream repository.

sudo apt update
sudo apt install -y caddy git ufw

Set the firewall before starting the forge:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 2222/tcp
sudo ufw enable

Replace 22 if your administrative SSH listener uses another port. Mirror these rules in the provider’s cloud firewall or security group. Do not open port 3000 or a database port publicly.

Create the Forgejo deployment

The standard image stores its state under /data. Create a host directory owned by the UID and GID used in the Compose file:

sudo install -d -m 750 -o 1000 -g 1000 /opt/forgejo/forgejo
cd /opt/forgejo

Create /opt/forgejo/compose.yml. The layout follows Forgejo’s official Docker and configuration documentation; the release pin, loopback web binding, public port 2222, disabled registration, and log limits are choices made for this tutorial.

sudo tee compose.yml > /dev/null <<'YAML'
services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:16.0.0
    container_name: forgejo
    restart: unless-stopped
    environment:
      USER_UID: "1000"
      USER_GID: "1000"
      FORGEJO__server__DOMAIN: "git.example.com"
      FORGEJO__server__ROOT_URL: "https://git.example.com/"
      FORGEJO__server__SSH_DOMAIN: "git.example.com"
      FORGEJO__server__SSH_PORT: "2222"
      FORGEJO__service__DISABLE_REGISTRATION: "true"
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"
      - "2222:22"
    logging:
      options:
        max-size: "10m"
        max-file: "3"
YAML

The image is pinned to the exact release checked for this article. An exact tag prevents an unattended major migration, but it also stops automatic fixes, so read the canonical Forgejo releases and update the tag deliberately later.

Forgejo converts variables named FORGEJO__[SECTION]__[KEY] into app.ini settings. ROOT_URL controls browser links and HTTPS clone URLs. SSH_DOMAIN and SSH_PORT make displayed SSH clone URLs use git.example.com:2222, while Docker forwards that host port to port 22 inside the standard container.

The ./forgejo:/data mount contains app.ini, repositories, the SQLite database, LFS objects, attachments, packages, SSH-related state, and generated secrets. In particular, losing [security].SECRET_KEY can make encrypted data such as 2FA secrets unreadable.

This guide uses the standard image. It does not teach the rootless variant because its paths and port mappings differ. Validate those details against the exact image before designing a rootless deployment.

Start the service, wait for the web listener, then confirm port 3000 is loopback-only and port 2222 is public:

cd /opt/forgejo
sudo docker compose up -d
for attempt in $(seq 1 24); do
  if curl -fsS -o /dev/null http://127.0.0.1:3000/; then
    break
  fi
  if [ "$attempt" -eq 24 ]; then
    echo "Forgejo did not become ready within 120 seconds" >&2
    exit 1
  fi
  sleep 5
done
sudo ss -lntp | grep -E ':(3000|2222)'

Add Caddy and HTTPS

Use a dedicated subdomain. Forgejo’s reverse-proxy documentation warns against putting a forge below a subpath on an origin that also serves user-controlled content because same-origin and CSRF boundaries become harder to protect.

Create an imported Caddy site snippet. This keeps existing hosts intact even when Forgejo is not the first service on the VPS:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/forgejo.caddy > /dev/null <<'CADDY'
git.example.com {
    reverse_proxy 127.0.0.1:3000
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Caddy requests and renews the certificate when DNS and both firewalls permit TCP 80/443. Git SSH does not pass through Caddy. Clients connect directly to port 2222.

Complete the first-run installer

An uninitialized public forge can be claimed by whoever reaches its installer first. Open https://git.example.com only when you are ready to finish setup. For stricter staging, keep Caddy stopped and tunnel the loopback listener with ssh -L 3000:127.0.0.1:3000 root@SERVER_IP, then browse to http://127.0.0.1:3000.

In the installer:

1. Select SQLite3 and keep its database inside /data.
2. Confirm the server domain is git.example.com.
3. Confirm the Forgejo base URL is https://git.example.com/.
4. Confirm the SSH domain is git.example.com and the SSH port is 2222.
5. Expand the administrator section and create the first administrator with a strong unique password and a real email address.
6. Finish the installation and sign in.

The first user created during installation receives administrator access. Registration is already disabled through Compose. Verify that a logged-out visitor cannot register, then enable 2FA on the administrator account. Configure SMTP before depending on password reset, email confirmation, or notifications.

Verify HTTPS and SSH Git workflows

Run the server-side checks:

cd /opt/forgejo
curl -fsSI https://git.example.com/
sudo docker compose exec forgejo \
  forgejo doctor check --all --log-file /tmp/doctor.log
sudo docker compose exec forgejo cat /tmp/doctor.log

In the web UI, create a disposable repository named docker-test under your account. Leave it empty for the first clone. Forgejo’s HTTP clone path uses HTTPS here, so credentials and repository data are protected in transit. On your workstation, replace YOUR_USER with the account name:

git clone https://git.example.com/YOUR_USER/docker-test.git
cd docker-test
git config user.name "Forgejo Test"
git config user.email "forgejo-test@example.com"
printf '%s\n' 'Forgejo end-to-end test' > README.md
git add README.md
git commit -m "Test HTTPS push"
git branch -M main
git push -u origin main

Enter the Forgejo username and password or personal access token when Git prompts. Refresh the browser and confirm the commit and file appear. This proves that the reverse proxy, application, SQLite database, and repository storage agree.

Now test SSH. Add your workstation’s public SSH key under Settings > SSH/GPG Keys, then run:

ssh -F /dev/null -p 2222 git@git.example.com

Forgejo should recognize the account and deny interactive shell access. Change the existing clone to SSH and push a second commit:

git remote set-url origin \
  ssh://git@git.example.com:2222/YOUR_USER/docker-test.git
printf '%s\n' 'SSH push works' >> README.md
git add README.md
git commit -m "Test SSH push"
git push

Confirm the second commit in the web UI. Delete the disposable repository after the backup test if you do not need it.

Plan for storage and runners

Git history is only part of forge storage. Git LFS, release attachments, package registries, repository mirrors, and Actions artifacts can grow independently. Set quotas where appropriate and monitor the filesystem instead of estimating capacity from repository count.

Run Forgejo Actions runners as separate services with their own lifecycle and isolation. Workflow code may be controlled by repository contributors. Do not attach a runner to the Forgejo container or casually give it the host Docker socket; that can turn a CI job into host-level access. Follow the project’s separate Actions security documentation before enabling untrusted workflows.

Back up and rehearse restoration

Forgejo’s official guidance requires a synchronized point-in-time copy of every storage component. For this single-volume SQLite design, a stopped-container archive of /data captures the database, repositories, configuration, packages, LFS objects, and generated secrets together:

sudo install -d -m 700 /var/backups/forgejo
cd /opt/forgejo
sudo docker compose exec forgejo forgejo manager flush-queues
sudo docker compose stop forgejo
sudo tar --numeric-owner -C /opt/forgejo -czf \
  "/var/backups/forgejo/forgejo-$(date +%F-%H%M%S).tar.gz" \
  forgejo
sudo docker compose start forgejo
for attempt in $(seq 1 24); do
  if curl -fsS -o /dev/null http://127.0.0.1:3000/; then
    break
  fi
  if [ "$attempt" -eq 24 ]; then
    echo "Forgejo did not restart within 120 seconds" >&2
    exit 1
  fi
  sleep 5
done

Encrypt and copy the archive off-host. If you move to PostgreSQL or MySQL, stop or quiesce Forgejo and take the database vendor’s native dump as part of the same recovery point. External object storage and remote repository paths must be captured with it. forgejo dump can be useful, but the official upgrade guide warns about restoring its SQL output for external databases; do not treat it as a substitute for pg_dump or mysqldump.

Restore onto an isolated test VPS with Forgejo 16.0.0. Transfer one archive, set BACKUP to its real path, and keep the empty directory as a rollback point:

export BACKUP=/path/to/forgejo-YYYY-MM-DD-HHMMSS.tar.gz
cd /opt/forgejo
sudo docker compose stop forgejo
sudo mv forgejo forgejo.empty
sudo tar --numeric-owner -C /opt/forgejo -xzf "$BACKUP"
sudo chown -R 1000:1000 /opt/forgejo/forgejo
sudo docker compose up -d
for attempt in $(seq 1 24); do
  if curl -fsS -o /dev/null http://127.0.0.1:3000/; then
    break
  fi
  if [ "$attempt" -eq 24 ]; then
    echo "Restored Forgejo did not become ready within 120 seconds" >&2
    exit 1
  fi
  sleep 5
done
sudo docker compose exec forgejo \
  forgejo doctor check --all --log-file /tmp/doctor.log
sudo docker compose exec forgejo cat /tmp/doctor.log

Log in, clone the restored docker-test repository over HTTPS, push a commit over SSH, and check any LFS objects, packages, or attachments you use. Upgrade only after the restored copy passes those checks.

Every Riven Cloud plan includes daily provider backups, which make a good extra layer, but they are no substitute for an application-consistent Forgejo backup and a rehearsed restore, so keep both.

Upgrade deliberately

Read the release notes and known upgrade issues, take a consistent backup, then flush queues:

cd /opt/forgejo
sudo docker compose exec forgejo forgejo manager flush-queues

Change 16.0.0 in compose.yml to the reviewed release and run:

sudo docker compose pull
sudo docker compose up -d
for attempt in $(seq 1 24); do
  if curl -fsS -o /dev/null http://127.0.0.1:3000/; then
    break
  fi
  if [ "$attempt" -eq 24 ]; then
    echo "Upgraded Forgejo did not become ready within 120 seconds" >&2
    exit 1
  fi
  sleep 5
done
sudo docker compose exec forgejo \
  forgejo doctor check --all --log-file /tmp/doctor.log
sudo docker compose exec forgejo cat /tmp/doctor.log

Repeat login, HTTPS clone, SSH push, and storage checks. Major upgrades require an explicit tag change and human verification. Forgejo performs database migrations at startup; do not assume a downgrade will be safe after those migrations.

Choosing a Riven Cloud VPS for Forgejo

For a small private forge with ordinary source repositories, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB transfer) is a solid start. Storage is usually the first thing you outgrow: Git LFS, packages, release assets, mirrors, and CI artifacts add up much faster than plain Git history. When they do, Ultra raises the NVMe to 80 GB and transfer to 2 TB, and Max provides 160 GB and 4 TB. Watch retained data and clone traffic rather than sizing by repository count, and keep Actions runners on separately isolated capacity.

All plans include a 1 Gbps port, full root access, daily backups, and deployment in Tokyo or Singapore. Our plans are unmanaged, so you keep full control of the stack you just built. Put the forge near the developers and systems that clone, push, fetch packages, and receive webhooks; teams connecting from mainland China can compare the Tokyo Looking Glass and Singapore Looking Glass from the office or carrier network to see which location feels closer. The pricing page lists the current storage and transfer limits.

Security limits

Keep public registration disabled unless you can handle spam, abuse reports, mail reputation, and user storage. If you open it, use Forgejo’s recommended CAPTCHA and username-cooldown controls. Protect administrator accounts with 2FA, review webhook targets and secrets, and leave local-network access for repository migrations disabled unless you have a specific reason to permit it.

Third-party themes, Git hooks, templates, extensions, and runners execute or influence trusted server-side work. Add them only with a review and backup plan.

When not to self-host

If source availability is business-critical and nobody on the team wants to own upgrades, monitoring, mail, incident response, and restore tests, a managed forge will serve you better. A single VPS may also fall short of compliance or geographic-redundancy requirements. And if you need to run untrusted workflow code but cannot isolate runners from the forge and host, managed CI is the safer choice.

This guide builds that deployment on a Debian or Ubuntu VPS. The application listens only on 127.0.0.1:2586; Caddy or Nginx owns the public ports. We use the official binwiederhier/ntfy:v2.26.0 image, which was the latest release when checked on July 17, 2026, with ntfy’s SQLite storage, the conservative choice for one unmanaged server.

One warning before anything else: ntfy allows anonymous users to read and write every topic by default, and adding an auth-file alone does not make the server private. The configuration below sets auth-default-access: deny-all, then grants access with named users and topic ACLs.

Prerequisites: prepare the VPS, DNS, and firewall

You need a Linux VPS with root or sudo access, a DNS record for ntfy.example.com, and Docker Engine with the Compose plugin. Point an A record at the server’s IPv4 address. Add an AAAA record only if the VPS, firewall, and reverse proxy all serve IPv6.

Our VPS plans are unmanaged, so you run Docker, TLS, the firewall, monitoring, backups, and upgrades yourself and keep full control of the stack. If you want one server for several small services, our self-hosted apps guide can help you decide what belongs on the same VPS.

Install Docker Engine and the Compose plugin. Docker’s convenience script is the quickest way to get both; anyone uneasy about running a downloaded script as root can install from the distribution’s packages instead:

curl -fsSL https://get.docker.com | sudo bash
sudo docker compose version

The rest of the guide assumes your user can run Docker without sudo. Either prefix Docker commands with sudo, or follow Docker’s documented post-install procedure.

Allow SSH before enabling or changing a firewall; if you have not hardened that port yet, our walkthrough of securing SSH on a VPS covers it. If UFW is already active, add only the web ports:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status

Mirror those rules in any provider firewall. Do not open port 2586 publicly. After DNS propagates, getent ahosts ntfy.example.com should show this VPS.

Create the ntfy Compose project

Keep the project in one directory so its configuration and storage paths remain unambiguous:

sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/ntfy
cd /opt/ntfy
umask 077
install -d -m 0700 cache data

Create /opt/ntfy/compose.yaml. The loopback binding, deny-by-default policy, explicit limits, and file permissions are hardening choices on top of ntfy’s official example and configuration reference.

services:
  ntfy:
    image: binwiederhier/ntfy:v2.26.0
    container_name: ntfy
    command: serve
    environment:
      TZ: UTC
    ports:
      - "127.0.0.1:2586:80"
    volumes:
      - ./server.yml:/etc/ntfy/server.yml:ro
      - ./cache:/var/cache/ntfy
      - ./data:/var/lib/ntfy
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "wget -q --tries=1 http://localhost:80/v1/health -O - | grep -Eo '\"healthy\"\\s*:\\s*true' || exit 1",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s
    init: true
    restart: unless-stopped

Create /opt/ntfy/server.yml:

base-url: "https://ntfy.example.com"
behind-proxy: true

cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"

attachment-cache-dir: "/var/cache/ntfy/attachments"
attachment-total-size-limit: "5G"
attachment-file-size-limit: "15M"
attachment-expiry-duration: "3h"
visitor-attachment-total-size-limit: "100M"
visitor-attachment-daily-bandwidth-limit: "500M"

auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"

enable-login: true
require-login: true
enable-signup: false

# Optional for prompt delivery to the official iOS app:
# upstream-base-url: "https://ntfy.sh"

Keep the project files private too:

cd /opt/ntfy
chmod 600 compose.yaml server.yml

The 12-hour message retention and the attachment limits are ntfy’s documented defaults, written out here so you can review them. They are limits, not a sizing recommendation. cache/cache.db and cache/attachments/ hold temporary messages and files. data/user.db is durable security state: users, password hashes, tokens, and ACLs.

Start ntfy and check its health:

docker compose up -d --wait --wait-timeout 120
curl -fsS http://127.0.0.1:2586/v1/health

The response should contain {"healthy":true}.

Create users and topic ACLs

There is no default administrator. Add one interactively; the password is hashed into data/user.db rather than written into Compose:

docker compose exec ntfy ntfy user add --role=admin admin

An administrator can read and write every topic. For automation, a regular account with a narrow ACL is safer. These commands create a publisher that may write, but not read, the backups topic:

docker compose exec ntfy ntfy user add publisher
docker compose exec ntfy ntfy access publisher backups write-only

Create a separate subscriber if a person or service needs read-only access:

docker compose exec ntfy ntfy user add subscriber
docker compose exec ntfy ntfy access subscriber backups read-only
docker compose exec ntfy ntfy access

You can create a client token so scripts never see the account password:

docker compose exec ntfy ntfy token add --expires=90d --label="tutorial-client" publisher

Store the returned token in a secret manager. ntfy tokens inherit the user’s permissions; they have no separate scopes.

Put ntfy behind HTTPS

TLS is required because Basic credentials and bearer tokens must never cross plaintext HTTP. behind-proxy: true also matters: without it, ntfy sees the proxy as every visitor and applies one shared rate-limit bucket.

Caddy’s automatic HTTPS keeps the proxy configuration small. Install Caddy through its official distro instructions, then add this site to /etc/caddy/Caddyfile:

ntfy.example.com {
    reverse_proxy 127.0.0.1:2586
}

Validate and reload it:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Caddy forwards client information and supports WebSocket upgrades by default. For Nginx, use ntfy’s official reverse-proxy example, not a bare proxy_pass: preserve Host, append X-Forwarded-For, set X-Forwarded-Proto, use HTTP/1.1 with Upgrade and Connection, disable response buffering for streaming subscriptions, allow request bodies up to your attachment limit, and set long read and send timeouts. Terminate TLS with a valid certificate on port 443 and redirect port 80 to HTTPS.

Verify the public endpoint:

curl -fsS https://ntfy.example.com/v1/health

Run an end-to-end notification test

First prove that anonymous publishing is blocked:

curl -sS -o /dev/null -w '%{http_code}\n' \
  -d 'anonymous publish should fail' \
  https://ntfy.example.com/backups

The result must not be a 2xx status. A 401 or 403 confirms the private default is in effect.

In the ntfy web app or mobile app, add https://ntfy.example.com as the server, sign in as subscriber, and subscribe to backups. Then publish with the restricted account:

curl -fsS \
  -u 'publisher:YOUR_PASSWORD' \
  -H 'Title: Backup test' \
  -H 'Priority: high' \
  -d 'ntfy end-to-end test' \
  https://ntfy.example.com/backups

Confirm the message appears in the subscribed browser or phone. Polling the API gives a second check:

curl -fsS \
  -u 'subscriber:YOUR_PASSWORD' \
  'https://ntfy.example.com/backups/json?poll=1&since=10m'

Now test persistence within the 12-hour cache window:

docker compose restart ntfy
curl -fsS https://ntfy.example.com/v1/health
curl -fsS -u 'subscriber:YOUR_PASSWORD' \
  'https://ntfy.example.com/backups/json?poll=1&since=10m'

For an attachment test, create a harmless file smaller than 15 MB and upload it:

printf 'attachment persistence test\n' > /tmp/ntfy-test.txt
curl -fsS -u 'publisher:YOUR_PASSWORD' \
  -H 'Filename: ntfy-test.txt' \
  -T /tmp/ntfy-test.txt \
  https://ntfy.example.com/backups
rm /tmp/ntfy-test.txt

The subscriber should receive an attachment link hosted at ntfy.example.com. Treat that URL as a capability link: ntfy’s file handler serves the attachment by message ID, without applying the topic ACL to the download. Anyone who obtains the URL can fetch the file until it expires. Do not send sensitive attachments through this path; use an authenticated object-delivery system when each download must be authorized.

For a harmless test file, download it before the configured three-hour expiry, restart ntfy, and confirm it remains available during that window. ntfy manages the attachment directory and deletes expired or unreferenced files, so never share the directory with another application.

Understand the iOS delivery trade-off

Prompt delivery to the official iOS app requires an APNS-connected upstream, normally https://ntfy.sh. Uncomment upstream-base-url and recreate ntfy if that delivery behavior matters. According to ntfy’s iOS documentation, the upstream receives the message ID and a SHA-256-derived topic identifier, not the message body.

Leaving the setting disabled avoids that upstream dependency, but iOS notifications can be delayed significantly. A self-hosted ntfy server therefore does not promise fully independent, instant iOS push. Android normally keeps an instant-delivery connection to the self-hosted server; using FCM requires a custom app build and Firebase configuration.

Back up and restore ntfy

ntfy has no dedicated backup tool. Stop the container, archive the project directory, and start it again:

cd /opt/ntfy
install -d -m 0700 backups
archive="backups/ntfy-$(date +%F-%H%M%S).tar.gz"

docker compose stop ntfy
sudo tar -czf "$archive" compose.yaml server.yml data cache
sudo chmod 600 "$archive"
docker compose start ntfy
curl -fsS --retry 12 --retry-delay 5 --retry-all-errors \
  http://127.0.0.1:2586/v1/health

data/user.db is the part you cannot lose: it holds accounts, tokens, and ACLs. The message cache and attachments are temporary by design; a minimal backup may omit cache, but document that recovery will then not include recent messages or files.

Encrypt the archive before transferring it off the VPS. File permissions protect it on this host, not at the destination.

To restore, stop ntfy and move the damaged project aside. This example assumes the backup archive is still under the old project’s backups directory; list that directory first and replace the ntfy-YYYY-MM-DD-HHMMSS.tar.gz placeholder below with the real filename, which carries both the date and the time of the backup:

cd /opt/ntfy
docker compose stop ntfy
cd /opt
sudo mv ntfy ntfy.failed
sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/ntfy
cd /opt/ntfy
ls /opt/ntfy.failed/backups/
sudo tar -xzf /opt/ntfy.failed/backups/ntfy-YYYY-MM-DD-HHMMSS.tar.gz
sudo chown -R "$USER":"$USER" /opt/ntfy
install -d -m 0700 backups
chmod 700 data cache

docker compose up -d --wait --wait-timeout 120
curl -fsS https://ntfy.example.com/v1/health
docker compose exec ntfy ntfy access

Start the same ntfy version first. Verify an authenticated publish and a cached attachment before upgrading. Do not run docker compose down -v; it is unnecessary here and a dangerous habit around stateful Compose projects.

Every one of our plans includes daily backups, a solid fallback when the entire host needs to come back. Keep the stopped archive, the rehearsed restore, and an encrypted off-server copy in your routine as well; they are what guarantee an application-consistent data/user.db.

Upgrade without losing state

Read the ntfy release notes, take a fresh backup, and change the image tag in compose.yaml only after reviewing the target release. Then run:

docker compose pull ntfy
docker compose up -d --wait --wait-timeout 120
curl -fsS https://ntfy.example.com/v1/health

Repeat the anonymous rejection and authenticated delivery tests. Keep the old archive until the new version has survived a restart and delivered an attachment.

Choosing a Riven Cloud VPS for ntfy

ntfy itself is a light workload. For a private, authenticated server handling alerts from a handful of machines, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is more than enough. Consider Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB transfer) or Max (4 vCPU, 16 GB RAM, 160 GB NVMe, 4 TB transfer) if you expect many subscribers, long retention, or frequent large attachments. Whichever plan you pick, keep the ACLs and quotas above in place; access control is what keeps transfer and disk usage predictable.

Choose Tokyo or Singapore based on where your publishers and subscribers sit. If clients connect from mainland China, a quick test from the Tokyo Looking Glass and Singapore Looking Glass on your own carrier, at the time of day you care about, will tell you more than any route description. The Riven Cloud VPS plan comparison shows the current NVMe and monthly-transfer limits.

Security limits and when not to self-host

Publicly writable ntfy topics can become notification spam, phishing, attachment hosting, or unexpected VPS transfer. ntfy includes request, subscription, and attachment limits, but those controls do not turn an anonymous service into a private one. Keep deny-all, grant narrow ACLs, protect tokens, monitor logs and disk usage, and patch both Docker and ntfy.

Hosted ntfy or another managed notification service is the better fit when nobody has time to maintain TLS, monitoring, updates, and restore tests; when you need contractual availability or delivery guarantees; or when public anonymous topics are part of the product and running an abuse desk is not realistic. And if dependable iOS push is the hard requirement, be clear-eyed about the trade. With upstream-base-url set, every notification sends a delivery poke through ntfy.sh, though the upstream sees only the message ID and a hashed topic identifier while the content stays on your server. That is a dependency on upstream infrastructure rather than a content leak, but it does mean your alerting is only as available as ntfy.sh; if that dependency is unacceptable and instant iOS delivery is non-negotiable, hosted delivery is the more practical choice.

The container’s Apache listener is available only at 127.0.0.1:8080. Caddy is the public entry point, while the image’s built-in cron runs feed refreshes twice an hour. The verification path adds a real Atom feed, runs the updater, marks an article read, restarts the container, and checks that both the subscription and read state survived.

FreshRSS is one option in our broader guide to self-hosted apps for a VPS. It makes a good first service; just plan on maintaining TLS, updates, and backups after the novelty wears off.

Prerequisites

You need:

• a Debian or Ubuntu VPS with root or sudo access;
• an A record for rss.example.com pointing to the VPS, plus an AAAA record only if IPv6 is configured and filtered correctly;
• TCP 80 and 443 open for Caddy and certificate issuance;
• a modern browser and an off-server backup destination.

The SQLite path in this tutorial is simple and complete for a single VPS. FreshRSS also supports PostgreSQL and MySQL/MariaDB, but either choice adds a separate database service, credentials, upgrades, and backup scope. No public database port is needed.

Secure the host’s administrative login before deploying the reader. Our SSH hardening guide explains how to add and test keys before disabling passwords.

Install Docker Engine and the Compose plugin with Docker’s convenience script (read it first if piping a script into root bothers you, or use Docker’s apt repository instead):

curl -fsSL https://get.docker.com -o get-docker.sh
sudo bash get-docker.sh
sudo docker compose version

Install Caddy and UFW from the Debian or Ubuntu repository. Caddy also publishes official package instructions for distributions that need its upstream repository.

sudo apt update
sudo apt install -y caddy ufw

This firewall example assumes administrative SSH uses TCP 22:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Replace port 22 if you moved SSH. Apply the same public inbound rules to the provider’s cloud firewall or security group. Port 8080 must not be public.

Create the Compose deployment

Store the deployment under /opt/freshrss. Bind mounts make the data and extensions easy to inspect, archive, and restore without relying on Docker’s volume-name conventions.

sudo install -d -m 750 /opt/freshrss
sudo install -d -m 750 /opt/freshrss/data
sudo install -d -m 750 /opt/freshrss/extensions
cd /opt/freshrss

Create /opt/freshrss/compose.yml. It follows FreshRSS’s official Docker examples; the release pin, loopback binding, and staggered cron schedule are our choices.

sudo tee compose.yml > /dev/null <<'YAML'
services:
  freshrss:
    image: freshrss/freshrss:1.29.1
    container_name: freshrss
    restart: unless-stopped
    environment:
      TZ: "UTC"
      CRON_MIN: "13,43"
    volumes:
      - ./data:/var/www/FreshRSS/data
      - ./extensions:/var/www/FreshRSS/extensions
    ports:
      - "127.0.0.1:8080:80"
    logging:
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test: ["CMD", "cli/health.php"]
      timeout: 10s
      start_period: 60s
      interval: 75s
      retries: 3
YAML

FreshRSS listens on port 80 inside this image. Docker maps it to loopback port 8080, where only host processes such as Caddy can connect. /var/www/FreshRSS/data contains configuration, user data, and the SQLite databases. The extensions mount preserves any third-party extensions installed later.

TZ=UTC makes log and cron times unambiguous. CRON_MIN=13,43 asks the image’s scheduled job to run at 13 and 43 minutes past each UTC hour. The stagger avoids the common top-of-hour spike. FreshRSS’s feed-update documentation notes that scheduling much more often than every 20 minutes brings little benefit because individual feeds are not refreshed more frequently than that.

Pinning 1.29.1 keeps the deployment reproducible. It also requires you to read the FreshRSS release notes and deliberately change the tag when you are ready to update. Avoid the rolling edge tag for a routine production install.

Start the service:

cd /opt/freshrss
sudo docker compose up -d --wait --wait-timeout 120
sudo docker compose logs --tail=50 freshrss

Confirm that Apache is not exposed on every interface:

sudo ss -lntp | grep ':8080'
curl -fsSI http://127.0.0.1:8080/

The listener should show 127.0.0.1:8080, not 0.0.0.0:8080.

Complete the web installer through an SSH tunnel

Do not add the public Caddy route yet. The uninitialized web installer creates the first user, so exposing it before setup gives an Internet visitor a chance to claim the instance. Complete it through a private SSH tunnel instead.

From your workstation, open a tunnel and leave it running:

ssh -N -L 8080:127.0.0.1:8080 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:8080. The official Docker guide recommends the web installation path used here.

1. Choose the interface language and continue after the prerequisite check passes.
2. Select SQLite as the database.
3. Set the application or base URL to https://rss.example.com.
4. Create the initial user with a strong, unique password.
5. Select form authentication and finish the installation.
6. Log in through the tunnel.

Never select No authentication for a reader reachable from the Internet. FreshRSS’s access-control documentation calls that mode dangerous on a public server.

The Compose file contains no administrator password because the browser setup writes it directly into the persistent data directory. The official image also supports unattended environment variables, but those variables apply only during first initialization and make secret handling easier to get wrong.

Before public exposure, confirm the initial user exists:

cd /opt/freshrss
sudo docker compose exec --user www-data freshrss cli/list-users.php

Sign out through the tunneled browser, reload the root page, and visit http://127.0.0.1:8080/i/. The root must show the login flow, and /i/ must not offer a fresh installation wizard. Stop and inspect the persistent data directory if the installer is still available. Close the tunnel only after those checks pass.

Configure Caddy and TLS

Now expose the initialized login page through Caddy. Use an imported site snippet so this tutorial does not overwrite other hosts already served by Caddy:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/freshrss.caddy > /dev/null <<'CADDY'
rss.example.com {
    reverse_proxy 127.0.0.1:8080
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsSI https://rss.example.com/

Caddy obtains and renews a public certificate when DNS points to this VPS and TCP 80/443 can reach it. If the certificate does not appear, check the DNS records, UFW, the provider firewall, and sudo journalctl -u caddy -n 100 --no-pager.

Do not broaden FreshRSS’s TRUSTED_PROXY setting just to make the page load. It affects which forwarded client addresses and authentication headers FreshRSS trusts. This host-proxy design works without adding a broad Docker-network range. If a later authentication integration requires the setting, trust only the actual proxy path.

Add a feed and prove state persists

Log in at https://rss.example.com. Choose Add a feed and enter the public FreshRSS releases feed:

https://github.com/FreshRSS/FreshRSS/releases.atom

Trigger an immediate server-side refresh rather than waiting for minute 13 or 43:

cd /opt/freshrss
sudo docker compose exec --user www-data freshrss \
  php /var/www/FreshRSS/app/actualize_script.php
sudo docker compose logs --since=5m freshrss

Reload the browser and confirm release entries appear. Open one item, mark it read, and optionally mark it as a favorite. Then restart the container:

sudo docker compose restart freshrss
sudo docker compose exec --user www-data freshrss cli/health.php

Log in again. The subscription, its articles, and the read or favorite state should all have survived, which exercises the browser workflow, updater, SQLite data, and bind mount together. After minute 13 or 43 passes, check sudo docker compose logs --since=45m freshrss to confirm cron ran.

If you use a mobile reader, enable API access in the user settings and set a separate API password. Test login and article-state sync from that client. Do not assume the normal web password is the API credential.

Use OPML for migration, not recovery

FreshRSS can import and export subscriptions as OPML from Subscription management > Import/export. Export an OPML file after initial setup and whenever the subscription list changes substantially. It is useful for moving feeds to another reader or rebuilding the list by hand.

OPML is not a full backup. It does not preserve the whole FreshRSS configuration, read and favorite state, user credentials, extensions, or every feed-specific setting. Keep it beside, not instead of, the application backup.

Back up data, SQLite, and extensions

FreshRSS’s backup guide provides a portable per-user SQLite export:

cd /opt/freshrss
sudo docker compose exec --user www-data freshrss cli/db-backup.php

The command writes the export under persistent user data, so it still needs to be copied off the server. For full state, archive both bind mounts with the container stopped:

sudo install -d -m 700 /var/backups/freshrss
cd /opt/freshrss
sudo docker compose stop freshrss
sudo tar -C /opt/freshrss -czf \
  "/var/backups/freshrss/freshrss-$(date +%F-%H%M%S).tar.gz" \
  data extensions
sudo docker compose up -d --wait --wait-timeout 120

Encrypt the archive and copy it to storage outside the VPS. If you adopt PostgreSQL or MySQL/MariaDB, include a native pg_dump or mysqldump from the same recovery point.

Test the archive on an isolated VPS with the same image tag. Transfer one archive, set BACKUP to its real path, and keep the empty directories as rollback points:

export BACKUP=/path/to/freshrss-YYYY-MM-DD-HHMMSS.tar.gz
cd /opt/freshrss
sudo docker compose stop freshrss
sudo mv data data.empty
sudo mv extensions extensions.empty
sudo tar -C /opt/freshrss -xzf "$BACKUP"
sudo docker compose up -d --wait --wait-timeout 120
sudo docker compose exec --user www-data freshrss cli/health.php

Log in, refresh the test feed, and confirm the subscription and read state. Test each installed extension too.

For a portable database export, the official restore command is:

sudo docker compose exec --user www-data freshrss \
  cli/db-restore.php --delete-backup --force-overwrite

Use it only against the intended test or recovery instance after reading the prompts and backup documentation.

Every Riven Cloud plan includes daily backups, and they make a good safety net, but they do not replace an application-consistent backup and a rehearsed restore.

Upgrade the container

Read the release notes, export the user database, and take the stopped-container archive. Change only the exact image tag in compose.yml, then run:

cd /opt/freshrss
sudo docker compose pull
sudo docker compose up -d --wait --wait-timeout 120
sudo docker compose exec --user www-data freshrss cli/health.php

Log in, run /var/www/FreshRSS/app/actualize_script.php, and confirm feed and read-state behavior. Docker deployments should replace the image rather than use the web updater. Treat a PostgreSQL major-version change as a separate database migration.

Choosing a Riven Cloud VPS for FreshRSS

For a private reader on SQLite, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is a comfortable fit. Feed count, refresh frequency, full-text retrieval, and retention decide how far it stretches; if you add PostgreSQL, RSS-Bridge, heavy image proxying, or browser-based scraping, our Ultra plan (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB) is the sensible step up. Every plan is an unmanaged KVM VPS with full root access, a 1 Gbps port, and daily backups, so you run the stack yourself and keep full control.

FreshRSS talks both to its readers and to feed publishers, so location affects two paths. Choose Tokyo or Singapore based on where you read from, and check that your important feeds respond well from that data-center IP (more RAM will not fix a publisher that blocks data-center traffic). If you read from mainland China, a quick comparison of the Tokyo Looking Glass and Singapore Looking Glass from your own access network will show which location feels faster. Once you have a rough idea of the workload, the details are on the Riven Cloud VPS plans page.

Security limits

FreshRSS fetches user-supplied feed URLs from the server, which creates server-side request forgery risk on shared or multi-user instances. As of July 16, 2026, release 1.29.1 does not restrict fetching internal hosts, so a feed URL can reach loopback or LAN services the container can route to. Rely on network-level controls instead: the compose and network layout in this guide, the firewall, and keeping cloud metadata endpoints and sensitive internal services out of the container’s reach. The next release after 1.29.1 adds default internal-host blocking with an INTERNAL_HOST_ALLOWLIST allowlist (FreshRSS PR #8400), so revisit this section after upgrading; at that point, allow only the exact host, port, or network range a private RSS-Bridge or RSSHub needs, and never set the allowlist to *.

Install extensions only from sources you trust because they execute server-side code. Protect private feed URLs, feed credentials, browser sessions, and backups. Keep Apache’s port on loopback and apply host and container updates promptly.

When not to self-host

A hosted reader is the better choice if nobody will own TLS, feed scheduling, updates, monitoring, and restore tests. A public reader for untrusted users also brings SSRF, privacy, abuse, and transfer concerns that a personal instance largely avoids, and a managed service is the safer fit when private feed credentials need formal controls or reader availability needs a commercial SLA.

This tutorial installs the current Umami 3.2.0 release on Debian or Ubuntu with Docker Compose. Umami listens only on 127.0.0.1:3000; PostgreSQL has no host port at all. Caddy or Nginx terminates TLS at analytics.example.com.

This deployment pins the application image to ghcr.io/umami-software/umami:3.2.0, the newest release when checked on July 16, 2026. Umami publishes plain version tags on GHCR (3, 3.2, 3.2.0, and so on) alongside latest, so pinning the exact release keeps upgrades deliberate instead of accidental. The database follows the official Compose file’s choice of postgres:15-alpine.

Prerequisites: prepare Docker, DNS, and the firewall

You need an unmanaged Linux VPS with root or sudo access, Docker Engine, the Compose plugin, and a DNS A record that points analytics.example.com to the VPS. Publish an AAAA record only when the complete HTTPS path works over IPv6. Umami requires PostgreSQL 12.14 or newer; this deployment follows the official Compose choice of the PostgreSQL 15 Alpine series and configures it for UTC.

Our VPS plans are unmanaged, so you run the containers, database, firewall, backups, and upgrades yourself and keep full control. If you are comparing several services for one server, our self-hosted apps guide is a good place to start.

Install Docker Engine and the Compose plugin with Docker’s convenience script; it is worth skimming the script before running it so you know what it changes:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo docker compose version

The script runs as root and adds Docker’s package repository. If that does not suit your host, use your distribution’s own Docker packages instead. The commands below assume your user can run Docker. Otherwise prefix them with sudo or follow Docker’s documented post-install procedure.

If UFW is active, allow HTTP and HTTPS. Keep the current SSH rule in place:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status

Apply equivalent rules at the hosting-provider firewall. Do not expose ports 3000 or 5432. Confirm DNS with getent ahosts analytics.example.com before requesting a certificate.

Generate the environment file

Create the project directory:

sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/umami
cd /opt/umami

Generate URL-safe random values without printing them to the terminal. Hex keeps the PostgreSQL password valid inside DATABASE_URL without percent-encoding:

umask 077
printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
printf 'APP_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
chmod 600 .env

Do not paste the contents of .env into tickets or logs. DATABASE_URL tells Umami which PostgreSQL user, password, database, host, and port to use. In Compose, the hostname is the service name db, not localhost. APP_SECRET is a unique random value used to secure authentication tokens. Keep it unchanged across restarts and restores; changing it invalidates existing login sessions.

Create the Umami and PostgreSQL services

Create /opt/umami/compose.yaml. It is based on Umami’s official Compose file; the loopback-only publication, required APP_SECRET, and bounded health waits are choices made for this tutorial.

services:
  umami:
    image: ghcr.io/umami-software/umami:3.2.0
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: "postgresql://umami:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/umami"
      APP_SECRET: "${APP_SECRET:?set APP_SECRET}"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test:
        ["CMD-SHELL", "curl -fsS http://localhost:3000/api/heartbeat || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 6
      start_period: 30s
    init: true
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}"
      TZ: UTC
      PGTZ: UTC
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 6
    restart: unless-stopped

volumes:
  umami-db-data:

The db health check prevents Umami from starting before PostgreSQL accepts connections. All accounts, website definitions, shares, and analytics events live in the named umami-db-data volume. The application container is disposable and needs no data volume.

Start both services and check the heartbeat:

docker compose up -d --wait --wait-timeout 180
curl -fsS http://127.0.0.1:3000/api/heartbeat

If Umami loops during startup, read docker compose logs umami before changing the database. Common causes are a damaged DATABASE_URL, a missing .env, or PostgreSQL that never reached healthy state.

Change the default password through an SSH tunnel

Do not enable the public Caddy route yet. On first initialization, Umami creates the documented account admin with password umami. Publishing that login page before changing the password creates an avoidable takeover window.

From your workstation, forward the loopback-only listener and leave the tunnel running:

ssh -N -L 3000:127.0.0.1:3000 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:3000, sign in as admin with password umami, and replace it with a strong, unique password. Sign out, confirm the old password no longer works, then sign in with the new one. Close the tunnel only after that check passes.

Serve the dashboard and tracker over HTTPS

An HTTPS website will refuse to load an HTTP analytics script as mixed content. Put the dashboard, tracker, and collection endpoint behind the same valid TLS hostname.

With Caddy, add this block to /etc/caddy/Caddyfile:

analytics.example.com {
    reverse_proxy 127.0.0.1:3000
}

Caddy handles certificate issuance and forwards the original host, client address, and scheme. Validate, reload, and check the public heartbeat:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsS https://analytics.example.com/api/heartbeat

For Nginx, terminate TLS on 443, redirect port 80, and proxy to http://127.0.0.1:3000. Preserve Host, append X-Forwarded-For, and set X-Forwarded-Proto to the original scheme. Umami does not need an invented BASE_URL variable for this deployment; the proxy’s host and forwarded headers describe the public request. The Umami installation guide links to Nginx’s reverse-proxy documentation for this pattern.

Do not put blanket authentication in front of the whole hostname. The tracker script and /api/send collection endpoint must remain reachable from tracked websites. If you add another access layer for the dashboard, test its path rules carefully.

Record a real pageview

Browse to https://analytics.example.com and sign in with the password set through the SSH tunnel.

Add a website in the dashboard. Use the actual site hostname and a recognizable name, then open its tracking-code section. Umami generates the website ID and the exact snippet. It has this form:

<script
  defer
  src="https://analytics.example.com/script.js"
  data-website-id="WEBSITE-ID-FROM-UMAMI"
></script>

Copy the generated snippet into the tracked site’s <head>. Deploy that page and open it in a normal browser with tracker blocking disabled.

Use the browser’s Network panel to verify two requests: https://analytics.example.com/script.js loads successfully, and the collection request to /api/send returns a successful status. The Umami collection guide says the visit should appear immediately. Confirm the pageview in the dashboard’s realtime view, then repeat from another browser or device. This is the end-to-end test; a green container health check alone proves nothing about tracker delivery.

If the pageview does not appear, check the generated website ID, browser blockers, Content Security Policy, mixed-content errors, reverse-proxy logs, and Umami logs:

docker compose logs --tail=100 umami
curl -fsSI https://analytics.example.com/script.js

Back up PostgreSQL and configuration

Umami’s documentation has no application-specific backup procedure, so use PostgreSQL’s own tools. Use pg_dump rather than copying a live database volume; the custom format supports a controlled pg_restore:

cd /opt/umami
umask 077
install -d -m 0700 backups
docker compose exec -T db \
  pg_dump -U umami -d umami -Fc \
  > "backups/umami-$(date +%F).dump"
test -s "backups/umami-$(date +%F).dump"
chmod 600 "backups/umami-$(date +%F).dump"

Because compose.yaml pins exact image tags, the Compose file itself records which Umami and PostgreSQL versions produced the dump. Keep a copy of it with every dump and a restore can always use matching versions.

Preserve compose.yaml, the mode-600 .env, the reverse-proxy configuration, and any optional tracker endpoint settings in an encrypted, access-controlled backup. The dump contains analytics, users, teams, shares, and website definitions. The stable APP_SECRET and database password are configuration secrets, so do not store them in a public repository or beside an unencrypted public dump.

For the Caddy deployment in this guide, make a restricted configuration archive without displaying either secret:

sudo tar -czf "backups/umami-config-$(date +%F).tar.gz" \
  compose.yaml .env /etc/caddy/Caddyfile
sudo chmod 600 "backups/umami-config-$(date +%F).tar.gz"

Use the corresponding Nginx site file if you chose Nginx. Encrypt the configuration archive before copying it off the VPS.

Riven Cloud plans include daily provider backups as an extra safety net, but nothing replaces an application-consistent PostgreSQL dump that you have rehearsed restoring. Copy encrypted backups off the VPS. Database growth follows event volume and retention, so keep an eye on the volume and decide how long raw analytics should stay available.

Restore and prove the backup works

This restore drill uses a separate directory, Compose project, PostgreSQL volume, and loopback port. It never stops or drops the production database. Copy the production secrets and one dump into the isolated project without printing either one:

sudo install -d -m 0700 -o "$USER" -g "$USER" \
  /opt/umami-restore/backups
sudo install -m 0600 -o "$USER" -g "$USER" \
  /opt/umami/.env /opt/umami-restore/.env
sudo install -m 0600 -o "$USER" -g "$USER" \
  /path/to/umami-YYYY-MM-DD.dump \
  /opt/umami-restore/backups/umami-YYYY-MM-DD.dump
cd /opt/umami-restore

Create /opt/umami-restore/compose.yaml with the same pinned images as the production Compose file, a distinct database volume, and non-conflicting loopback port 3300:

services:
  umami:
    image: ghcr.io/umami-software/umami:3.2.0
    ports:
      - "127.0.0.1:3300:3000"
    environment:
      DATABASE_URL: "postgresql://umami:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/umami"
      APP_SECRET: "${APP_SECRET:?set APP_SECRET}"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test:
        ["CMD-SHELL", "curl -fsS http://localhost:3000/api/heartbeat || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 6
      start_period: 30s
    init: true
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}"
      TZ: UTC
      PGTZ: UTC
    volumes:
      - umami-restore-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 6
    restart: unless-stopped

volumes:
  umami-restore-db-data:

Start the isolated database. The new PostgreSQL volume contains a fresh, empty umami database, so no dropdb command is needed. Restore the dump, start the isolated application, and check its heartbeat:

cd /opt/umami-restore
test -s backups/umami-YYYY-MM-DD.dump
docker compose -p umami-restore up -d --wait --wait-timeout 120 db
docker compose -p umami-restore exec -T db pg_restore \
  -U umami -d umami \
  < backups/umami-YYYY-MM-DD.dump
docker compose -p umami-restore up -d --wait --wait-timeout 180 umami
curl -fsS http://127.0.0.1:3300/api/heartbeat

Inspect the restored dashboard without creating a public proxy route. From your workstation, open a second tunnel:

ssh -N -L 3300:127.0.0.1:3300 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:3300, log in with the restored account, and confirm the websites and historical reports exist. Keep production running while you compare a few known totals. Once a dump has passed this drill, you can rely on it.

Upgrade Umami safely

Umami updates can include database migrations. Read the release notes and official update guidance, and take a fresh logical dump first. The image tag is pinned, so pulling alone changes nothing; edit compose.yaml, set the Umami image tag to the release you reviewed, then pull and recreate:

docker compose pull umami
docker compose up -d --wait --wait-timeout 180
curl -fsS https://analytics.example.com/api/heartbeat

Wait for startup and migration logs to settle. On major upgrades or large migrated databases, Umami recommends refreshing PostgreSQL planner statistics:

docker compose exec -T db \
  psql -U umami -d umami -c 'ANALYZE;'

Log in, inspect an existing dashboard, load the tracker, and confirm a fresh pageview reaches /api/send and appears in realtime. Never use docker compose down -v; that removes the PostgreSQL volume.

Update the PostgreSQL 15 image separately

Keep database-image maintenance separate from an Umami application update, and take a fresh logical dump first. For a patch update within PostgreSQL major version 15:

cd /opt/umami
docker compose pull db
docker compose stop umami
docker compose up -d --wait --wait-timeout 120 db
docker compose up -d --wait --wait-timeout 180 umami
curl -fsS https://analytics.example.com/api/heartbeat

Log in and confirm an existing dashboard plus a new pageview. Keep the pre-update dump until those checks pass. A PostgreSQL major-version change is a database migration, not an image patch; follow PostgreSQL’s major-upgrade or logical dump/restore procedure instead of using the sequence above.

Choosing a Riven Cloud VPS for Umami

For most sites, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB transfer) is a comfortable starting point for Umami. Capacity follows event volume, retention, and report queries more than the number of tracked domains, so if the database grows or reports slow down, Ultra (8 GB RAM, 80 GB NVMe, 2 TB transfer) and Max (4 vCPU, 16 GB RAM, 160 GB NVMe, 4 TB transfer) give you room to move up. A periodic look at PostgreSQL size, ingestion rate, and backup time will tell you when it is time.

One placement tip: put the collector near the visitors and the sites that send events. Latency for whoever opens the dashboard matters far less than latency on the tracking path. We offer Tokyo and Singapore on every plan, and if a meaningful share of your traffic comes from mainland China, comparing the Tokyo Looking Glass and Singapore Looking Glass from the relevant carriers at representative times is the quickest way to decide. The pricing page has the current plan details.

Security, privacy, and when not to self-host

Keep PostgreSQL private, retain the same APP_SECRET, patch both images, restrict backup access, and disable dashboard share URLs unless they are intentional. The collection endpoint is public by design. Anyone who obtains a website ID can submit fake events, so watch for report poisoning and disk growth. Apply proxy rate limits cautiously because a blunt limit can discard legitimate traffic bursts.

Analytics may involve consent, retention, deletion, data-location, or employee-monitoring obligations. IP-derived location and session identifiers may be personal data under applicable law. Review the current v3 session replay and heatmap features before enabling them because replay can capture sensitive page content or interactions. Umami sends anonymous product telemetry by default; the documented DISABLE_TELEMETRY=1 option disables it if your policy requires that.

Umami Cloud or another hosted analytics service is the better choice when nobody can own PostgreSQL backups, restores, migrations, monitoring, and privacy requests, or when you need vendor support, high availability, or a formal SLA. If basic request counts from web-server logs answer the question, a simpler single-binary log analyzer avoids a database, a tracker endpoint, and application migrations. Self-hosted Umami fits when its dashboard and event model are worth that ongoing operational work to you.

Version 2.20.15 was the current stable release when this article was checked on July 15, 2026. It fixes GHSA-8c6x-pfjq-9gr7, a low-severity flaw that let non-superusers delete superusers (releases before 2.20.14 are affected, 2.20.15 has the fix), and upstream recommends that all users upgrade. Read the 2.20.15 release notes and take a tested backup before upgrading.

A self-hosted Paperless-ngx server is an unmanaged deployment, so you run the operating system, TLS, access control, updates, monitoring, and recovery yourself and keep full control of the stack. Worth knowing up front: Paperless does not encrypt documents, extracted text, or filenames at rest. HTTPS protects traffic in transit; storage and backup encryption are separate decisions.

Prepare the VPS, DNS, and firewall

You need a VPS with root or sudo access, an A record for paperless.example.com, and off-server backup storage. Add an AAAA record only if IPv6 works through the host firewall and Caddy. Allow TCP 80 and 443 for HTTPS, plus the port used by administrative SSH. PostgreSQL, Redis, and Paperless port 8000 must never be public.

Install Docker Engine and the Compose plugin with Docker’s convenience script (or your distribution’s packages, if you’d rather not run a downloaded script as root):

curl -fsSL https://get.docker.com | sudo bash
sudo docker compose version

The remaining commands assume your account can run Docker. Otherwise, prefix each Docker command with sudo or follow Docker’s documented post-install procedure.

Install Caddy, UFW, and OpenSSL. Caddy also provides official package instructions if your distribution needs its repository.

sudo apt update
sudo apt install -y caddy ufw openssl
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Replace 22 before enabling UFW if SSH uses another port (our SSH hardening guide explains how to move it safely), and mirror the rules in the provider firewall. Docker can bypass some host firewall paths when a port is published, which is another reason to keep the application binding explicitly on 127.0.0.1.

Generate secrets without printing them

Create the project and its two host directories. Paperless watches consume for incoming files and writes application exports under export.

sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/paperless
sudo install -d -m 0750 -o "$USER" -g "$USER" \
  /opt/paperless/consume /opt/paperless/export
cd /opt/paperless

Generate a 256-bit Paperless secret and a 192-bit PostgreSQL password without displaying either value:

umask 077
{
  printf 'PAPERLESS_SECRET_KEY=%s\n' "$(openssl rand -hex 32)"
  printf 'PAPERLESS_DB_PASSWORD=%s\n' "$(openssl rand -hex 24)"
  printf 'USERMAP_UID=%s\n' "$(id -u)"
  printf 'USERMAP_GID=%s\n' "$(id -g)"
} > .env
chmod 600 .env

Keep .env unchanged across restarts and restores, and keep it out of tickets, terminal recordings, and Git. Paperless supports Docker secret files through _FILE variables if your secret-management system provides them; a mode-0600 file keeps this tutorial portable.

Create the Paperless Compose project

Create /opt/paperless/compose.yaml with the following content. It is a hardened single-VPS version of Paperless-ngx’s official PostgreSQL Compose file. The service roles and mount points follow upstream; the random database password, loopback port, webhook restrictions, health dependencies, and log limits are tutorial choices.

services:
  broker:
    image: redis:8
    restart: unless-stopped
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  db:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: "${PAPERLESS_DB_PASSWORD:?set PAPERLESS_DB_PASSWORD}"
    volumes:
      - pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U paperless -d paperless"]
      interval: 10s
      timeout: 5s
      retries: 5
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.15
    restart: unless-stopped
    depends_on:
      broker:
        condition: service_healthy
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:${PAPERLESS_HOST_PORT:-8000}:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: "${PAPERLESS_DB_PASSWORD:?set PAPERLESS_DB_PASSWORD}"
      PAPERLESS_URL: "${PAPERLESS_EXTERNAL_URL:-https://paperless.example.com}"
      PAPERLESS_ALLOWED_HOSTS: "${PAPERLESS_ALLOWED_HOSTS:-paperless.example.com}"
      PAPERLESS_SECRET_KEY: "${PAPERLESS_SECRET_KEY:?set PAPERLESS_SECRET_KEY}"
      PAPERLESS_TIME_ZONE: UTC
      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_TASK_WORKERS: "1"
      PAPERLESS_THREADS_PER_WORKER: "1"
      PAPERLESS_PROXY_SSL_HEADER: '["HTTP_X_FORWARDED_PROTO", "https"]'
      PAPERLESS_WEBHOOKS_ALLOWED_PORTS: "80,443"
      PAPERLESS_WEBHOOKS_ALLOW_INTERNAL_REQUESTS: "false"
      USERMAP_UID: "${USERMAP_UID:?set USERMAP_UID}"
      USERMAP_GID: "${USERMAP_GID:?set USERMAP_GID}"
    logging:
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  data:
  media:
  pgdata:
  redisdata:

Replace every paperless.example.com before starting. PAPERLESS_URL must have no trailing slash or path. The explicit allowed host removes the insecure public default of *. Caddy overwrites X-Forwarded-Proto, and only the loopback proxy can reach port 8000, so trusting that header is appropriate for this layout. PostgreSQL and Redis use the major-version tags from the upstream 2.20.15 template, so they pick up patch releases automatically.

Start the private stack and check the listener:

cd /opt/paperless
docker compose up -d --wait --wait-timeout 180
curl -fsSL http://127.0.0.1:8000/ > /dev/null
sudo ss -lntp | grep ':8000'

The listener must show 127.0.0.1:8000, not 0.0.0.0:8000.

Create the superuser before public access

Paperless can create an administrator from environment variables, but that leaves a plaintext password in long-lived configuration. Use the interactive management command from the official setup documentation instead:

cd /opt/paperless
docker compose exec webserver createsuperuser

Choose a non-obvious username, a real administrative email address, and a unique password from a password manager. The command hashes the password in the database and does not add it to .env or shell history. Do not add the public Caddy route until this command succeeds.

Put Caddy in front of Paperless

Paperless requires a TLS reverse proxy for Internet exposure. Its interface uses WebSocket connections, and uploads can exceed the small request-body defaults in some proxy examples. Caddy handles WebSocket upgrades and the standard forwarded headers automatically. Keep this site in a separate imported file so adding Paperless does not erase existing hosts. This block adds an explicit 100 MB proxy-side upload ceiling:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/paperless.caddy > /dev/null <<'CADDY'
paperless.example.com {
    request_body {
        max_size 100MB
    }
    reverse_proxy 127.0.0.1:8000
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsSI https://paperless.example.com/

Change the ceiling to match the largest document you intend to accept. A 413 Request Entity Too Large points to the proxy or an application upload limit, while a stalled interface can mean broken WebSocket forwarding. Nginx users must explicitly configure HTTP/1.1 upgrade headers and raise client_max_body_size; a bare proxy_pass is incomplete.

Sign in over HTTPS with the CLI-created account. Enable multi-factor authentication if your identity setup supports it, and do not create broad user accounts merely to feed the consume directory.

Verify a real upload and OCR result

A green health check only proves that the web process answers HTTP. Test the workflow with a harmless image-only scan that contains a unique phrase, such as paperless ocr test 20260714. A phone photograph saved as JPEG works, and it forces Paperless to run OCR rather than read an existing PDF text layer.

Upload the image from the web interface. Watch Tasks until consumption finishes, then open the document and confirm all of the following:

1. The original image opens and downloads.
2. The document page contains extracted text with the unique phrase.
3. Searching for that phrase returns the document.
4. The archived representation and thumbnail render correctly.

If processing fails, read the consumer and OCR output before raising resource limits:

cd /opt/paperless
docker compose logs --tail=250 webserver

OCR is CPU and memory intensive. Multiple languages increase processing time, and untrusted PDFs or oversized images can exhaust resources or hit bugs in parsers such as Ghostscript and ImageMagick. Keep PAPERLESS_TASK_WORKERS * PAPERLESS_THREADS_PER_WORKER at or below the VPS’s logical CPU count. The conservative one-by-one setting above is intentional. Do not disable image-pixel safeguards or allow anonymous uploads.

Back up with document_exporter

Provider snapshots help with whole-host recovery, but a snapshot taken while PostgreSQL and Paperless are writing may not be application consistent. Paperless’s backup documentation provides document_exporter to export documents, thumbnails, settings, and database content. API tokens are not included and must be recreated after recovery.

Pause watched mailboxes, scanners, and uploads, then wait for the Tasks view to become idle. Run the official exporter through Compose and checksum the result:

cd /opt/paperless
backup="backup-$(date +%F-%H%M%S)"
docker compose exec -T webserver \
  document_exporter "../export/$backup" --no-progress-bar
find "export/$backup" -type f -print0 \
  | sort -z \
  | xargs -0 -r sha256sum > "export/$backup.sha256"

Record the Paperless version (2.20.15) alongside the export; the importer requires an exact version match. Copy the export, checksum, compose.yaml, Caddy configuration, and encrypted secret material off the VPS. The export contains the documents you were trying to protect, so encrypt it and restrict access at the destination. A copy on the same disk is not a backup.

Rehearse an isolated same-version restore

Paperless requires document_importer to run against an empty installation of exactly the same version. The drill below builds that empty installation beside production, in its own Compose project on an alternate loopback port. A separate test VPS is safer, since a same-host drill shares the Docker daemon, RAM, disk, and port space with production; if you use one, copy the Compose file, .env, and the latest export there first and adjust the source paths.

For a same-host drill, keep all commands in one shell:

set -Eeuo pipefail
restore_project="paperless-restore-$(date +%Y%m%d%H%M%S)"
restore_dir="/opt/$restore_project"
backup_dir=$(find /opt/paperless/export -mindepth 1 -maxdepth 1 \
  -type d -name 'backup-*' | sort | tail -n 1)
backup_name=$(basename "$backup_dir")
sudo install -d -m 0700 -o "$USER" -g "$USER" \
  "$restore_dir/consume" "$restore_dir/export"
sudo install -m 0600 -o "$USER" -g "$USER" \
  /opt/paperless/.env "$restore_dir/.env"
sudo install -m 0640 -o "$USER" -g "$USER" \
  /opt/paperless/compose.yaml "$restore_dir/compose.yaml"
sudo cp -a "$backup_dir" "$restore_dir/export/"
sudo chown -R "$USER":"$USER" "$restore_dir"
cd "$restore_dir"
export PAPERLESS_HOST_PORT=18000
export PAPERLESS_EXTERNAL_URL=http://127.0.0.1:18000
export PAPERLESS_ALLOWED_HOSTS=127.0.0.1,localhost

docker compose -p "$restore_project" up -d --wait --wait-timeout 180
docker compose -p "$restore_project" exec webserver \
  document_importer "../export/$backup_name"
docker compose -p "$restore_project" exec webserver document_sanity_checker
curl -fsSL http://127.0.0.1:18000/ > /dev/null

The timestamped project name gives the drill its own containers, volumes, and network, so document_importer runs against a fresh, empty database. The importer still requires the export and target to use exactly the same Paperless version; an empty newer installation is not compatible.

Tunnel port 18000 over SSH, log in with a restored account, and inspect several originals, archived files, thumbnails, metadata, permissions, and searches. Recreate an API token if an integration needs one. The sanity checker catches internal inconsistencies, but it cannot prove that every document is readable or that an external integration still works.

After the rehearsal, remove the restore project and its isolated volumes:

cd "$restore_dir"
docker compose -p "$restore_project" down -v

Never run the importer over the production installation, and never use down -v in /opt/paperless; there it deletes the production volumes.

Upgrade and roll back deliberately

Before an upgrade, stop new ingestion, wait for active tasks, run document_sanity_checker, create a fresh exporter backup, and read every release note between the installed and target versions. Then update the version tag in compose.yaml.

Paperless’s official Docker procedure stops the stack, pulls, and starts it in the foreground so database migrations remain visible:

cd /opt/paperless
docker compose exec webserver document_sanity_checker
docker compose down
docker compose pull
docker compose up

Watch for migration or worker errors. In another SSH session, test login, search, and a fresh OCR upload. Then stop the foreground run with Ctrl+C and return it to detached mode:

cd /opt/paperless
docker compose up -d --wait --wait-timeout 180
docker compose exec webserver document_sanity_checker

Do not roll back by pointing an older image at a database migrated by a newer release. A safe rollback uses the pre-upgrade export with the old, exact Paperless version in a new empty deployment. Rehearse it on an alternate port, then switch Caddy only after documents, search, permissions, and OCR pass. PostgreSQL major upgrades need PostgreSQL’s own migration or a logical dump and restore; do not bundle them into a routine Paperless update.

Keep Tika and Gotenberg optional

The baseline handles the normal PDF and image workflow without Tika or Gotenberg. Enable the pair only if you need Office documents or email formats that require conversion. Paperless’s official Tika Compose template adds apache/tika and Gotenberg, then sets PAPERLESS_TIKA_ENABLED=1 and internal endpoints for both services.

That template uses gotenberg/gotenberg:8.25 and apache/tika:latest. The latter is a mutable tag; pin a specific version if you want repeatable deployments. Do not publish ports 3000 or 9998. Preserve the upstream Gotenberg arguments --chromium-disable-javascript=true and --chromium-allow-list=file:///tmp/.*; they reduce remote-content and JavaScript exposure while converting email. Tika and Gotenberg parse more untrusted formats and use more CPU and RAM, so they expand both the attack surface and the sizing requirement.

Choosing a Riven Cloud VPS for Paperless-ngx

For a personal document archive with the conservative one-worker OCR settings above, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is a comfortable starting point. Move up to Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB transfer) if you want faster OCR on a large backlog or plan to enable Tika and Gotenberg, and to Max (4 vCPU, 16 GB RAM, 160 GB NVMe, 4 TB transfer) when the originals, archived files, thumbnails, and PostgreSQL start crowding the disk. Storage tends to grow long after the initial import, while an OCR backlog only needs CPU for a while, so watching disk usage usually tells you first when it is time to resize. If the archive will share its VPS with other services, our roundup of self-hosted apps is a good place to gauge what co-hosts comfortably alongside an OCR workload.

All three plans include a 1 Gbps port, full root access, daily backups, and a choice of Tokyo or Singapore. The daily backups are a good safety net for whole-host recovery; keep the application-consistent exporter backups and the restore drill above in place as well. If you or your users connect from mainland China, take a moment to test the Tokyo Looking Glass and Singapore Looking Glass from your own network before choosing a location, then compare the current Riven Cloud VPS plans.

Security and privacy limits

Paperless removed its old built-in document encryption. Original and archived files are readable by the application, extracted document text is stored in plaintext in PostgreSQL, and filenames are not encrypted. Use an encrypted filesystem or encrypted block volume if you need protection from physical-media access, and always encrypt off-server exports. Access controls, TLS, and disk encryption solve different problems.

Workflow webhooks also deserve attention. Upstream defaults allow HTTP and HTTPS on any port and permit internal requests. The environment values above restrict ports to 80 and 443 and disable internal webhook requests, which reduces server-side request forgery risk. Treat those settings as one layer; container egress rules should also block cloud metadata and management networks, especially when less-trusted users can create workflows.

Do not accept uploads from anonymous or untrusted users. OCR and document parsers handle complex, attacker-controlled files and have no blanket sandbox guarantee from Paperless. Keep Paperless, the host, and every parser image patched; retain image-pixel limits; cap proxy upload size; and monitor CPU, memory, disk, and task queues.

Self-hosting Paperless-ngx works well when someone owns those controls, application-aware backups, restore tests, and security updates. If the archive needs built-in per-document encryption, contractual high availability, or formal records controls, a managed document system is the better home for it; a single unmanaged VPS is not designed to provide those guarantees.

This guide deploys linkding 1.45.0 from the official Docker Hub image on Debian or Ubuntu. Port 9090 stays bound to loopback, the first superuser is created before Caddy exposes the service, and host firewall rules block the container from private, link-local, and metadata address ranges.

Set up this way, linkding makes a pleasant private bookmark service for trusted users. The two habits worth keeping are treating the outbound fetcher as attack surface and testing your restores instead of assuming the copies work.

Prerequisites

Prepare:

• a Debian or Ubuntu VPS with root or sudo access;
• an A record for bookmarks.example.com pointing to the VPS, plus an AAAA record only when the complete IPv6 path is configured;
• TCP 80 and 443 for Caddy and your existing administrative SSH port;
• a trusted administrator account and no plan to offer open registration;
• encrypted off-server backup storage;
• an unused private Docker subnet. This guide uses 172.31.50.0/24.

Check that the example subnet does not overlap an existing host or container route:

ip route
sudo docker network ls

If it overlaps, choose another unused RFC1918 /24 and replace both 172.31.50.0/24 and 172.31.50.10 everywhere below.

Install Docker Engine and the Compose plugin with Docker’s convenience script (skim it first if you want to know what it changes), then install the remaining packages:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo docker compose version

sudo apt update
sudo apt install -y caddy ufw jq unzip

The script runs as root and adds Docker’s package repository; if that is unacceptable on your host, install Docker from your distribution’s packages instead.

Keep SSH allowed when configuring UFW. Replace port 22 if necessary:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Apply the same inbound policy in any provider firewall. Port 9090 must never be public.

Create the linkding Compose project

The official installation guide uses one container, SQLite, and a persistent /etc/linkding/data mount. Its data directory holds db.sqlite3, secretkey.txt, page assets, favicons, preview images, and background-task state.

Create the project, data, and backup directories:

sudo install -d -m 750 -o "$USER" -g "$USER" /opt/linkding
cd /opt/linkding
umask 077
install -d -m 700 data backups
install -m 600 /dev/null .env

Create /opt/linkding/.env:

tee .env > /dev/null <<'ENV'
LD_DISABLE_URL_VALIDATION=False
LD_CSRF_TRUSTED_ORIGINS=https://bookmarks.example.com
LD_USE_X_FORWARDED_HOST=False
LD_LOG_X_FORWARDED_FOR=False
ENV
chmod 600 .env

Keeping LD_DISABLE_URL_VALIDATION=False preserves the normal HTTP/HTTPS syntax check. It does not make arbitrary destinations safe. LD_USE_X_FORWARDED_HOST=False avoids trusting a client-controlled forwarding header because Caddy preserves the ordinary Host header.

Create /opt/linkding/compose.yaml:

tee compose.yaml > /dev/null <<'YAML'
services:
  linkding:
    image: docker.io/sissbruecker/linkding:1.45.0
    container_name: linkding
    restart: unless-stopped
    ports:
      - "127.0.0.1:9090:9090"
    volumes:
      - ./data:/etc/linkding/data
    env_file:
      - .env
    networks:
      linkding_outbound:
        ipv4_address: 172.31.50.10
    logging:
      options:
        max-size: "10m"
        max-file: "3"

networks:
  linkding_outbound:
    ipam:
      config:
        - subnet: 172.31.50.0/24
YAML

The custom network intentionally has no IPv6. Do not enable Docker IPv6 for this service until equivalent IPv6 egress rules block ::1, fc00::/7, fe80::/10, and any provider-specific metadata destinations.

Start the container and check the listener:

cd /opt/linkding
sudo docker compose up -d --wait --wait-timeout 180
curl -fsS http://127.0.0.1:9090/health
sudo ss -lntp | grep ':9090'

The official health endpoint checks the database connection and should return JSON with version 1.45.0 and status healthy. The host listener must be 127.0.0.1:9090.

Block private and metadata egress

linkding fetches page metadata with server-side HTTP requests. The plus image also runs Chromium and downloads PDF or HTML snapshots. The 1.45.0 validator delegates to Django’s URL validator and does not reject loopback, RFC1918, link-local, cloud metadata, or DNS answers that resolve there.

Install persistent iptables support, then add rules scoped to the fixed container address. The first rule permits reply traffic for connections initiated toward the published application port. The remaining rules reject new container connections to non-public IPv4 ranges, including 169.254.169.254 within 169.254.0.0/16.

sudo DEBIAN_FRONTEND=noninteractive apt-get install -y iptables-persistent

sudo iptables -C DOCKER-USER -s 172.31.50.10 \
  -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT 2>/dev/null \
  || sudo iptables -I DOCKER-USER 1 -s 172.31.50.10 \
  -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

for cidr in \
  0.0.0.0/8 10.0.0.0/8 100.64.0.0/10 127.0.0.0/8 \
  169.254.0.0/16 172.16.0.0/12 192.0.0.0/24 \
  192.168.0.0/16 198.18.0.0/15 224.0.0.0/4 240.0.0.0/4
do
  sudo iptables -C DOCKER-USER -s 172.31.50.10 -d "$cidr" -j REJECT 2>/dev/null \
    || sudo iptables -I DOCKER-USER 2 -s 172.31.50.10 -d "$cidr" -j REJECT
done

sudo netfilter-persistent save

These rules block routed private destinations after DNS resolution, so they also help against redirects and DNS rebinding. They do not make linkding safe for hostile tenants: a request to loopback inside the same container never traverses the host’s forwarding chain, and public destinations remain reachable. Keep every account trusted and isolate sensitive services from this Docker network.

After any Docker or firewall change, rerun this test from inside the container. It must reach a public site and fail on both blocked destinations:

sudo docker compose exec -T linkding python - <<'PY'
from urllib.error import HTTPError, URLError
from urllib.request import ProxyHandler, build_opener

opener = build_opener(ProxyHandler({}))
with opener.open("https://example.com/", timeout=15) as response:
    assert 200 <= response.status < 400

for url in (
    "http://169.254.169.254/latest/meta-data/",
    "http://192.168.0.1/",
):
    try:
        opener.open(url, timeout=5)
    except HTTPError as exc:
        raise SystemExit(f"blocked destination returned HTTP {exc.code}: {url}")
    except URLError:
        pass
    else:
        raise SystemExit(f"blocked destination was reachable: {url}")
PY

The test covers routed destinations only. It says nothing about loopback inside the linkding container, other special-purpose prefixes, an IPv6 path, or a future Docker network with a different source address. Review the rules whenever networking changes.

Create the superuser before public exposure

The linkding image has no default user. Its official user setup provides an interactive Django command. Run it while port 9090 is still loopback-only so the password does not enter Compose, .env, or shell history:

cd /opt/linkding
sudo docker compose exec linkding \
  python manage.py createsuperuser \
  --username=admin \
  --email=admin@example.com

Enter a strong unique password at the prompts. Do not set LD_SUPERUSER_PASSWORD for this deployment; it would leave a reusable administrator credential in the container environment.

Open an SSH tunnel from your workstation:

ssh -N -L 9090:127.0.0.1:9090 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:9090, sign in, sign out, and sign in again. Confirm that there is no public sign-up flow. Close the tunnel only after the account works.

Put Caddy in front of loopback port 9090

Caddy preserves the original Host header, which linkding needs for login and form submissions. Add the public route only after the administrator test:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/linkding.caddy > /dev/null <<'CADDY'
bookmarks.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:9090
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Caddy will obtain a certificate once DNS, UFW, and any provider firewall permit TCP 80/443. Check the redirect and the health endpoint:

curl -fsSI http://bookmarks.example.com/
curl -fsS https://bookmarks.example.com/health | jq .

If a save or login request returns 403 CSRF verification failed, confirm that .env contains the exact origin with the https:// scheme and no path. Do not solve it by trusting every origin or by publishing port 9090.

Run UI and API bookmark tests

Log in at https://bookmarks.example.com and create a bookmark for https://example.com. Set the title to Compose UI test, add the tag compose-test, and put Created through the browser in the description or notes field. Save, reload the page, search for Compose UI test, and confirm the title, tag, and note survive. This browser check tests persistence, not automatic metadata fetching.

Restart the container and check the same bookmark again:

cd /opt/linkding
sudo docker compose restart linkding
sudo docker compose up -d --wait --wait-timeout 180
curl -fsS https://bookmarks.example.com/health | jq -e \
  '.status == "healthy" and .version == "1.45.0"'

linkding creates an API token for each user in the Settings page. Read it without echoing, then create a bookmark through the official REST API without supplying a title. A nonempty title in the saved record proves that server-side metadata fetching ran:

set -Eeuo pipefail
read -rsp 'linkding API token: ' LINKDING_TOKEN
echo
bookmark_id=''
cleanup_api_test() {
  local rc=$?
  if [ -n "$bookmark_id" ]; then
    curl -fsS -o /dev/null -X DELETE \
      -H "Authorization: Token $LINKDING_TOKEN" \
      "https://bookmarks.example.com/api/bookmarks/$bookmark_id/" || true
  fi
  unset LINKDING_TOKEN
  return "$rc"
}
trap cleanup_api_test EXIT

response=$(curl -fsS -X POST \
  -H "Authorization: Token $LINKDING_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://www.iana.org/help/example-domains","description":"Created through REST API","tag_names":["compose-test"]}' \
  https://bookmarks.example.com/api/bookmarks/)

bookmark_id=$(printf '%s' "$response" | jq -er '.id')
for attempt in $(seq 1 12); do
  saved=$(curl -fsS \
    -H "Authorization: Token $LINKDING_TOKEN" \
    "https://bookmarks.example.com/api/bookmarks/$bookmark_id/")
  if jq -e '.title | type == "string" and length > 0' \
    <<<"$saved" > /dev/null; then
    break
  fi
  [ "$attempt" -lt 12 ] || {
    echo 'linkding did not fetch a title within 60 seconds' >&2
    exit 1
  }
  sleep 5
done
printf '%s' "$saved" | jq '{id,url,title,tag_names}'

curl -fsS -o /dev/null -X DELETE \
  -H "Authorization: Token $LINKDING_TOKEN" \
  "https://bookmarks.example.com/api/bookmarks/$bookmark_id/"
bookmark_id=''
unset LINKDING_TOKEN response saved
trap - EXIT