How invaliduser231/portlyn works
1. Top-level shape
Portlyn is a two-tier control-plane plus data-plane system: a Go backend that serves both the admin API and reverse-proxy traffic, and a separate Next.js frontend for administration. In the default deployment, both sit behind a Docker Compose stack with PostgreSQL, Loki, Grafana Alloy, and Grafana.
2. Runtime entrypoints
The Go side is split into multiple binaries under cmd/: server is the main API/proxy process, nodeagent is a separate agent-oriented executable, and configcheck validates runtime configuration before startup. This separation is important because the main server owns control-plane state while agent behavior is isolated.
3. Backend core responsibilities
The internal/ tree shows the backend is not just an API; it combines authentication, proxying, routing, certificate automation, audit logging, rate limiting, health/metrics, and persistence. The backend is the central orchestrator that reads and writes the application’s state and then propagates configuration to the proxy runtime.
4. Persistence boundary
State is stored through internal/store/, which contains dedicated stores for users, sessions, groups, services, domains, certificates, DNS providers, node enrollment, routing, audit records, and app settings. The README confirms PostgreSQL is the default database, with SQLite also supported, and the deployment can point to an external Postgres instance via DATABASE_URL.
5. Authentication and session flow
Authentication is handled server-side in internal/auth/ and internal/http/auth.go, with local login, OIDC/SSO, MFA, session cookies, and recovery codes. The UI uses auth-specific routes for login, OIDC callback, forbidden, and route-login flows, while the backend enforces access through middleware and route-access logic.
6. Authorization model
Access control is resource-centric: services can be public, authenticated, or restricted, and restricted access is composed from users, groups, service groups, and route policies. The frontend mirrors this model with pages for services, groups, service groups, users, and access-policy fields, indicating the UI is largely a management surface over backend authorization objects.
7. Reverse-proxy and routing path
The proxy subsystem under internal/proxy/ is the runtime data-plane. It uses cached/config-bus state to serve incoming traffic, with routing definitions managed in internal/routing/ and persisted in the store. In other words, the backend computes route state from DB objects, then the proxy layer consumes that state to forward requests to upstream services.
8. Certificate and DNS automation
ACME handling is a distinct subsystem under internal/acme/ and internal/http/certificate_ops.go/certificates_dns.go. It manages certificate issuance, renewal, retries, and status synchronization, including http-01 and dns-01 flows and wildcard support through DNS providers. DNS provider credentials are stored encrypted and are never returned in cleartext, which is a clear security boundary around certificate automation.
9. Node and heartbeat boundary
Node enrollment and heartbeat management are first-class features in internal/http/node_enrollment.go, internal/http/node_security.go, and internal/store/node_*. The README indicates heartbeat tokens are stored hashed server-side and can optionally be pinned to client certificate fingerprints, so nodes are treated as trusted-but-managed agents rather than anonymous clients.
10. Security and data protection
Security-sensitive concerns are centralized in internal/secureconfig/, internal/http/security*.go, and internal/auth/. The system uses encrypted secrets, CSRF protection, security headers, strict request parsing, admin MFA enforcement, and separate secrets for JWT/session/OIDC/CSRF/MFA/data encryption. This means the architecture assumes browser traffic, admin actions, and node traffic all need different trust controls.
11. Observability and audit
Observability is split into operational telemetry and compliance-style audit logs. internal/observability/metrics.go and HTTP health endpoints provide liveness/readiness/health plus Prometheus-style metrics, while internal/audit/ captures auth, proxy, and admin events. On the stack side, Loki receives logs via Alloy, and Grafana ships with provisioning and a dashboard for Portlyn-specific operational views.
12. Frontend integration
The frontend/ app is a Next.js admin console that talks to the backend API and mirrors backend resource boundaries: domains, certificates, services, nodes, users, groups, service groups, DNS providers, audit logs, settings, and system status. It is not a separate business layer; it is a management interface over the backend’s control plane.
13. Operational packaging
The repository is optimized for containerized Linux deployment. docker-compose.yml, the root Dockerfile, frontend/Dockerfile, deploy/ provisioning files, and deploy.sh define the deployment boundary, while docs cover backup/restore, HA, secret rotation, and production hardening. For an architecture diagram, the main external dependencies to show are PostgreSQL, Loki, Grafana Alloy, and Grafana, with the frontend and backend as the two primary application services.
Main entry points: main.go Server · docker-compose.yml Compose stack · page.tsx Admin UI · db.go Stores
Components 23
Backend
Go control-plane, proxy runtime, and shared backend subsystems.
- Server · Main control-plane process serving admin API and reverse-proxy traffic.
cmd/server/main.go - Node agent · Separate executable for managed node behavior.
cmd/nodeagent/main.go - Config check · Pre-start configuration validation binary.
cmd/configcheck/main.go - HTTP layer · Admin API, auth, security, health, and resource handlers.
internal/http/server.go - Auth · Login, OIDC, MFA, sessions, route access, and auth middleware.
internal/auth/service.go - Proxy · Reverse-proxy runtime consuming cached routing state.
internal/proxy/manager.go - Routing · Routing types and policies that define request dispatch.
internal/routing/types.go - ACME · Certificate issuance, renewal, and DNS/http validation workflows.
internal/acme/manager.go - Audit · Compliance-style logging for auth, proxy, and admin events.
internal/audit/logger.go - Metrics · Operational metrics and health reporting.
internal/observability/metrics.go - Secrets · Encrypted secrets and secure configuration handling.
internal/secureconfig/secrets.go
Frontend
Next.js administration console.
- Admin UI · Browser-based administration console mirroring backend resources.
frontend/app/page.tsx - Auth pages · Login, OIDC callback, route login, and forbidden screens.
frontend/app/(auth)/login/page.tsx - Dashboard · Authenticated management surface for resources and system status.
frontend/app/(dashboard)/layout.tsx - Resource pages · Pages for users, groups, services, domains, certificates, DNS providers, nodes, and audit logs.
frontend/app/(dashboard)/services/page.tsx
Deployment
Container, compose, and observability packaging.
- Compose stack · Default deployment stack wiring backend, frontend, database, and observability services.
docker-compose.yml - Backend image · Container build definition for the Go application.
Dockerfile - Frontend image · Container build definition for the Next.js app.
frontend/Dockerfile - Alloy · Grafana Alloy configuration for log shipping.
deploy/alloy/config.alloy - Loki · Log aggregation backend configuration.
deploy/loki/config.yml - Grafana · Provisioned dashboards and datasources for operational visibility.
deploy/grafana/provisioning/dashboards/portlyn.yml
Connections 29
- Server → HTTP layer: serves · Main server exposes the HTTP/admin surface.
- Server → Proxy: hosts · Main server also runs the reverse-proxy data plane.
- Server → Auth: uses · HTTP handlers delegate authentication and session logic.
- Server → ACME: orchestrates · Server coordinates certificate issuance and renewal.
- Server → Audit: emits · Administrative and security events are audited.
- Server → Metrics: exports · Health and metrics are exposed from the backend.
- HTTP layer → Stores: reads/writes · Handlers persist and load application state through stores.
- HTTP layer → Secrets: protects · Sensitive request and secret handling uses secure config primitives.
- Auth → Stores: persists · Users, sessions, MFA, and OIDC state are stored.
- Auth → Secrets: encrypts · Auth-related secrets and tokens rely on secure secret storage.
- Proxy → Routing: consumes · Proxy runtime forwards traffic according to routing definitions.
- Proxy → Stores: syncs · Proxy state is populated from persisted configuration.
- Routing → Stores: persists · Route definitions and policy objects are stored in the database.
- ACME → Stores: reads/writes · Certificate and DNS provider state is persisted.
- ACME → Secrets: encrypts · DNS provider credentials and other secrets stay protected.
- Node agent → Server: enrolls with · Managed nodes register and heartbeat through the backend.
- Admin UI → HTTP layer: calls API · Admin UI talks to backend endpoints.
- Admin UI → Auth pages: routes · Authentication-specific pages handle login and callback flows.
- Admin UI → Dashboard: shell · Dashboard layout wraps authenticated administration pages.
- Admin UI → Resource pages: manages · Resource CRUD screens mirror backend control-plane objects.
- Compose stack → Server: deploys · Compose stack runs the Go backend service.
- Compose stack → Admin UI: deploys · Compose stack runs the admin UI.
- Compose stack → Database: includes · Primary database service is part of the default deployment.
- Compose stack → Alloy: includes · Log shipping is provided via Alloy.
- Compose stack → Loki: includes · Logs are stored in Loki.
- Compose stack → Grafana: includes · Operational dashboards are provided by Grafana.
- Backend image → Server: builds · Backend container image is built from the Go sources.
- Frontend image → Admin UI: builds · Frontend container image is built from the Next.js sources.
- Stores → Database: uses · Store layer abstracts PostgreSQL and SQLite persistence.