Configure it once. Query it whenever you want.

§ 01How Porta is configured#

Porta separates bootstrap from content. A handful of environment variables decide where the gateway listens, where it stores certificates and where its configuration comes from. Everything else — routes, domains, TLS policy — lives in configuration sources that Porta re-reads while it runs.

The mental model#

A running gateway holds three independent config dimensions, each fed by an ordered list of sources:

• routes — hostname/path → backend, plus per-route behaviour.
• profiles — named, reusable header transform sets that routes can point at.
• tls — the ACME account, server-wide TLS policy, the domain list, and any private CAs.

Within a dimension, sources are merged in manifest order and the last source wins on a collision. That is what makes the common layout work: a YAML file supplies the stable base, a database supplies the volatile per-customer rows on top.

Ports and pipelines#

Porta binds up to four listeners, each with its own middleware pipeline. They never share auth or TLS behaviour.

The HTTP listener is opt-in. With GATEWAY_HTTP_REDIRECT_ENABLED=false (the default) port 80 is opened only for the duration of an HTTP-01 validation and closed again afterwards, so nothing occupies it in normal operation.

§ 02A complete configuration#

Three files and a handful of environment variables describe a full gateway: a manifest that says where configuration comes from, a routing file, and a TLS file. The same set applies unchanged however Porta is started.

/etc/porta/
├── porta.yaml        # manifest — which sources to read
├── routes.yaml       # routing
└── tls.yaml          # ACME account, domains, TLS policy

routes:
  - type: file
    path: /etc/porta/routes.yaml
tls:
  - type: file
    path: /etc/porta/tls.yaml

- match:
    host: app.example.com
  backend:
    url: http://127.0.0.1:5001
  preserve_host: true
  set_x_real_ip: true

acme:
  email: ops@example.com

defaults:
  renewal_threshold_days: 30
  min_tls_version: "1.2"

domains:
  - name: app.example.com
    challenge: http-01

GATEWAY_MANIFEST=/etc/porta/porta.yaml
GATEWAY_CERT_STORAGE=/var/gateway
GATEWAY_CERT_PFX_PASSWORD=change-me
GATEWAY_PUBLIC_PORT=443
GATEWAY_HTTP_REDIRECT_ENABLED=true
GATEWAY_ACME_DIRECTORY=https://acme-v02.api.letsencrypt.org/directory
GATEWAY_ADMIN_API_TOKEN=generate-a-long-random-string
GATEWAY_MONITORING_TOKEN=generate-another-one
GATEWAY_NTFY_TOPIC=porta-alerts-something-unguessable

With that in place the first reconcile runs immediately at startup: Porta validates app.example.com over HTTP-01, obtains a certificate, writes it under GATEWAY_CERT_STORAGE and starts serving. From then on the renewal loop runs on its own, and the gateway can answer for itself:

curl -sk https://app.example.com:8082/healthz | jq .

§ 03Environment variables#

Bootstrap only. Every variable below is read once at process start; changing one requires a restart. Logging is configured through appsettings.json, not through the environment.

Core#

ACME & DNS#

Listeners#

Admin & monitoring APIs#

Backend health probes#

Alerts#

§ 04The manifest — porta.yaml#

Three independent sections — routes, profiles, tls — each an ordered list of sources. Order is precedence: later entries win. A section you omit simply contributes nothing.

routes:
  - type: file
    path: /etc/porta/routes.yaml
tls:
  - type: file
    path: /etc/porta/tls.yaml

routes:
  - type: file
    path: /etc/porta/routes.yaml          # stable infrastructure routes
  - type: postgres
    connectionEnv: PORTA_PG_CONNECTION    # secret by env-var name, never inline
    query: |
      SELECT fqdn AS match_host,
             'http://app-' || tenant_id || ':8080' AS backend_url,
             true AS preserve_host
      FROM tenants WHERE enabled

profiles:
  - type: file
    path: /etc/porta/profiles.yaml

tls:
  - type: file
    path: /etc/porta/tls.yaml             # ACME account + defaults + private CAs
  - type: postgres
    connectionEnv: PORTA_PG_CONNECTION
    query: SELECT fqdn AS domain, 'http-01' AS challenge FROM tenants WHERE enabled

Source fields#

Merge and precedence rules#

When sources are re-read#

• At startup, before the first request is served, so the gateway never starts with an empty route table.
• On every renewal reconcile — daily at 03:00 UTC, plus once immediately at start.
• On demand, through the admin API: /admin/reload-routes, /admin/reload-tls, /admin/reload-certs.

Editing a YAML file does not by itself apply anything — trigger a reload, or wait for the next reconcile.

§ 05Routing — routes.yaml#

A YAML list of routes. Only match.host and a backend are required; every other field is optional and defaults to sane proxy behaviour.

- match:
    host: app.example.com
    path: /api/                 # optional prefix; longest prefix wins
  backend:
    url: http://127.0.0.1:5001
    protocol: http1             # auto (default) | http1 | http2 | http2-prior-knowledge
  preserve_host: true           # forward the original Host header
  set_x_real_ip: true           # add X-Real-IP with the client IP
  timeout_seconds: 900          # idle timeout toward the backend
  max_body_bytes: 17179869184   # request-body limit; 0 = unlimited
  block_user_agents:            # matching User-Agents get a 404
    - '^(curl|Go ).*$'
  header_profile: hardened      # reusable header set, see § 07
  headers:
    request_set: { X-Forwarded-By: porta }
    request_remove: [Cookie]
    response_set: { Cache-Control: no-store }
    response_remove: [Server]   # nginx `server_tokens off`

Field reference#

* Exactly one of backend.url and backend.static must be present. A route with neither fails the reload.

Matching#

• Host is matched exactly, or as a wildcard (*.example.com).
• Path is an optional prefix. The longest matching prefix wins, so a route on /api/ takes precedence over the same host's catch-all.
• Two routes with the same (host, path) from different sources are not both kept — the later source replaces the earlier one (§ 04).

Backend protocol#

Handled for you#

No configuration needed for any of these: WebSocket upgrades, X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host. TLS termination happens on the public listener; the backend connection is whatever backend.url says.

§ 06Static files#

A route can serve files from a local directory instead of proxying. Replace backend.url with backend.static — the two are mutually exclusive.

- match: { host: files.example.com }
  backend:
    static:
      root: /srv/www/files       # document root
      fallback: not_found        # not_found (default) | index_html (SPA)

- match:                         # nginx: location /tools/ { alias /opt/tools/; }
    host: example.com
    path: /tools
  backend:
    static: { root: /srv/opt/tools }
  headers:
    response_set: { Access-Control-Allow-Origin: "*" }

Static routes match by host and optional path prefix, serve directory index.html, and support conditional requests (ETag / Last-Modified → 304) and range requests. headers.response_set applies; the request-side header transforms do not, since there is no upstream request.

Static routes appear on /monitoring/routes with a synthetic id of the form static:{host}|{path} and a backend of static:{root}. They carry no proxy metrics — request counters and latency stay at zero, because nothing is forwarded.

§ 07Header profiles#

Named, reusable header transform sets. Define a security-header baseline once, point every route at it, and change it in one place.

hardened:
  response_set:
    Strict-Transport-Security: "max-age=63072000; includeSubDomains"
    X-Content-Type-Options: nosniff
    Referrer-Policy: strict-origin-when-cross-origin
  response_remove: [Server, X-Powered-By]

internal-only:
  request_set:
    X-Internal: "1"
  request_remove: [Authorization]

Register the file as a profiles source in the manifest, then reference a profile by name:

- match: { host: app.example.com }
  backend: { url: http://127.0.0.1:5001 }
  header_profile: hardened
  headers:
    response_set: { Cache-Control: no-store }   # merged on top of the profile

Merge semantics#

• The profile is the base; the route's inline headers override it per key. Setting Referrer-Policy inline replaces just that one header, not the whole profile.
• The *_remove lists are unioned, de-duplicated. You cannot un-remove a header the profile removes.
• Profile names are matched exactly, case-sensitively, verbatim as written in the map key.

§ 08TLS & certificates — tls.yaml#

One file describes the ACME account, the server-wide TLS policy, every domain the gateway terminates, and any installation-local certificate authorities.

acme:
  email: ops@example.com        # CA account contact; receives expiry/failure notices
  use_staging: false            # true = Let's Encrypt staging (untrusted, no rate limits)

defaults:
  renewal_threshold_days: 30    # renew this many days before expiry
  min_tls_version: "1.2"        # 1.2 (default, = 1.2+1.3) or 1.3 (1.3 only)
  cipher_suites:                # optional explicit allow-list; Linux/macOS only
    - TLS_AES_128_GCM_SHA256
    - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

private_cas:                    # optional, see § 09
  - id: home
    name: "Example Home CA"
    root_lifetime_days: 3650
    leaf_lifetime_days: 47
    permitted_suffixes:
      - internal

domains:
  - name: app.example.com
    challenge: http-01          # http-01 (port 80) or dns-01 (default)
  - name: "*.example.com"       # wildcards require dns-01
  - name: app.internal
    issuer: private-ca          # no ACME — works fully offline
    ca: home                    # optional when exactly one CA is configured

Field reference#

The protocol floor and cipher list are server-wide, not per domain — they are applied to the public listener during the SNI handshake.

Choosing a challenge#

Under HTTP-01 with GATEWAY_HTTP_REDIRECT_ENABLED=false, Porta opens port 80 only while a validation is in flight. That keeps the port free for something else the rest of the time, at the cost of a brief bind during renewal.

How certificates are grouped#

• Plain ACME domains are bundled into multi-SAN certificates, grouped by registered domain (eTLD+1, resolved against the Public Suffix List).
• Each group is batched at 100 SANs — Let's Encrypt's per-certificate limit. A registered domain with 250 names becomes three certificates, not one failed order.
• Each wildcard gets its own certificate.
• Private-CA hosts get one certificate per host.

The certId you see on /monitoring/certs is derived from the exact SAN set, so the monitoring view can never disagree with what the renewal loop actually issues.

The renewal loop#

A failing renewal never takes the gateway down. The existing certificate keeps serving until it actually expires, the failure count and last error are visible on /monitoring/certs, and the alert fires long before the browser notices.

Only three things start a pass: process start, the daily cron, and an explicit trigger (the admin API or the monitoring trigger). Nothing watches your configuration — editing a TLS source does not apply anything on its own. Trigger a reconcile, or wait for 03:00.

Passes are serialized: a second trigger while one is running waits rather than starting a parallel pass. Two overlapping passes would place duplicate ACME orders for the same SAN set and burn Let's Encrypt's five-duplicate-certificates-per-week budget.

The domain-collapse guard#

A reconcile retires certificates the config no longer asks for. With a database TLS source that is a sharp edge: one row per domain, and zero rows is a valid load, not an error — so a broken WHERE clause, a failed migration or a mass enabled = false would quietly retire the fleet.

So a merged config whose domain count dropped by more than GATEWAY_MAX_TLS_DOMAIN_DROP_PERCENT (default 50) against the last good load is refused. The gateway keeps serving the previous config, the source shows up as stale on /monitoring/config-sources, and nothing is destroyed. The guard needs a baseline from the running process, so a cold start never trips it, and lists shorter than four domains are exempt.

§ 09Private CA — browser-trusted HTTPS for internal hosts#

An installation-local CA gives hosts that have no public domain, no public DNS and no internet access real HTTPS — which means a real Secure Context: service workers, PWA install, Web Push, passkeys. No ACME, no rate limits, works fully offline.

private_cas:
  - id: home                    # used in storage paths and download URLs; [A-Za-z0-9._-]
    name: "Example Home CA"     # shown on devices after installing the root
    root_lifetime_days: 3650    # rotating the root re-onboards every device
    leaf_lifetime_days: 47      # server certs, auto-rotated; clamped to 825
    permitted_suffixes:
      - internal                # .internal is the ICANN-reserved private-use TLD

domains:
  - name: app.internal
    issuer: private-ca
    ca: home

Renewal for private-CA leafs uses the same loop as ACME, with one adjustment: the effective threshold is capped at half the leaf lifetime. With the default 47-day leafs and a 30-day global threshold, the effective threshold becomes 23 days — otherwise every reconcile would re-issue.

Device onboarding endpoints#

The root certificate — never the key — is served unauthenticated, because a fresh device has no trust yet and could not authenticate anyway. Integrity is verified out of band, by comparing the SHA-256 fingerprint from /monitoring/private-cas.

These are mounted on the public HTTPS listener and — when GATEWAY_HTTP_REDIRECT_ENABLED is on — on cleartext port 80 as well, so a device that does not trust the CA yet can fetch the root without walking through a certificate interstitial. An unknown or malformed {id} answers 404.

# fetch and verify before installing
curl -o root.pem http://app.internal/.porta/ca/home/root.pem
openssl x509 -in root.pem -noout -fingerprint -sha256

# compare against the gateway's own view
curl -s -H "Authorization: Bearer $TOKEN" \
  https://app.internal:8082/monitoring/private-cas | jq -r '.[].fingerprintSha256'

On iOS the profile still has to be trusted manually under Settings → General → About → Certificate Trust Settings after installation — that toggle is Apple's, and no profile can set it for you.

§ 10Postgres as a config source#

The Postgres source does not require dedicated tables. It runs your query verbatim and reads the result columns by name, case-insensitively — so you write a SELECT that aliases your existing schema onto the expected names. Joins, CTEs and WHERE are all fine.

Routing query columns#

Static-file routes are not expressible from a database source — backend_url is required. Keep static routes in the file base.

SELECT
    fqdn                                   AS match_host,
    'http://127.0.0.1:' || port            AS backend_url,
    'http1'                                AS backend_protocol,
    true                                   AS preserve_host,
    true                                   AS set_x_real_ip,
    900                                    AS timeout_seconds,
    CASE WHEN big_uploads THEN 17179869184 END          AS max_body_bytes,
    CASE WHEN fqdn = 'registry.example.com'
         THEN jsonb_build_array('^(docker/1\.|Go ).*$') END   AS block_user_agents,
    jsonb_build_array('Server')            AS headers_response_remove
FROM sites
WHERE enabled

TLS query columns#

A domains-only source: one row per domain. The ACME account, the defaults block and any private CAs always come from the file base — a database source never supplies them. Zero rows is valid and simply contributes nothing.

SELECT fqdn AS domain, 'http-01' AS challenge
FROM sites
WHERE tls_enabled

Header-profile query columns#

Fully relational — one row per header directive, no JSON needed. Rows are grouped by name.

SELECT profile AS name, kind AS type, header_name AS header, header_value AS value
FROM header_rules

routes:
  - type: file
    path: /etc/porta/routes.yaml
  - type: postgres
    connectionEnv: PORTA_PG_CONNECTION
    query: "SELECT fqdn AS match_host, 'http://127.0.0.1:'||port AS backend_url FROM sites WHERE enabled"
tls:
  - type: file
    path: /etc/porta/tls.yaml
  - type: postgres
    connectionEnv: PORTA_PG_CONNECTION
    query: "SELECT fqdn AS domain, 'http-01' AS challenge FROM sites WHERE tls_enabled"

With PORTA_PG_CONNECTION in the environment, e.g. Host=db;Port=5432;Database=porta;Username=porta;Password=secret. Give that user SELECT and nothing else — Porta never writes to your database.

§ 11SproutDB as a config source#

Same idea as Postgres, over REST. Porta posts the query text to POST {connection}/sproutdb/query with the database and API key as headers, and reads the returned rows by column name.

POST https://sprout.example.com/sproutdb/query
X-SproutDB-Database: porta
X-SproutDB-ApiKey: {masterKeyEnv value}
Content-Type: text/plain

<your query text>

SproutDB has no JSON column type, so the map- and list-valued columns are stored as JSON strings and carry a _json suffix. Everything else matches the Postgres column names.

Routing columns#

TLS and profile columns#

Identical to Postgres: TLS is one row per domain with domain and optional challenge; header profiles are one row per directive with name, type, header, value.

routes:
  - type: file
    path: /etc/porta/routes.yaml
  - type: sproutdb
    connection: https://sprout.example.com
    database: porta
    masterKeyEnv: PORTA_SPROUT_KEY
    query: "from sites where enabled = true select fqdn as match_host, backend as backend_url"

§ 12Querying Porta — the monitoring API#

A read-only HTTP API on the monitoring port. Nothing here mutates state, so it is safe to poll from a dashboard, a uptime checker, or your own tooling. The Porta Monitor desktop client is simply one consumer of these same endpoints.

Connecting#

• Base URL: https://{host}:8082 — TLS, using the same SNI certificates as the public listener. Connect with a hostname the gateway holds a certificate for; an IP address will not match.
• Auth: Authorization: Bearer {GATEWAY_MONITORING_TOKEN}, compared in constant time. Clients that cannot set headers may pass ?access_token=… instead.
• Exception: /healthz needs no token, so an external uptime monitor can poll it directly.
• CORS: any origin is allowed, with the preflight answered before the token check — every endpoint except /healthz is token-gated regardless, so a browser client from another origin works out of the box.
• Off switch: with GATEWAY_MONITORING_TOKEN empty the listener is never bound at all. No token, no port.

export PORTA=https://gw.example.com:8082
export TOKEN=your-monitoring-token

curl -s -H "Authorization: Bearer $TOKEN" $PORTA/monitoring/status | jq .

Three states, deliberately mapped onto two status codes.

degraded answers 200 on purpose: it is not an outage, and paging someone at 3 a.m. for a stale config source trains people to ignore the pager. The reason is always named in checks.

{
  "status": "degraded",
  "checks": {
    "cert_cache": "ok",
    "renewal_scheduler": "ok",
    "sqlite": "ok",
    "config_sources": "stale"
  }
}

The cheapest call. Poll this; fetch detail only when something changes.

{
  "status": "running",
  "now": "2026-08-23T09:14:02.115+00:00",
  "startedAt": "2026-08-19T22:03:44.901+00:00",
  "certCount": 12,
  "routeCount": 27,
  "configStale": false
}

configStale is the summary flag for "the running config no longer matches the configured one". When it is true, /monitoring/config-sources tells you which source and why.

lastReconcile answers the question nothing else can: did the renewal loop run, and did it get anywhere. It is published even when the pass threw or was cancelled — an aborted cycle that leaves no trace is precisely how a missing certificate stays invisible.

{
  "status": "running",
  "certCount": 12,
  "routeCount": 27,
  "configStale": false,
  "reconcileInProgress": false,
  "lastReconcile": {
    "startedAt": "2026-08-23T03:00:04.118+00:00",
    "completedAt": "2026-08-23T03:02:41.006+00:00",
    "trigger": "cron",
    "outcome": "partial",
    "certsIssued": 2,
    "certsUpToDate": 38,
    "certsFailed": 1,
    "certsSkippedBackoff": 0,
    "error": "new.example.com: order failed: DNS problem"
  }
}

Every certificate group Porta is responsible for — configured ones (even before they are issued) and orphans still on disk.

{
  "certs": [
    {
      "certId": "a3f1c8…",
      "status": "active",
      "domains": [
        {
          "name": "app.example.com",
          "challenge": "http-01",
          "dns": {
            "a": ["203.0.113.10"],
            "aaaa": [],
            "cname": null,
            "pointsAtGateway": "yes",
            "checkedAt": "2026-08-23T09:09:41.002+00:00",
            "error": null
          }
        }
      ],
      "notBefore": "2026-08-01T00:00:00+00:00",
      "notAfter": "2026-10-30T00:00:00+00:00",
      "issuedAt": "2026-08-01T03:00:12.441+00:00",
      "nextRenewalAttempt": null,
      "lastAttempt": "2026-08-23T03:00:07.118+00:00",
      "consecutiveFailures": 0,
      "lastError": null,
      "history": [
        { "timestamp": "2026-08-01T03:00:12.441+00:00",
          "eventName": "cert_issued", "severity": "info", "detailsJson": "{…}" }
      ]
    }
  ],
  "gatewayIp": { "ipv4": "203.0.113.10", "ipv6": null, "checkedAt": "2026-08-23T09:09:40.500+00:00" },
  "configError": null
}

Every route in the running table, with counters accumulated since process start.

[
  {
    "routeId": "b71e0d…",
    "host": "app.example.com",
    "pathPrefix": null,
    "backendUrl": "http://127.0.0.1:5001",
    "requestsTotal": 184223,
    "requestsFailed": 91,
    "bytesIn": 40113882,
    "bytesOut": 991244102,
    "latency": { "p50": 4.1, "p90": 11.8, "p99": 52.3, "sampleCount": 4096 },
    "backendHealth": "healthy",
    "backendHealthSince": "2026-08-19T22:04:02.771+00:00"
  }
]

Latency is in milliseconds, computed over a rolling sample window. Static routes appear with a static: route id and zeroed counters — nothing is forwarded, so there is nothing to count. backendHealth is null when active probing is disabled.

The id is a query parameter rather than a path segment because synthetic static-route ids contain | and :. An unknown id answers 404.

{
  "routeId": "b71e0d…",
  "host": "app.example.com",
  "pathPrefix": null,
  "backendUrl": "http://127.0.0.1:5001",
  "requestsTotal": 184223,
  "requestsFailed": 91,
  "bytesIn": 40113882,
  "bytesOut": 991244102,
  "latency": { "p50": 4.1, "p90": 11.8, "p99": 52.3, "sampleCount": 4096 },
  "backendHealth": "healthy",
  "backendHealthSince": "2026-08-19T22:04:02.771+00:00",
  "statusCodes": [ { "code": 200, "count": 183900 }, { "code": 502, "count": 91 } ],
  "buckets":     [ { "minuteUtc": "2026-08-23T09:13:00+00:00", "total": 214, "failed": 0 } ],
  "recentErrors": [
    { "timestamp": "2026-08-23T08:41:19.204+00:00", "method": "POST", "path": "/api/import",
      "statusCode": 502, "forwarderError": "RequestTimedOut",
      "exceptionType": "TaskCanceledException", "exceptionMessage": "…" }
  ]
}

buckets is a per-minute rolling window — enough to draw a sparkline without keeping a time-series database around.

limit defaults to 50. Newest first.

[
  { "id": 412, "timestamp": "2026-08-23T09:02:07.118+00:00",
    "what": "tls", "trigger": "admin_api", "success": true, "errorMessage": null },
  { "id": 411, "timestamp": "2026-08-22T14:22:51.900+00:00",
    "what": "routes", "trigger": "admin_api", "success": false,
    "errorMessage": "Route 'app.example.com' has neither a backend nor a static root." }
]

what is routes, tls or certs; trigger records who asked. diffSummary carries the tally of the pass. This history covers explicitly triggered reloads — the scheduled daily reconcile publishes its result on /monitoring/status instead. It is the first place to look after an edit that "did not take".

Two things worth knowing: a reload that was cancelled (client disconnect, shutdown) is recorded here as a failure rather than vanishing, and success is false when a TLS pass ran to the end but some cert group failed — a green row never implies "the change landed" on its own.

The persisted audit log, newest first. limit defaults to 100; category and severity are optional exact-match filters.

[
  { "id": 9182, "timestamp": "2026-08-23T03:00:12.441+00:00",
    "category": "acme", "severity": "info", "eventName": "cert_issued",
    "domain": "app.example.com,api.example.com", "detailsJson": "{\"sans\":2}" }
]

{ "accountUrl": "https://acme-v02.api.letsencrypt.org/acme/acct/1234567", "isRegistered": true }

isRegistered: false on a deployment that has ACME domains means no order has been placed yet — expected before the first reconcile, worth investigating afterwards.

The list device onboarding is verified against. Note what is not here: the key.

[
  {
    "id": "home",
    "name": "Example Home CA",
    "fingerprintSha256": "9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08",
    "notBefore": "2026-02-11T18:22:03+00:00",
    "notAfter":  "2036-02-09T18:22:03+00:00",
    "createdAt": "2026-02-11T18:22:04.118+00:00",
    "permittedSuffixes": ["internal"]
  }
]

One entry per manifest source, identified by section and position. This is the endpoint that turns a silent last-known-good fallback into something you can see.

[
  { "kind": "routes", "index": 0, "state": "ok",
    "error": null, "failingSince": null, "lastSuccessAt": "2026-08-23T03:00:05.221+00:00" },
  { "kind": "routes", "index": 1, "state": "stale",
    "error": "Connection refused (db:5432)",
    "failingSince": "2026-08-22T19:41:03.775+00:00",
    "lastSuccessAt": "2026-08-22T19:11:02.400+00:00" }
]

A source only appears once it has been attempted at least once.

Starts a certificate reconcile immediately instead of waiting for 03:00. This is what a "renew now" button in a monitoring client calls — it lives on the monitoring listener, so the admin port stays local and uninvolved.

Authenticated with GATEWAY_MONITORING_WRITE_TOKEN, not the read token. Body is optional:

curl -sk -X POST "$PORTA/monitoring/reconcile" \
  -H "Authorization: Bearer $WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

{ "started": true, "trigger": "monitoring_api", "force": true, "certId": null }

It answers 202 and runs the pass in the background. That is deliberate: a reconcile legitimately takes minutes, and a synchronous trigger would recreate the failure mode it exists to fix — a client timeout killing the work halfway through, leaving a started-but-never-finished certificate and no error anywhere. Poll /monitoring/status for progress.

If a pass is already running you get 202 with started: false and the current lastReconcile — not an error, because a reconcile is what you asked for and one is happening.

The background work runs on the process lifetime token, so it survives the response but not a shutdown.

Polling patterns#

• Uptime monitor: /healthz every 30–60 s, no token. Alert on 503; surface degraded without paging.
• Dashboard: /monitoring/status on a short interval, and fetch the heavier endpoints only when certCount, routeCount or configStale changes.
• Certificate watch: /monitoring/certs a few times a day is plenty — the renewal loop runs daily. Alert on any status of failed or expiring, or any consecutiveFailures > 0.
• Config drift: alert on configStale: true persisting past one reconcile cycle.

The DNS snapshot behind /monitoring/certs is cached, so polling it harder does not resolve harder — it just returns the same snapshot.

§ 13The admin API#

Three mutating endpoints, all of them idempotent triggers: re-read configuration now instead of waiting for the next reconcile. Everything is bearer-authenticated and fail-closed — with no GATEWAY_ADMIN_API_TOKEN set, every call answers 401.

Re-reads every routing source and rebuilds the proxy table. Answers {"reloaded":"routes"}, or 500 with the error detail if a source is invalid.

Re-reads the TLS configuration and runs a full reconcile: issue what is missing, renew what is due, retire what is no longer configured. This is the call to make after adding a domain.

Reloads the certificate cache from storage without contacting any CA. Use it after replacing certificate files on disk out of band.

curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" http://127.0.0.1:8081/admin/reload-tls

Every call is recorded in the reload history with trigger: "admin_api", success or failure — so /monitoring/reload-history is the audit trail for anything anyone triggered by hand.

§ 14Status vocabulary#

Every status string Porta can hand back, in one place, with what you should do about it.

Certificate status#

Config source state#

DNS verdict#

§ 15Recipes#

The tasks that actually come up, end to end.

Coming from nginx#

WebSocket upgrade blocks and the whole X-Forwarded-* dance have no equivalent because they need no configuration.

Add a domain#

# 1. routes.yaml
- match: { host: new.example.com }
  backend: { url: http://127.0.0.1:5005 }
  preserve_host: true

# 2. tls.yaml
domains:
  - name: new.example.com
    challenge: http-01

# 3. apply now instead of waiting for 03:00 UTC — either the local admin API…
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" http://127.0.0.1:8081/admin/reload-tls
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" http://127.0.0.1:8081/admin/reload-routes

#    …or, from a monitoring client over the network:
curl -sk -X POST -H "Authorization: Bearer $WRITE_TOKEN" $PORTA/monitoring/reconcile

# 4. confirm
curl -s -H "Authorization: Bearer $TOKEN" $PORTA/monitoring/certs \
  | jq '.certs[] | select(.domains[].name == "new.example.com") | {status, notAfter, lastError}'

Point DNS at the gateway before reloading if you use HTTP-01 — the challenge needs the name to resolve to this host. pointsAtGateway on /monitoring/certs tells you whether it does.

A wildcard certificate#

# tls.yaml — wildcards require dns-01, which is the default
domains:
  - name: "*.example.com"
  - name: example.com          # the apex is not covered by the wildcard

Set GATEWAY_IONOS_API_KEY and make sure the zone is hosted at a supported provider. The wildcard gets its own certificate; the apex joins the multi-SAN group.

An internal host with real HTTPS#

# tls.yaml
private_cas:
  - id: home
    name: "Acme Home CA"
    permitted_suffixes: [internal]

domains:
  - name: nas.internal
    issuer: private-ca

# routes.yaml
- match: { host: nas.internal }
  backend: { url: http://192.168.1.20:5000 }
  preserve_host: true

Then install the root once per device from /.porta/ca/home/root.crt (or .mobileconfig on iOS), after checking the fingerprint against /monitoring/private-cas. No internet, no public DNS, no ACME involved — and the browser treats https://nas.internal as a Secure Context.

Host an SPA and its API on one host#

- match: { host: app.example.com, path: /api }
  backend: { url: http://127.0.0.1:5001 }
  preserve_host: true

- match: { host: app.example.com }
  backend:
    static:
      root: /srv/www/app
      fallback: index_html      # client-side routing

Longest prefix wins, so /api/* proxies and everything else falls through to the static root — as long as /srv/www/app is a path the gateway process can actually read.

Large uploads, slow backends#

- match: { host: registry.example.com }
  backend: { url: http://127.0.0.1:5000 }
  preserve_host: true
  max_body_bytes: 0            # unlimited
  timeout_seconds: 3600

max_body_bytes: 0 removes the limit entirely; omitting the field leaves Kestrel's ~28 MiB default in place. timeout_seconds is an idle timeout, not a total request budget.

Multi-tenant, database driven#

Keep the infrastructure routes in YAML and let the tenant table drive the rest. Adding a customer becomes an INSERT plus one reload call — no file edits, no redeploy.

routes:
  - type: file
    path: /etc/porta/routes.yaml
  - type: postgres
    connectionEnv: PORTA_PG_CONNECTION
    query: |
      SELECT fqdn AS match_host,
             'http://tenant-' || id || ':8080' AS backend_url,
             true AS preserve_host,
             'hardened' AS header_profile
      FROM tenants WHERE enabled
tls:
  - type: file
    path: /etc/porta/tls.yaml
  - type: postgres
    connectionEnv: PORTA_PG_CONNECTION
    query: "SELECT fqdn AS domain, 'http-01' AS challenge FROM tenants WHERE enabled"

Certificates for the new names are batched into the existing multi-SAN groups automatically, 100 SANs per certificate.

Test without burning rate limits#

acme:
  email: ops@example.com
  use_staging: true

Or point GATEWAY_ACME_DIRECTORY at the staging directory. Certificates are issued by an untrusted root, so browsers complain — which is exactly what you want while rehearsing a cutover. Switch back and reload TLS to get real certificates.

Cutting over from an existing proxy#

1. Run Porta on spare ports with the real config and use_staging: true. Verify routing with curl --resolve.
2. Switch to production ACME, keep the old proxy on 80/443 for now, and pre-issue over DNS-01 if you can — that needs no port at all.
3. Stop the old proxy, move Porta to 80/443, start. If you must use HTTP-01, this is the point where port 80 has to be free.
4. Watch /healthz and /monitoring/certs; roll back by restarting the old proxy if anything is wrong.

§ 16Troubleshooting#

Symptom first, then the endpoint that answers it.

A 30-second triage#

curl -sk $PORTA/healthz | jq .
curl -s -H "Authorization: Bearer $TOKEN" $PORTA/monitoring/status | jq .
curl -s -H "Authorization: Bearer $TOKEN" $PORTA/monitoring/config-sources | jq '.[] | select(.state != "ok")'
curl -s -H "Authorization: Bearer $TOKEN" $PORTA/monitoring/certs \
  | jq '.certs[] | select(.status != "active") | {certId, status, lastError}'
curl -s -H "Authorization: Bearer $TOKEN" "$PORTA/monitoring/audit?limit=20&severity=error" | jq .

Those five calls cover essentially every operational question the gateway can answer about itself.