VPS Tutorials
Self-host Authentik: OIDC, MFA, Caddy HTTPS and tested recovery
Deploy Authentik with Docker Compose and PostgreSQL, secure its private ports with Caddy HTTPS, integrate OIDC and Forward Auth, configure MFA, and preserve secrets and data for safe upgrades and tested recovery.

As a collection of self-hosted applications grows, account administration often becomes harder before the VPS runs out of CPU or disk space. Grafana, Gitea and Nextcloud each have passwords to manage; departures require removing access in several places; older applications may have no OIDC integration. Authentik provides a common identity service using OIDC, SAML or LDAP, and can place authentication in front of legacy websites through a Proxy Provider.
This guide uses Ubuntu 24.04, Docker Compose, PostgreSQL 16 and Caddy. The original September 15, 2026 example used Authentik 2026.8.2; the official release checked on November 16 is 2026.8.5, whose Compose definition still uses PostgreSQL 16 and server/worker services. Read the release notes before installing: the download URL follows the current release, so downloading it later does not reproduce an older deployment automatically.
Authentik suits individuals and small teams running several applications that need common sign-in, MFA and access policies:
- It supports OpenID Connect/OAuth 2.0, SAML, LDAP, SCIM and other integration protocols; check edition requirements for the specific feature.
- Visual Flows define sign-in, registration, password recovery and MFA.
- For applications with native OIDC, Authentik acts as the identity provider.
- Proxy Providers and Outposts protect applications without native single sign-on.
- Users, groups, attributes and policies determine access to each application.
- Disabling a user prevents subsequent authorized sign-ins through the connected provider.
Disabling the account does not necessarily invalidate an application's existing session or an already issued access token. Test logout, token lifetime and session revocation for each integration as part of offboarding.
Authentik is not a password vault for your personal website passwords. For a separate team vault, see self-hosting Vaultwarden.
| Option | Strength | Maintenance cost | Best fit |
|---|---|---|---|
| Authentik | Accessible administration, identity protocols and flexible proxy Flows | Understanding server, worker, PostgreSQL and Outposts | A mix of OIDC applications and legacy websites |
| Keycloak | Established OIDC/SAML ecosystem, realms, roles and enterprise directories | More configuration and resource planning | Complex organizational identity and role models |
| Authelia | Relatively lightweight authentication for reverse-proxied websites | Narrower identity-platform and application-directory scope | A few internal sites primarily using Forward Auth |
| Basic Auth | Quick configuration | No shared account lifecycle, MFA or granular audit | Temporary pages with very few users and limited exposure |
For enterprise directories or extensive realm and role modeling, read the Keycloak deployment guide. Authentik is often a convenient starting point when several Docker applications need a common login.
The single-node arrangement is browser or OIDC client → Caddy HTTPS → Authentik server/worker → PostgreSQL over the private Docker network:
浏览器 / OIDC 应用
|
| HTTPS :443
v
Caddy
|
| HTTP 127.0.0.1:9000
v
Authentik server + worker
|
| Docker 内部网络 :5432
v
PostgreSQL 16
The official Compose method is intended for testing and small production deployments, with a minimum of 2 CPU cores and 2GB RAM. That minimum is not a comfortable production budget when PostgreSQL, Caddy, workers and backups share the host.
| Workload | Suggested VPS | Practical limitation |
|---|---|---|
| Testing, fewer than 10 users | 2 vCPU, 2GB RAM, 25GB SSD | Functional testing rather than a critical login service |
| Small team, tens to hundreds of users | 2–4 vCPU, 4GB RAM, 40GB NVMe | Leave capacity for database growth and upgrades |
| Login peaks or many applications | 4 vCPU, at least 8GB RAM | Load-test before moving the database or adding nodes |
These are planning estimates, not measured capacity guarantees. A single VPS remains a single point of failure. Prepare off-host backups, application-level emergency access where supported, an emergency identity administrator and a tested recovery procedure.
Use a dedicated hostname such as sso.example.com. Point its A record at the VPS public IPv4 address; add AAAA only when IPv6 is actually configured and reachable.
Allow SSH, HTTP and HTTPS:
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose
Do not open 9000, 9443 or 5432 in the cloud security group or UFW. The web ports bind to 127.0.0.1, and PostgreSQL has no host port mapping. Docker-published ports require their own exposure checks; a UFW rule alone is not proof of isolation. If enabling the firewall breaks SSH, use the provider console and the UFW lockout recovery guide.
Install Docker Engine and the Compose v2 plugin using the official Ubuntu instructions before the commands below. Installing Caddy and checking Docker's version does not install Docker. Review package upgrades and schedule any reboot before making this the team's login endpoint.
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl openssl caddy
docker --version
docker compose version
sudo systemctl enable --now caddy
Use Compose v2. Also configure log rotation, monitoring and recovery exercises using the Compose production checklist.
Create a deployment directory and restrict newly created files:
sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik
umask 077
curl -fsSLo compose.yml https://docs.goauthentik.io/compose.yml
The official download pins the version current at download time. Keep an auditable version rather than changing the image tag to latest. If the documentation download is unavailable, obtain the Compose file from the same official release and review it; do not substitute an unverified third-party installer.
Generate the database password and identity secret, and bind both web ports to loopback:
{
printf 'PG_PASS=%s\n' "$(openssl rand -hex 32)"
printf 'AUTHENTIK_SECRET_KEY=%s\n' "$(openssl rand -hex 60)"
printf 'COMPOSE_PORT_HTTP=127.0.0.1:9000\n'
printf 'COMPOSE_PORT_HTTPS=127.0.0.1:9443\n'
} > .env
chmod 600 .env
docker compose config --quiet
This command is for a fresh installation: it overwrites the environment file. Never regenerate these secrets on an existing instance. Keep .env out of Git, chat and support tickets. The full output of docker compose config expands secrets; use --quiet for syntax validation.
The default worker mounts /var/run/docker.sock to manage Outposts. Access to the Docker socket can confer control of the host. Remove the mount if managing Outposts manually, or evaluate a Docker Socket Proxy with only required operations and access restricted to the worker.
Do not mount /etc/timezone or /etc/localtime into these containers. Authentik's internal operations use UTC; host timezone mounts can disrupt OAuth, SAML and certificate-time checks. Keep the VPS clock synchronized independently.
Pull the pinned images and start the services:
cd /opt/authentik
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 server worker postgresql
Inspect the host bindings:
ss -lnt | grep -E ':9000|:9443'
curl -fsSI http://127.0.0.1:9000/
The ss output should show 127.0.0.1:9000 and 127.0.0.1:9443, never 0.0.0.0 or [::]. Verify exposure from outside the VPS as well. If a service keeps restarting, inspect database health and server/worker logs; increasing restart behavior does not fix the underlying failure.
Edit /etc/caddy/Caddyfile, replacing the example hostname:
sso.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:9000
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
Referrer-Policy "strict-origin-when-cross-origin"
}
}
Validate and reload:
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsSI https://sso.example.com/
The proxy must support HTTP/1.1 and WebSockets, preserve Host, and correctly handle X-Forwarded-Host, X-Forwarded-Proto, X-Forwarded-For, Connection and Upgrade. Caddy's reverse_proxy handles ordinary forwarding and WebSockets. Do not permit users to bypass it through port 9000.
For an existing Nginx Proxy Manager installation, use the HTTPS and reverse proxy guide and enable WebSockets. Endless loading, CSRF errors, HTTP callbacks or incorrect client IPs often indicate forwarding-header or trusted-proxy problems. Authentik's default trust covers loopback, private RFC1918 and link-local sources; never trust the entire public internet to make an error disappear. Enable HSTS subdomain coverage only when every affected subdomain is ready for HTTPS.
Open https://sso.example.com; for a fresh installation, use the official initial setup flow at /if/flow/initial-setup/ and set a strong password for akadmin.
- Create named administrators instead of sharing
akadminfor daily work. - Enable TOTP or WebAuthn/passkeys for administrators and preserve recovery methods.
- Define appropriate administrator and user login Flows and password policies.
- Keep an emergency administrator's credentials offline; test it periodically.
- Configure branding, email and password recovery, then actually test recovery delivery.
- Maintain a list of dependent applications to assess an identity-service outage.
Before enforcing MFA broadly, test a separate administrator and an incognito login. Recovery codes, backup copies and emergency access matter more than cosmetic login customization.
Prefer native OIDC/OAuth 2.0 over an additional proxy login when the application supports it:
- Create an OAuth2/OpenID Provider in Authentik.
- For a server-side application, choose a confidential client and generate its Client ID and Client Secret. Browser-only clients need their documented public-client/PKCE flow instead.
- Add the application's exact Redirect URI, including scheme, hostname, path and trailing slash.
- Create an Application linked to that Provider.
- Enter the Discovery URL shown by the Provider, Client ID and Client Secret in the application's server-side configuration.
- Test login, logout, email and group mapping with a test group before allowing everyone.
Include openid; applications often also request profile and email. Use the Provider's OpenID Configuration/Discovery address rather than guessing authorization and token endpoints. Never expose a confidential Client Secret in browser code.
For redirect_uri_mismatch, compare the actual callback character by character. An unexpected http:// callback behind HTTPS usually requires fixing proxy headers and external URL detection, rather than allowing the insecure callback.
For applications without OIDC, SAML or LDAP, create a Proxy Provider. Full proxy mode forwards application traffic through an Outpost; Forward Auth lets Caddy, Nginx or Traefik ask the Outpost for an access decision and then connect directly to the backend.
- Single application: a separate Provider and policy for each application; preferred for clear isolation.
- Domain level: shared authentication for several applications within a domain, with less configuration but without separate per-application policy enforcement in that mode.
Create the Provider, create its Application, assign it to the Embedded Outpost, and use the proxy configuration generated by the current Authentik interface. The Outpost address, callback path and authorization endpoint must match that deployment.
Forward Auth controls whether a request can enter; it does not automatically create a recognized backend user. If the backend consumes username, email or group headers, allow only the intended identity headers, overwrite untrusted client values and block direct access to the backend.
Preserve the database plus .env, compose.yml, data/, certs/ and custom-templates/, along with any Compose overrides and the Caddy configuration.
sudo install -d -m 0700 -o "$USER" -g "$USER" /srv/backups/authentik
cd /opt/authentik
set -a
. ./.env
set +a
BACKUP_FILE="/srv/backups/authentik/authentik-$(date -u +%Y%m%dT%H%M%SZ).dump"
docker compose exec -T postgresql pg_dump \
-U "${PG_USER:-authentik}" \
-d "${PG_DB:-authentik}" \
-Fc > "$BACKUP_FILE"
test -s "$BACKUP_FILE"
docker compose exec -T postgresql pg_restore --list < "$BACKUP_FILE" | head
unset PG_PASS AUTHENTIK_SECRET_KEY PG_USER PG_DB
Archive the configuration and persistent paths:
sudo tar --exclude='*.log' -czf \
"/srv/backups/authentik/files-$(date -u +%Y%m%dT%H%M%SZ).tar.gz" \
-C /opt/authentik .env compose.yml data certs custom-templates
Run these commands only from a trusted deployment directory: sourcing the environment file executes shell syntax. Check the actual mounts and directory existence before archiving; a failed tar operation is not a successful backup. Stop application writes or schedule a maintenance window when database and uploaded/certificate files need a consistent recovery point. Preserve the original secret key.
Encrypt identity/database backups, restrict access, set retention and copy them off-host. A dump listing only checks that the archive is readable, not that restoration succeeds. On an isolated replacement, use the same supported application/database versions, restore configuration and files, start PostgreSQL, restore the dump into an appropriate empty database, and then start server/worker. Test login, MFA, OIDC, Outposts and email before changing DNS. Never use a live production database as the restore-test target.
Authentik does not support downgrades. Follow every major release sequence and first reach the latest patch in the current sequence. The server and all Outposts must use matching versions.
cd /opt/authentik
# 先完成数据库和文件备份,再下载新 Compose 到临时文件
curl -fsSLo compose.yml.new https://docs.goauthentik.io/compose.yml
diff -u compose.yml compose.yml.new || true
docker compose -f compose.yml.new config --quiet
mv compose.yml compose.yml.previous
mv compose.yml.new compose.yml
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 server worker postgresql
The download in this example points to the latest Compose definition. Before replacing the old file, verify that its version is the next permitted upgrade, preserve local port bindings and overrides, and read any PostgreSQL-specific migration instructions. A database major-version change requires its own supported migration; changing the image alone is insufficient.
Do not skip release sequences or switch back to an older image after a database migration. Recovery means restoring the complete pre-upgrade database, secrets and files to a compatible instance, after validating that recovery in isolation.
cd /opt/authentik
docker compose config --quiet
docker compose ps
docker compose logs --tail=300 postgresql server worker
Check whether .env contains PG_PASS and AUTHENTIK_SECRET_KEY, then inspect free disk space, database volume permissions and the supported upgrade path.
sudo journalctl -u caddy -n 200 --no-pager
curl -fsSI http://127.0.0.1:9000/
curl -fsSI https://sso.example.com/
If loopback works while the public hostname fails, check DNS, TLS, WebSockets and forwarding headers using the layered access troubleshooting guide. Avoid disabling UFW or publishing 9000 as a shortcut.
Use one consistent external HTTPS hostname, match Redirect URIs exactly, synchronize clocks and inspect both application and Authentik logs. Avoid host timezone mounts and HTTP issuers or callbacks on an HTTPS deployment.
Check matching server/Outpost versions, reachability of the external Authentik URL, token validity and the expected Docker socket or proxy access. Remember to upgrade Outposts alongside the server.
The official minimum is 2 CPU cores and 2GB RAM. For a small production team, start planning around 2–4 vCPU, 4GB RAM and 40GB NVMe, then monitor login peaks, database growth and backup duration.
Both provide centralized identity, OIDC and SAML. Authentik emphasizes visual Flows and proxy integration; Keycloak has extensive realm and enterprise integration capabilities. Choose based on protocols, organizational requirements and maintenance experience.
No. Bind them to 127.0.0.1; expose 80/443 through Caddy and keep PostgreSQL 5432 unpublished.
Yes, with a Proxy Provider and Outpost in full proxy or Forward Auth mode. Prefer single-application Forward Auth when each application needs its own policy.
Its privileges can allow control of the host and access to secrets. Remove the default worker mount when automatic Outpost management is unnecessary, or evaluate a narrowly restricted socket proxy.
No supported downgrade exists. Back up first, upgrade sequentially and recover the complete compatible pre-upgrade instance if necessary.