Skip to main content
The supported v1 topology is one Harly app, PostgreSQL 16, one scheduler, and optional Caddy, all managed by Docker Compose. PostgreSQL has no published host port.

​
After reading this

  • You will know the CPU, RAM, and disk profile to provision for your team size
  • You will know which software versions the VPS needs
  • You will have DNS pointed at the VPS before running the installer

​
VPS requirements

Harly pulls a prebuilt image; the VPS does not compile Next.js or need pnpm. For a small installation (roughly 1-10 concurrent users): Use 64-bit Linux (amd64 or arm64), Docker Engine 24+, Compose 2.20+, and PostgreSQL 16 (bundled by default). Caddy mode also requires public ports 80 and 443 plus working DNS. External and local modes only bind Harly to loopback.
Actual disk capacity must include database growth, attachments, and backups. S3 storage removes attachment growth from the VPS but not database growth.

​
Point DNS at the VPS

Before running the installer, point a domain or, preferably, a subdomain such as careers.example.com at the VPS public IP:
  1. Create an A record for the public IPv4 address.
  2. Create an AAAA record only when IPv6 is actually configured and reachable.
  3. Verify propagation:
Remove stale or incorrect records. Caddy cannot issue a certificate until the hostname resolves to this server.

​
Open the required ports

For automatic Caddy mode, no other service or Docker container may publish TCP port 80, TCP port 443, or UDP port 443. Allow inbound TCP 80/443 in the VPS firewall or cloud security group, plus UDP 443 if you want HTTP/3. If Nginx, Apache, Traefik, or another Caddy instance already owns those ports, keep it and select the external proxy mode instead; it must forward the hostname to 127.0.0.1:3000.

​
Resource profiles and memory

The CLI selects a resource profile automatically based on free memory at install time. You can override with HARLY_RESOURCE_PROFILE or by setting individual limits in .env. On a 2 GB VPS, enable 1 GB of swap and the installer will select compact automatically, or set it explicitly:
To override individual limits after installation:
These are hard container ceilings, not reservations.

​
Managed cloud deployments

Choose a managed platform from the cloud deployment guide instead of a VPS when you want the provider to manage the host lifecycle. Managed platforms terminate HTTPS themselves and require S3-compatible uploads. Read configuration before adding provider credentials.

​
Troubleshooting

​
Caddy will not obtain a certificate

Symptom: the installer or doctor reports a stuck or failed TLS challenge. Cause: DNS has not propagated, or another process already holds port 80 or 443. Solution: re-run dig +short A <your-domain> to confirm it resolves to the VPS IP, then check for a process on the required ports before retrying.

​
Installer reports insufficient memory

Symptom: the wizard warns about RAM during the preflight check. Cause: the VPS has less than 2 GB RAM without swap configured. Solution: enable 1 GB of swap and apply the 2 GB memory profile above before continuing.

Quickstart

Run the guided installer once DNS and the VPS are ready.

Proxy modes

Choose Caddy, an external reverse proxy, or local-only.

Configuration

Required secrets, storage, cron, and optional integration variables.