> ## Documentation Index
> Fetch the complete documentation index at: https://docs.harly.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-hosting overview

> VPS requirements, memory profiles, and DNS setup for a supported Harly deployment.

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):

| Profile      |    CPU |              RAM |                  Free disk | Use                                  |
| ------------ | -----: | ---------------: | -------------------------: | ------------------------------------ |
| Minimum      | 2 vCPU | 2 GB + 1 GB swap |         10 GB plus uploads | Trial or very light traffic          |
| Recommended  | 2 vCPU |             4 GB | 20 GB plus uploads/backups | Normal small-team production         |
| Growing team | 4 vCPU |             8 GB |               40 GB+ or S3 | More concurrency and mailbox/AI work |

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.

<Note>
  Actual disk capacity must include database growth, attachments, and backups. S3 storage removes attachment growth from the VPS but not database growth.
</Note>

## 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:

```bash theme={null}
dig +short A careers.example.com
```

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](/self-hosting/proxy-modes) 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`.

| Profile       | When auto-selected  | App     | PostgreSQL | Scheduler | Caddy  |
| ------------- | ------------------- | ------- | ---------- | --------- | ------ |
| `compact`     | Free RAM \< 1.5 GB  | 1024 MB | 384 MB     | 192 MB    | 128 MB |
| `standard`    | Free RAM 1.5–3.5 GB | 1536 MB | 768 MB     | 256 MB    | 256 MB |
| `performance` | Free RAM > 3.5 GB   | 3072 MB | 1536 MB    | 512 MB    | 256 MB |

On a 2 GB VPS, enable 1 GB of swap and the installer will select `compact`
automatically, or set it explicitly:

```dotenv theme={null}
HARLY_RESOURCE_PROFILE=compact
```

To override individual limits after installation:

```dotenv theme={null}
HARLY_APP_MEMORY=1024m
HARLY_APP_NODE_OPTIONS=--max-old-space-size=640
HARLY_POSTGRES_MEMORY=384m
HARLY_MIGRATE_MEMORY=512m
HARLY_SCHEDULER_MEMORY=192m
HARLY_CADDY_MEMORY=128m
```

These are hard container ceilings, not reservations.

## Managed cloud deployments

Choose a managed platform from the [cloud deployment guide](/deployment/cloud)
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](/deployment/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.

## Related pages

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Run the guided installer once DNS and the VPS are ready.
  </Card>

  <Card title="Proxy modes" icon="route" href="/self-hosting/proxy-modes">
    Choose Caddy, an external reverse proxy, or local-only.
  </Card>

  <Card title="Configuration" icon="sliders" href="/deployment/configuration">
    Required secrets, storage, cron, and optional integration variables.
  </Card>
</CardGroup>