Documentation navigation

Wayfarer

Self-host Wayfarer

This guide is for the person who installs and operates a Wayfarer instance. The supported production path is Linux with Docker Engine and Compose, managed by the self-contained wayfarerctl operator.

If you only use an existing instance, start with the user guide. If you intentionally run Wayfarer directly under systemd/Nginx instead of Compose, use the advanced native/manual guide.

Supported production path

Wayfarer supports Linux AMD64 and ARM64 through the same Compose lifecycle. The normal installation consists of:

The supported Compose lifecycle starts at v1.9.21. Current operators reject public setup/update selectors below that floor. Existing native/systemd installations are a separate deployment family: automated native-to-Compose migration is not currently supported.

You do not need a source checkout or host installations of .NET, Node, PostgreSQL, Nginx or Certbot for the supported Compose path.

Before you begin

Prepare a host with:

Remote Docker contexts, Docker Desktop and rootless Docker are outside the accepted production topology.

For host sizing, measured history latency, protective limits and index-upgrade requirements, read Hardware and history performance. Its local workstation measurements do not establish minimum hardware or production capacity.

For managed HTTPS, also prepare a public DNS hostname that resolves to the host and make 80/TCP, 443/TCP and 443/UDP available. If you already operate a reverse proxy, use external mode instead.

Download and verify the bootstrap

From the official Wayfarer Releases, download the platform archive:

The archive contains the standalone wayfarerctl executable, not the full deployment bundle.

Verify the archive SHA-256 against the REST asset digest for that exact GitHub Release before running it. The adjacent .sha256 file is useful as an integrity check, but it is not a substitute for authenticating the Release asset itself.

AMD64 example:

sha256sum wayfarerctl-linux-amd64.tar.gz
sha256sum --check wayfarerctl-linux-amd64.tar.gz.sha256
tar -xzf wayfarerctl-linux-amd64.tar.gz
chmod +x wayfarerctl

Keep the verified bootstrap at a stable root-owned location for later management, for example /usr/local/lib/wayfarer-bootstrap/.

Run guided setup

From an interactive root terminal:

sudo ./wayfarerctl setup

Bare setup resolves the latest supported stable release for your platform, downloads and verifies its deployment bundle, pulls the exact immutable container images named by that bundle, then guides you through:

The administrator password is entered hidden and confirmed. Production requires at least 15 characters with uppercase, lowercase, a digit and a non-alphanumeric character.

Setup then performs the protected database/application initialization and does not report success until the selected ingress path is healthy.

Install one exact stable version

sudo ./wayfarerctl setup --version X.Y.Z

Use this when you intentionally need an exact supported release. It follows the same acquisition and verification path as bare setup.

Use a trusted local bundle

For controlled offline/staging work:

sudo ./wayfarerctl setup --bundle /absolute/trusted/bundle

The bundle must be complete, canonical and trusted, and its exact images must already be present locally. --version and --bundle are mutually exclusive.

Choose an ingress mode

Managed Caddy

Managed mode is the simplest public deployment. Caddy owns the public listener and automatic HTTPS. PostgreSQL remains private.

Setup verifies public HTTPS health before completion. DNS, firewall, port conflicts and public CA reachability are administrator responsibilities; the operator does not modify them for you.

External reverse proxy

External mode runs no Caddy service and exposes Wayfarer only on 127.0.0.1:PORT (default 8080). Your proxy must:

Wayfarer verifies loopback readiness, while public TLS/proxy correctness remains your responsibility.

Understand installation state

The default deployment root is:

/etc/wayfarer

It contains retained releases, generated deployment inputs, secrets, lifecycle receipts and recovery state. Treat the whole deployment root as protected operator state. Do not edit generated files independently or move retained release directories to make a command succeed.

After setup, run normal commands through the stable bootstrap so it can select the correct retained operator:

/usr/local/lib/wayfarer-bootstrap/wayfarerctl \
  --deployment-root /etc/wayfarer dispatch status

See wayfarerctl reference.

First checks after installation

Run:

wayfarerctl status
wayfarerctl doctor

Then:

  1. open the public HTTPS address;
  2. sign in as admin;
  3. enable two-factor authentication;
  4. review Admin > Settings;
  5. leave registration closed unless you deliberately want public account creation;
  6. configure and verify backups before treating the instance as durable.

For daily work, continue with Operations.

What must be backed up

A recoverable Wayfarer instance is more than its PostgreSQL database.

Keep together:

The key ring is required to decrypt durable protected data such as personal provider credentials. Database-only backup is therefore incomplete once protected credentials exist.

Caches, thumbnails and logs are rebuildable and are not recovery substitutes.

Use the managed backup/restore path in Operations rather than assembling ad-hoc copies while writers are active.

Supported boundaries

The Compose operator intentionally fails closed instead of guessing around contradictory state.

Important limits:

If a command reports unresolved protected state, preserve that state and follow the reported resume/recovery action. Do not delete receipts, locks, volumes or generated files merely to get past a refusal.

Next steps

Documentation home

Back to top