Installation#

PosternProxy installs directly on Debian 11/12 or Ubuntu 22.04/24.04. No Docker required.

Prerequisites#

• A fresh Debian or Ubuntu server with root access
• Ports 80, 443, and 81 open in your firewall
• A domain or IP for the management UI

Automated install#

The install script handles everything: installing the bundled Caddy, creating system users, configuring systemd, UFW, fail2ban, and unattended-upgrades.

Step 1 — Download the release binaries

Download the latest release from the GitHub releases page. Each release provides three binaries for your server’s architecture (amd64 for most servers, arm64 for ARM):

The installer looks for the binaries named exactly posternproxy, posternproxy-agent, and caddy. If the release assets carry a platform suffix (e.g. posternproxy-linux-amd64), rename them to the bare names above.

**Prefer to build it yourself?** See [Building from source](/getting-started/building-from-source/) for building the binaries on Linux or Windows.

Step 2 — Copy the binaries and the install script to the server

Put the three binaries and install.sh in one directory — the installer finds the binaries in the directory it runs from. The install script ships with the release; it is also available at scripts/install.sh in the repository.

ssh root@your-server 'mkdir -p /tmp/posternproxy'
scp posternproxy posternproxy-agent caddy install.sh root@your-server:/tmp/posternproxy/

Notes:

• The caddy binary is the custom build from Step 1. Shipping it means the installer skips compiling Caddy on the server, so no Go toolchain is installed on production. If you omit it, the installer falls back to building Caddy from source (and installs Go to do so).
• The posternproxy-agent binary is optional for a controller-only install, but it is required for provisioning remote nodes — copy it now to avoid a second trip.

Step 3 — Run the install script

ssh root@your-server
bash /tmp/posternproxy/install.sh

The script will:

1. Install the custom Caddy binary you shipped (or, if none was shipped, install Go and build Caddy with the L4 and rate-limit plugins on the server)
2. Create caddy and posternproxy system users (no login shell)
3. Generate a random JWT secret and write /etc/posternproxy/config.env
4. Install hardened systemd services for both Caddy and PosternProxy
5. Apply sysctl hardening (IP forwarding, rp_filter, TCP SYN cookies)
6. Configure UFW (allow ports 80, 443, 81)
7. Install and configure fail2ban with a PosternProxy login-failure jail
8. Enable unattended security upgrades
9. Optionally harden SSH (disable root login, enforce key-only auth)

**SSH hardening prompt** The installer asks whether to harden SSH. If you choose yes, ensure your SSH key is in `~/.ssh/authorized_keys` before logging out — password auth will be disabled.

Post-install#

Once complete, the UI is available at:

http://<your-server-ip>:81

On first boot, PosternProxy creates an admin account and prints a generated password to stderr, which the systemd service writes to its log file (not the journal). Check it immediately after startup:

grep -A6 "INITIAL SETUP" /var/log/posternproxy/posternproxy.log

The banner looks like:

╔══════════════════════════════════════════════════════╗
║           POSTERNPROXY — INITIAL SETUP               ║
╟──────────────────────────────────────────────────────╢
║  Email:    admin@posternproxy.local                  ║
║  Password: <random 20-character password>            ║
╟──────────────────────────────────────────────────────╢
║  Change this password immediately after first login. ║
║  Set POSTERNPROXY_ADMIN_PASSWORD to silence this.    ║
╚══════════════════════════════════════════════════════╝

Log in with the email and generated password shown, then change it immediately.

**Setting a fixed admin password** Set `POSTERNPROXY_ADMIN_PASSWORD` in `/etc/posternproxy/config.env` before the first boot to use a specific password instead of a generated one.

**Lost the generated password?** If you missed the banner, use the `reset-password` subcommand to recover access without running the server. Run it as the `posternproxy` user with the config loaded, so it uses the correct database path and does not create root-owned database files: ```bash sudo -u posternproxy bash -c 'set -a; . /etc/posternproxy/config.env; set +a; \ /usr/local/bin/posternproxy reset-password' # or for a specific account, append: --email admin@posternproxy.local ``` A new random password is printed to the terminal.

Environment variables#

PosternProxy is configured via /etc/posternproxy/config.env. All variables are optional — sensible defaults are used if not set.

Systemd management#

# Check status
systemctl status posternproxy
systemctl status caddy

# View logs
journalctl -u posternproxy -f
journalctl -u caddy -f

# Restart
systemctl restart posternproxy

Caddy plugins included#

The install script builds Caddy with two plugins beyond the standard distribution: