PosternProxy Documentation

Installation

Mon, 01 Jan 0001 00:00:00 +0000

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: building Caddy with required plugins, creating system users, configuring systemd, UFW, fail2ban, and unattended-upgrades.

Step 1 — Build the binary

On your development machine (or CI), run:

Load Balancing

Mon, 01 Jan 0001 00:00:00 +0000

Load Balancing#

PosternProxy supports distributing traffic across multiple upstream backends for a single proxy host. Configuration is on the Upstreams tab of the Add/Edit Proxy Host modal.

Adding backends#

The first upstream is always the Primary backend (set on the Details tab). Additional backends are added on the Upstreams tab. Each extra backend requires:

Host / IP — the internal address of the backend server
Port — the port the backend listens on

There is no enforced limit on the number of backends.

Provisioning

Mon, 01 Jan 0001 00:00:00 +0000

Server Provisioning#

PosternProxy automates the full setup of a remote server via SSH. This page documents what the provisioner does and how to troubleshoot it.

Prerequisites#

The remote server must have:

Debian 11/12 or Ubuntu 22.04/24.04
Root access (or a user with passwordless sudo)
Port 22 open (SSH)
Outbound internet access (to download packages and Let’s Encrypt)
Outbound access to the controller on port 81 (for the agent WebSocket)

What the provisioner installs#

Caddy#

The provisioner builds Caddy from source using xcaddy, including the required plugins:

Security Hardening

Mon, 01 Jan 0001 00:00:00 +0000

Security Hardening#

The PosternProxy install script applies a comprehensive set of security hardening measures. This page documents what is applied and how to verify it.

Application-level hardening#

Authentication#

JWT access tokens with 15-minute TTL
Refresh tokens with 7-day TTL stored in HttpOnly / Secure / SameSite=Strict cookies
bcrypt password hashing at cost factor 12
Login rate limit: 5 attempts/min per IP (enforced by the API and by fail2ban)
Account lockout is not time-based — use fail2ban to block IPs

API security#

Rate limiting: 120 requests/min per IP on authenticated management API routes; 5 login attempts/min per IP; 30 agent WebSocket connection attempts/min per IP
CSRF protection: Double-submit cookie pattern on all state-changing requests
Secure headers on all responses:
- X-Content-Type-Options: nosniff
- X-Frame-Options: DENY
- Strict-Transport-Security: max-age=31536000; includeSubDomains
- Content-Security-Policy: default-src 'self'
Input validation: All user input validated at the handler layer; domain names validated per RFC 1123; ports validated 1–65535; CIDRs parsed and validated; all database queries use parameterized statements (no SQL interpolation)

Encrypted storage#

DNS provider credentials and SSH credentials are encrypted at rest using AES-256-GCM with a key derived from the JWT secret.

Health Checks

Mon, 01 Jan 0001 00:00:00 +0000

Health Checks#

PosternProxy exposes Caddy’s built-in health-check machinery through the Health tab of the proxy host form. Health checks keep your load balancer from routing traffic to backends that are down or degraded.

Active health checks#

Active checks probe each upstream on a schedule by sending an HTTP request and evaluating the response.

Setting	Default	Description
Path	`/`	URL path Caddy requests on each backend
Interval	`30s`	How often to run the check
Timeout	`5s`	Maximum time to wait for a response
Expected status	`200`	HTTP status code that counts as healthy

Enable active checks with the Enable health checks toggle on the Health tab.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

Quick Start#

This guide walks you through the most common first-day tasks after installation.

1. Log in and change the default password#

Open http://<server-ip>:81 in your browser.

On first boot, PosternProxy generates a random admin password and prints it to the service logs. Retrieve it before logging in:

journalctl -u posternproxy --no-pager | grep -A5 "INITIAL SETUP"

Email: admin@posternproxy.local (or the value of POSTERNPROXY_ADMIN_EMAIL)
Password: the generated password from the startup banner above

Immediately navigate to Users → (your account) → Change Password and set a strong password.

Upgrading

Mon, 01 Jan 0001 00:00:00 +0000

Upgrading PosternProxy#

Upgrading the controller#

Build the new binary on your development machine:
```
bash scripts/build.sh
```
Copy the binary to the server:
```
scp posternproxy user@your-server:/tmp/
```

Stop the service, replace the binary, restart:

ssh root@your-server
systemctl stop posternproxy
cp /tmp/posternproxy /usr/local/bin/posternproxy
systemctl start posternproxy

Verify the service started:

systemctl status posternproxy
journalctl -u posternproxy -n 20

Database migrations#

PosternProxy runs embedded migrations automatically on startup. If a new version adds database columns or tables, the migration runs before the service starts serving requests. No manual intervention is needed.

SSL / TLS

Mon, 01 Jan 0001 00:00:00 +0000

SSL / TLS#

PosternProxy leverages Caddy’s automatic HTTPS to handle TLS with minimal configuration. The SSL tab controls certificate selection and security options.

Automatic Let’s Encrypt (default)#

Leave the SSL Certificate field set to None / Caddy automatic. Caddy will:

Obtain a certificate from Let’s Encrypt the first time a request arrives for the domain
Store the certificate in its managed certificate store
Renew automatically before expiry

Requirements for automatic certificates:

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting#

Service not starting#

PosternProxy fails to start#

journalctl -u posternproxy -n 50 --no-pager

Common causes:

Symptom	Cause	Fix
`database is locked`	Another PosternProxy instance is running	`systemctl stop posternproxy; systemctl start posternproxy`
`migration failed`	Bad database state	Restore from backup
`address already in use :81`	Another process owns port 81	`ss -tlnp \| grep 81` to find it
`config.env not found`	Missing config file	Re-run `scripts/install.sh` or create manually

Caddy fails to start#

journalctl -u caddy -n 50 --no-pager
caddy validate --config /etc/caddy/Caddyfile # if using Caddyfile fallback

Common causes:

Rate Limiting

Mon, 01 Jan 0001 00:00:00 +0000

Rate Limiting#

PosternProxy can cap the number of requests a single IP address can make to a proxy host within a sliding time window. Rate limiting is configured on the Security tab.

How it works#

Rate limiting is implemented via the caddy-ratelimit Caddy plugin, which is included in the PosternProxy Caddy build.

When a client exceeds the limit, Caddy returns a 429 Too Many Requests response. The limit resets on a sliding window basis — it is not a hard per-minute bucket.

TLS Passthrough

Mon, 01 Jan 0001 00:00:00 +0000

TLS Passthrough#

TLS Passthrough lets Caddy forward encrypted TLS connections directly to an upstream without terminating (decrypting) them. The upstream handles TLS itself — Caddy never sees the plaintext.

When to use it#

Use TLS Passthrough when:

The upstream requires mutual TLS (mTLS) / client certificates that Caddy cannot forward
The upstream is a database or other service presenting its own TLS certificate
You need end-to-end encryption between client and upstream with no proxy in the middle
The upstream uses a private CA certificate that Caddy cannot validate

How to enable#

On the Details tab, toggle TLS Passthrough on. When enabled:

Custom Error Pages

Mon, 01 Jan 0001 00:00:00 +0000

Custom Error Pages#

PosternProxy can serve custom HTML pages when a proxy host returns a 404, 502, or 503 status code. This replaces Caddy’s default plain-text error responses with your own branded or user-friendly HTML.

Configuration#

Open the Errors tab of the Add/Edit Proxy Host modal. You will see three panels, one for each supported status code:

Code	Meaning	Common cause
404	Not Found	Route exists but upstream returned 404; or path not matched
502	Bad Gateway	Upstream is down or returned an invalid response
503	Service Unavailable	Upstream is overloaded or in maintenance mode

Paste your HTML into the relevant textarea. Leave a field blank to use Caddy’s default behaviour for that code.

Custom Headers

Mon, 01 Jan 0001 00:00:00 +0000

Custom Headers#

PosternProxy can inject, modify, or remove HTTP headers on requests sent to your upstream and on responses returned to clients. Header rules are configured on the Headers tab.

Adding a rule#

Each rule has four fields:

Field	Options	Description
Direction	Request / Response	Whether the rule applies to the upstream request or the downstream response
Operation	Set / Add / Delete	What to do with the header
Name	Any string	The header name (case-insensitive)
Value	Any string	The header value (not used for Delete)

Click + Add Rule to insert a new row. Rows with an empty Name are ignored on save.

Custom Locations

Mon, 01 Jan 0001 00:00:00 +0000

Custom Locations#

Custom locations let you override proxy behaviour for specific URL paths within a proxy host. They are configured on the Locations tab.

What locations do#

By default, a proxy host forwards all paths to the same upstream. Locations allow you to:

Send /api/* to a different backend than /
Apply different forward_scheme per path
Set path-specific Caddy directives using Advanced Config

Adding a location#

Click + Add Location on the Locations tab. Each location has:

Config History

Mon, 01 Jan 0001 00:00:00 +0000

Config History#

PosternProxy records a snapshot of every proxy host’s configuration before each change. You can browse the history and roll back to any previous state.

Viewing history#

Open the ⋮ menu on any proxy host row in the table and click History. A drawer slides open showing the last 100 snapshots in reverse chronological order.

Each entry shows:

Timestamp of the change
The user who made it
A brief diff of what changed

Rolling back#

Click Restore on any snapshot to revert the proxy host to that state. PosternProxy will: