DEV Community: DeployLark

Self-Host Supabase with Docker: Studio, API Keys and Errors

DeployLark — Thu, 22 Oct 2026 03:02:47 +0000

Supabase is an open source backend built on Postgres. It bundles a database, Auth, an auto-generated REST API, Storage, Realtime and Edge Functions, with Studio as the web dashboard. The supabase/supabase repository had about 113,000 GitHub stars on October 22, 2026, and the supabase/postgres image had passed 19 million pulls on Docker Hub.

This guide installs the official self-hosted release v0.8.3 with Docker Compose, generates the keys the official way, creates a table in Studio and reads it over the REST API with the anon key. It then covers the errors that usually come next: 401 from the gateway, PGRST301, an empty [] from Row Level Security, Storage upload errors and signups that never finish.

TL;DR:

Clone the self-hosted/v0.8.3 tag, copy docker/ to a project folder, run sh utils/generate-keys.sh --update-env and sh utils/add-new-auth-keys.sh --update-env, then docker compose up -d --wait. All 11 containers reported healthy in 37 seconds.
Studio and every API sit behind one gateway on port 8000. Studio uses HTTP basic auth with DASHBOARD_USERNAME and DASHBOARD_PASSWORD from .env.
Every API call needs an apikey header. Without it the gateway returns 401 Unauthorized. A token signed with a different JWT_SECRET returns PGRST301.
Tables created in Studio have RLS on. With no policy, the anon key gets [] with HTTP 200, not an error. Add a policy for the anon role.
Self-hosted Supabase is one project, and branching, PITR, managed backups, ETL and the Management API stay on the managed platform. Back up Postgres yourself before you run update.sh.

What self-hosted Supabase includes, and what stays on Cloud

The self-hosted stack is the same set of open source services the managed platform runs, wired together by one Compose file. The v0.8.3 file starts 11 containers: Studio, the Envoy API gateway, Auth (GoTrue), PostgREST, Realtime, Storage, imgproxy, postgres-meta, Edge Runtime, Postgres and the Supavisor connection pooler. Logs and analytics (Logflare and Vector) are an optional override that you add with sh run.sh config add logs.

Cloud-only features

The self-hosting overview lists what you give up:

Some features of the managed platform aren't available when self-hosting: branching, advanced metrics beyond logs, managed backups and PITR, analytics and vector buckets, ETL, and the Management API.

The same page says self-hosted Supabase "runs as a single project, which means that Studio doesn't support multiple organizations or projects". Most settings live in .env instead of dashboard screens. The overview also states that self-hosted Supabase "does not phone home or collect any telemetry".

Hardware and ports

Per the Docker guide, the minimum for all components is 4 GB RAM, 2 CPU cores and a 40 GB SSD, with 8 GB, 4 cores and 80 GB recommended. The pinned images in v0.8.3 took about 6.6 GB of disk before any data, with Studio (1.28 GB), Postgres (1.24 GB) and Supavisor (1.17 GB) the largest.

The default file publishes three host ports:

Port	Service	Purpose
8000	Envoy gateway	Studio plus `/rest/v1`, `/auth/v1`, `/storage/v1`, `/realtime/v1`, `/functions/v1`
5432	Supavisor	Postgres connections in session mode
6543	Supavisor	Postgres connections in transaction mode

Envoy is the default gateway in v0.8.3, and the 401 responses below carry server: envoy. Kong is still available as an override with sh run.sh config add kong. To move the gateway port, change API_GW_HTTP_PORT in .env. The old KONG_HTTP_PORT variable is kept only as a fallback so older .env files keep working.

Install Supabase with Docker Compose

You need Docker with the Compose plugin and git. The steps below are the sparse clone from the Docker guide, which pins the release tag.

Clone the pinned release

git clone --filter=blob:none --no-checkout --depth=1 --quiet \
  --branch self-hosted/v0.8.3 https://github.com/supabase/supabase
cd supabase
git sparse-checkout init --cone
git sparse-checkout set docker
git checkout --quiet
cd ..

mkdir supabase-project
cp -rf supabase/docker/. supabase-project
cd supabase-project && cp .env.example .env
printf 'ref=self-hosted/v0.8.3\n' > .supabase-version
docker compose pull

The tag pointed at commit bc27d2661edd09a5d0b8d76ce33da6d4071a756e from October 16, 2026. The .supabase-version file matters later, because update.sh reads it to know which release you started from. These are the image tags that release pins in docker-compose.yml:

services:
  studio:
    image: supabase/studio:2026.10.12-sha-3699278
  api-gw:
    image: envoyproxy/envoy:v1.39.1
  auth:
    image: supabase/gotrue:v2.197.0
  rest:
    image: postgrest/postgrest:v14.18
  realtime:
    image: supabase/realtime:v2.143.3
  storage:
    image: supabase/storage-api:v1.81.0
  imgproxy:
    image: darthsim/imgproxy:v3.31.4
  meta:
    image: supabase/postgres-meta:v0.100.0
  functions:
    image: supabase/edge-runtime:v1.77.4
  db:
    image: supabase/postgres:17.6.1.136
  supavisor:
    image: supabase/supavisor:2.9.13

Generate JWT_SECRET, ANON_KEY and SERVICE_ROLE_KEY

Never start the stack with the placeholder values from .env.example. The repo ships two scripts that write fresh secrets straight into .env:

sh utils/generate-keys.sh --update-env
sh utils/add-new-auth-keys.sh --update-env

The first script creates JWT_SECRET, the legacy ANON_KEY and SERVICE_ROLE_KEY (HS256 tokens signed with that secret, valid for five years), POSTGRES_PASSWORD, DASHBOARD_PASSWORD and the other internal secrets. The second adds the newer SUPABASE_PUBLISHABLE_KEY (sb_publishable_...) and SUPABASE_SECRET_KEY (sb_secret_...) plus an ES256 key pair, and it uncomments the lines in docker-compose.yml that pass the key pair to Auth, Realtime, Storage and Edge Functions. It needs Node 16 or newer, or it runs inside a node:22-alpine container that it pulls on first use. The legacy anon key and the new publishable key both worked in the apikey header. sh run.sh secrets prints the database and dashboard passwords, the publishable and secret keys and the S3 keys. Read ANON_KEY, SERVICE_ROLE_KEY and JWT_SECRET straight from .env.

Then set the URLs in .env. For a local install the defaults work: SUPABASE_PUBLIC_URL=http://localhost:8000, API_EXTERNAL_URL pointing at the same host, and SITE_URL=http://localhost:3000 for your app.

Start the stack and create a table in Studio

Keep the ports on localhost and start the stack

The default ports bind to every interface. Studio has only basic auth in front of it, so keep everything on the loopback until a reverse proxy is in place. An override file with the Compose !override tag replaces the port lists:

# docker-compose.local.yml
services:
  api-gw:
    ports: !override
      - 127.0.0.1:8000:8000/tcp
  supavisor:
    ports: !override
      - 127.0.0.1:5432:5432
      - 127.0.0.1:6543:6543

Add it to the COMPOSE_FILE line in .env so every docker compose and run.sh command layers it:

COMPOSE_FILE=docker-compose.yml:docker-compose.local.yml

You cannot do this with POSTGRES_PORT=127.0.0.1:5432, because the Compose file also passes that variable to services as a plain port number. Now start everything and wait for the health checks:

docker compose up -d --wait
docker compose ps

sh run.sh start runs the same up -d --wait. The command returned after 37 seconds with all 11 containers healthy, and the pooler and gateway listened only on 127.0.0.1.

At idle the 11 containers used about 1.1 GiB of RAM added together and under 1% CPU each. Realtime (248 MiB), Studio (202 MiB) and Supavisor (193 MiB) were the largest, while Auth used about 11 MiB and PostgREST about 18 MiB.

Create a table and read it over REST

Open http://localhost:8000. The browser asks for a username and password. That is the HTTP basic auth from DASHBOARD_USERNAME (default supabase) and the generated DASHBOARD_PASSWORD. Studio opens straight into a single project called Default Project.

In Table Editor, choose New table, name it notes, keep the default id and created_at columns and add a title column of type text. Leave Enable Row Level Security checked. Save, then use Insert, Insert row and enter a title.

PostgREST serves every table in the public schema under /rest/v1. Read the anon key from .env and query the table:

export ANON_KEY=$(grep '^ANON_KEY=' .env | cut -d= -f2-)
curl -s -H "apikey: $ANON_KEY" \
  "http://localhost:8000/rest/v1/notes?select=id,title"

The first answer was [] with HTTP 200, even though the row is there. That is RLS doing its job, covered in the next section. After adding a read policy, the same call returned the row:

[{"id":1,"title":"Hello from self-hosted Supabase"}]

The publishable key works the same way in the apikey header. The service role key bypasses RLS and returned the row even before the policy existed. The secret key bypassed RLS the same way for a Storage upload later in this guide. Keep both on servers only.

Fix API key, RLS, Storage and signup errors

Each error below came up during setup, with the change that cleared it.

API keys and RLS: 401, PGRST301, [] and 42501

A request with no apikey header, or with a value that is not one of your keys, stops at the gateway. Envoy answers HTTP/1.1 401 Unauthorized with the plain body Unauthorized. The fix is to send the key in the apikey header on every request, including from your own backend.

A valid apikey with a bad Authorization: Bearer token gets further and fails in PostgREST instead:

{"code":"PGRST301","details":"None of the keys was able to decode the JWT","hint":null,"message":"No suitable key or wrong key type"}

The same error, with HTTP 401, appeared after replacing ANON_KEY in .env with a token signed by a different secret and recreating the gateway, Auth and REST. The gateway accepted it because it matched .env, and PostgREST rejected it because it was not signed with JWT_SECRET. Auth kept answering /auth/v1/settings normally the whole time, so a working Auth endpoint does not prove your keys match. Putting the generated keys back and running docker compose up -d --force-recreate api-gw rest auth returned the row again. If you ever change JWT_SECRET, run generate-keys.sh again so all three values are regenerated together, then sh run.sh recreate.

Studio enables RLS on new tables, and a table with RLS and no policy returns no rows to anon without any error. Studio warns about this when you create the table. Add a policy in the SQL Editor or with psql inside the supabase-db container:

create policy "Public can read notes"
  on public.notes for select
  to anon
  using (true);

That policy only covers reads. An anon POST to /rest/v1/notes still failed with HTTP 401, which is the intended result:

{"code":"42501","details":null,"hint":null,"message":"new row violates row-level security policy for table \"notes\""}

Add a separate insert policy for the role that should write, usually authenticated, instead of disabling RLS.

Storage and signup: NoSuchBucket, AccessDenied and 504

Storage and Auth fail in less obvious ways, because the HTTP status or the log line does not always match the real cause.

Storage errors come back with HTTP 400 and the real status inside the JSON body, which trips up clients that only check the status code. Uploading to a bucket that did not exist yet returned:

{"statusCode":"404","error":"Bucket not found","message":"Bucket not found","code":"NoSuchBucket"}

After creating a private bucket called docs with the service role key, an upload with the anon key returned {"statusCode":"403","error":"Unauthorized","message":"new row violates row-level security policy","code":"AccessDenied"}. Storage keeps object metadata in Postgres, so the same RLS rules apply. Uploading with the service role key succeeded, and so did an upload with the sb_secret_ key in the apikey header. The file showed up in Studio. For uploads from the browser, add policies on storage.objects per the Storage access control docs.

A fresh install has email signups on and confirmations required, and .env points SMTP_HOST at supabase-mail on port 2500. No container with that name exists in the Compose file. A POST to /auth/v1/signup hung for 10 seconds and returned {"code":504,"error_code":"request_timeout",...}. Other write-ups show the same root cause as a 500 with Error sending confirmation email and a lookup supabase-mail DNS error in the Auth logs.

For a production install, set real SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS and SMTP_ADMIN_EMAIL values, then recreate Auth. For a local test stack, setting ENABLE_EMAIL_AUTOCONFIRM=true and running docker compose up -d --force-recreate auth made the next signup return HTTP 200 with a session. Do not leave autoconfirm on for real users. A plain docker compose restart auth does not reread .env. After a restart the Auth container still had the old GOTRUE_MAILER_AUTOCONFIRM value, and only a recreate picked up the change. Use sh run.sh recreate <service> after every .env edit.

HTTPS, backups and upgrades

Set SITE_URL and add HTTPS

Everything above runs on localhost. Once you put Supabase on a domain, three URL variables in .env have to change together, per the reverse proxy guide:

SUPABASE_PUBLIC_URL=https://supabase.example.com
API_EXTERNAL_URL=https://supabase.example.com/auth/v1
SITE_URL=https://app.example.com

SITE_URL is where Auth sends users after email links and OAuth logins when no other address is given. A redirect_to address has to match an entry in ADDITIONAL_REDIRECT_URLS, which Auth uses as its allow list. Otherwise Auth sends the user to SITE_URL instead. The redirect URLs docs allow wildcard patterns such as https://app.example.com/**, but recommend exact URLs in production.

The default Envoy gateway does not terminate TLS, so HTTPS comes from a proxy in front of it. v0.8.3 ships two proxy overrides. Per the guide, sh run.sh config add caddy followed by sh run.sh start adds Caddy with automatic Let's Encrypt certificates, configured in volumes/proxy/caddy/Caddyfile. sh run.sh config add nginx adds Nginx with Certbot instead, and it also needs PROXY_DOMAIN and CERTBOT_EMAIL set in .env. Both need a DNS record pointing at the server and ports 80 and 443 open. The guide's check is curl -I https://<your-domain>/auth/v1/, which should answer 401.

The guide also allows Nginx Proxy Manager, Traefik, HAProxy or another proxy you already run. With Nginx Proxy Manager, add a proxy host that forwards to port 8000, turn on WebSockets support for Realtime, pass the X-Forwarded headers, and remove the gateway's host port binding if the proxy shares the Docker network. Keep Studio's basic auth in front of the dashboard either way, or add an access list in your proxy.

Back up and upgrade with update.sh

The updating guide warns that update.sh "backs up your configuration files to backups/, but it does not back up Postgres or Storage data". Managed backups and PITR are Cloud features, so backups are your job.

A logical dump of your own schema runs inside the database container:

docker exec supabase-db pg_dump -U postgres -d postgres \
  --schema=public --no-owner > public-backup.sql

The dump contained the notes table, its row and the Public can read notes policy. Storage files live on disk under volumes/storage, and the database files under volumes/db/data, so copy both directories with the stack stopped for a full file-level backup.

Per the updating guide, back up first, then preview and apply the next release, then pull and recreate:

sh update.sh --dry-run
sh update.sh
sh run.sh pull
sh run.sh recreate

update.sh does a three-way merge against the release in .supabase-version, keeps your .env, and stops with exit code 2 and merge markers if your edits conflict with upstream changes. Releases that need a manual step, such as a Postgres major upgrade, are flagged before anything is applied. sh reset.sh is the opposite tool. It runs docker compose down -v and deletes the data directories, so never run it on an install you care about.

If you want a broader self-hosted setup around this, Coolify can deploy the app that talks to Supabase, and Portainer gives you a web view of the 11 containers.

FAQ

Setup, limits and login

How much RAM does self-hosted Supabase need?

The docs ask for 4 GB of RAM and 2 cores at minimum, with 8 GB and 4 cores recommended. The full default stack of 11 containers used about 1.1 GiB at idle, and the images took about 6.6 GB of disk. You can remove Realtime, Storage, imgproxy or Edge Functions from the Compose file to save memory, per the Docker guide.

Can one self-hosted Supabase run multiple projects?

No. The self-hosting overview says Studio "doesn't support multiple organizations or projects". Users who run two stacks on one host report in GitHub issue #37412 that each copy needs its own .env, ports and renamed container_name values.

Why does my new dashboard password not work?

Studio's login is HTTP basic auth enforced at the gateway, which reads DASHBOARD_USERNAME and DASHBOARD_PASSWORD from its environment when the container is created. A restart keeps the old environment, so run sh run.sh recreate after editing .env. The Docker guide also says the password "must include at least one letter" and should not use numbers only or special characters.

Keys, email and redirects

Why does REST return "No suitable key or wrong key type" while Auth works?

PostgREST could not verify the JWT with your JWT_SECRET or JWKS. A token signed by another secret produced exactly that PGRST301 error, while /auth/v1/settings kept working. Regenerate the keys together with generate-keys.sh, recreate the stack, and send a user's JWT, not the secret key, as the Bearer token.

Why does signup fail with "Error sending confirmation email"?

The default .env points SMTP at a supabase-mail host that the Compose file does not create. Here the signup timed out with a 504 after 10 seconds. Set real SMTP values and recreate Auth, or use ENABLE_EMAIL_AUTOCONFIRM=true only on a test stack.

Why do auth emails redirect to localhost:3000?

SITE_URL defaults to http://localhost:3000. Set it to your app's URL. J0 explained the other common cause in GitHub issue #22242: "A redirect to the SITE_URL instead of the redirect_to URL typically indicates that the redirect URL is not in the allowed URL list." Add the callback URL to ADDITIONAL_REDIRECT_URLS and recreate Auth.

Portainer CE on Docker: Install, Stacks and Git Updates

DeployLark — Thu, 22 Oct 2026 03:01:46 +0000

Portainer is a web UI for Docker. It shows containers, images, volumes and networks, and it can deploy whole Compose projects as stacks, including straight from a Git repository. The portainer/portainer repository had about 38,700 GitHub stars on October 21, 2026, and the portainer/portainer-ce image had passed 1.5 billion pulls on Docker Hub. The current Community Edition (CE) release is 2.45.2 LTS, published on October 8, 2026.

This guide installs Portainer CE with Docker Compose, gets past the five-minute admin setup timeout, moves an app that was started with plain docker compose into Portainer without losing its data, and sets up a stack that redeploys itself when you push to Git. It ends with a backup and an upgrade from 2.45.1 to 2.45.2.

TL;DR:

Run portainer/portainer-ce:2.45.2 with the Docker socket and a portainer_data volume, and publish only 127.0.0.1:9443. Port 8000 is only for Edge Agents.
Create the admin user within 5 minutes of the first start, using the setup_token= value from docker logs portainer. If the timeout hits, run docker restart portainer and use the new token it prints.
Apps started with docker compose show as Limited. Run docker compose down without -v, then deploy the same file as a Portainer stack with the same name, and the stack gets Total control while keeping its volumes.
For Git stacks, turn on polling on the Git source, or turn on Create a Webhook on the stack. In CE 2.45 both redeployed the stack after a push.
Before an upgrade, download a backup from Settings, then bump the image tag and recreate the container. Your stacks keep running.

Install Portainer CE with Docker Compose

The compose file and ports

The official Linux install page uses the lts tag and publishes ports 9443 and 8000 on all interfaces. The version below pins the tag and binds the UI to localhost, so nothing is reachable from the network until you put a reverse proxy in front:

name: portainer

services:
  portainer:
    container_name: portainer
    image: portainer/portainer-ce:2.45.2
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    ports:
      - 127.0.0.1:9443:9443

volumes:
  portainer_data:
    name: portainer_data

networks:
  default:
    name: portainer_network

Start it with docker compose up -d. The ports work like this:

9443 serves the UI and API over HTTPS with a self-signed certificate that Portainer creates on first start. The generated certificate was valid for five years.
9000 is plain HTTP. The container still listens on it, and http://portainer:9000 answered from another container on the same network, but the docs only add -p 9000:9000 "for legacy reasons". Do not publish it.
8000 is the tunnel server for Edge Agents. The docs call it optional, so leave it out unless you manage remote Edge environments.

Portainer team member jamescarppe answered the port question in issue #10797: "Port 8000 has never been used for the Portainer UI - 8000 is used for the Edge Agent tunnel exclusively."

The socket mount gives Portainer full control of Docker on the host. Treat the UI like root access. For remote access, put it behind HTTPS with a proxy such as Nginx Proxy Manager or keep it on a VPN. The reverse proxy docs warn that a proxy that takes HTTP from the browser but forwards to 9443 breaks login, because Portainer then sets Secure cookies that the browser drops. Forward the Host header as the browser sent it, which in nginx means $http_host rather than $host.

First login and the setup token

Open https://127.0.0.1:9443 and accept the certificate warning. The setup page asks for a username (default admin), a password of at least 12 characters and a setup token. Since versions 2.43 and 2.39.4, new instances require that token and print it to the log:

docker logs portainer 2>&1 | grep setup_token

The setup token FAQ lists the flags to change this: --setup-token <value> sets your own, --admin-password-file pre-sets the admin password so no token is needed, and --no-setup-token turns the check off, which the docs reserve for networks you fully control. After the admin user exists, Portainer asks about Edge Compute (Skip is fine for a single host) and then opens the environment wizard with your local Docker already connected.

Fix the admin setup timeout

What the timeout looks like

A new Portainer instance gives you 5 minutes to create the admin user. The timeout FAQ explains it as protection against someone else claiming a fresh install. The 5 minutes count from container start. In the log below, the HTTPS server started at 02:11:47 UTC and the timeout line appeared at 02:16:47 UTC, five minutes later:

The container does not exit. docker ps still shows it as Up and /api/status still answers, so it looks healthy from the outside. The browser shows a New Portainer installation card that says the instance timed out for security purposes, and the API refuses to create the admin with Administrator initialization timeout.

Restart and finish within five minutes

Restart the container and the clock starts again:

docker restart portainer
docker logs portainer 2>&1 | grep setup_token

The restart prints a new setup token, so copy it again instead of reusing the one from the first start. The docs also mention that in some cases you need docker rm portainer and a fresh docker run or docker compose up -d. If the timeout shows up on an instance that already had an admin, the same FAQ points at the data volume: if portainer_data is not mounted, Portainer thinks it is a new install.

Move existing compose projects into Portainer

Why the stack shows Limited

Portainer lists every Compose project it finds on the host, but it can only edit the ones it deployed. Here Uptime Kuma 2.5.6 was started with plain docker compose up -d from its own folder, as in our Uptime Kuma setup guide:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.6
    restart: unless-stopped
    volumes:
      - kuma-data:/app/data
    ports:
      - 127.0.0.1:3001:3001

volumes:
  kuma-data:

In the Stacks list it appeared as uptime-kuma with Control set to Limited, and its details page said so:

A Limited stack has no Editor tab, no stack-level stop or delete, no environment variables and no duplicate or migrate option. You can still start, stop, restart and inspect its containers. Portainer cannot fix that by itself because it never had the compose file. jamescarppe explained it in portainer-docs issue #75: "The \"limited\" state displays when a stack is deployed outside of Portainer." The same thread notes that Portainer itself will always show as Limited, since it cannot deploy itself.

Take full control without losing data

The fix is to redeploy the same compose file through Portainer, under the same name. Compose prefixes named volumes with the project name, and Portainer uses the stack name as the project name. So a stack called uptime-kuma finds the existing uptime-kuma_kuma-data volume.

In the old project folder, run docker compose down. Do not add -v, which deletes the named volumes.
In Portainer, open Stacks, then Add stack, and set Name to exactly the old project name (uptime-kuma).
Choose Web editor or Upload and use the same compose file. Load the old .env with Load variables from .env file if the project had one.
Click Deploy the stack.

After the redeploy, the stack showed Total control, an Editor tab and stop and delete buttons. Docker listed the same uptime-kuma_kuma-data volume, and Uptime Kuma opened on its login page instead of the first-run setup, so the admin account and data had survived. The same steps work for any compose project that keeps its data in named volumes, as long as the stack name matches the old project name.

Relative bind mounts do not carry over. Portainer stores each stack's compose file under /data/compose/<stack id> inside its own container, and Compose resolves ./data against that folder. A stack with ./data:/d got the host path /data/compose/3/data as its mount source, a new empty directory, not the old project folder. A project like the Stirling-PDF stack, which keeps everything under ./stirling-data, needs absolute host paths in its compose file before you redeploy it in Portainer. Relative paths for Git stacks were requested in issue #6390 and shipped in 2.17 as a Business Edition option, and the Add a new stack docs still list relative path volumes as Business Edition only.

Deploy stacks from Git and keep them updated

Add a Git source and deploy the stack

In 2.45, Git stacks start from a source. Open Sources in the left menu, click Add new, and enter a name and the repository URL. Turn off Authentication for a public repository, or add a username and token for a private one. Turn on Enable polling and set a Fetch interval such as 5m. The form tests the connection before you can continue. Portainer clones the repository from inside its own container, so use a URL the container can reach. Here a Forgejo 17.0.0 server on the same Docker network served http://forgejo:3000/labadmin/whoami-stack.git and the form reported Connection successful.

The repository held one small compose file:

services:
  whoami:
    image: traefik/whoami:v1.12.0
    command: --name ${APP_NAME:-whoami}
    ports:
      - 127.0.0.1:8082:80
    restart: unless-stopped

Then go to Stacks, Add stack, pick Repository, select the source, keep refs/heads/main as the reference and set Compose path to compose.yml. Environment variables can be set in the form, but a stack.env file referenced from the compose file must already be in the repository, as the form itself points out.

After the deploy, the stack page shows a Managed by Git panel with the repository, reference, file, current commit, polling interval and webhook URL, plus Pull and redeploy, Edit stack settings and Detach from Git buttons. Detaching is one way: the stack keeps only its main compose file and cannot go back to Git.

Polling and webhooks in CE

Both update paths worked in CE 2.45.1:

Polling: with a 1-minute fetch interval on the source, a commit that changed the image from traefik/whoami:v1.11.0 to v1.12.0 was running 36 seconds after the push. The delay can be up to one full interval plus the redeploy. In 2.45 the interval belongs to the source, not the stack.
Webhook: with Create a Webhook on, a commit followed by an unauthenticated curl -X POST to the webhook URL returned HTTP 204, and the container served the new name 1.5 seconds later. A made-up webhook ID returned 404.

The webhook URL works without a login, so treat it like a password and only paste it into your Git server or CI secrets. Two options next to it carry a Business Feature badge in CE: Re-pull image, which pulls fresh images on every update, and Force redeployment, which overwrites local changes even when Git has not changed.

Portainer's own pages disagree about what CE gets. The features page lists "GitOps automatic updates and webhooks" among Business Edition features, and the January 2026 CE vs BE post sums up CE GitOps as "Basic Git deployment". The Add a new stack docs describe polling and webhook updates for Git stacks with no Business Edition flag, and both worked in CE 2.45. The separate stack webhooks page, which the web editor and upload options link to, is marked Business Edition only. Since Portainer markets these as Business Edition features, check the toggles after each upgrade before you build a deploy pipeline on them.

To get a new image in CE, change the tag in Git instead of reusing a moving tag like latest. Pinned tags are the safer habit for any stack.

Back up, upgrade and keep it private

Back up the configuration

In Settings, under Back up Portainer, Download backup file is available in CE. Store in S3 carries a Business Feature badge, and the settings docs list scheduled local backups as Business Edition too. The download here was a 38 KB tar.gz with portainer.db, the compose files of both Portainer stacks, the TLS certificate and key and the Edge tunnel private key. Turn on Password protect before you download it, and store it like a secret.

The backup FAQ is clear that this covers Portainer configuration only, not containers, images, volumes or the data inside them. Back up app data separately. For a full copy of Portainer itself, stop it and archive the volume:

docker compose down
docker run --rm -v portainer_data:/data:ro -v "$PWD/backup:/backup" alpine:3.24.2 tar czf /backup/portainer_data-2.45.1.tar.gz -C /data .

Upgrade to a new version

The Docker upgrade docs stop and remove the container, pull the new image and start it again with the same volume. With Compose, change the tag and recreate. This install went from 2.45.1 to the 2.45.2 tag shown in the compose file above:

sed -i "s/portainer-ce:2.45.1/portainer-ce:2.45.2/" compose.yml
docker compose pull
docker compose up -d

On start, 2.45.2 copied the database to /data/backups/portainer.db.bak, logged migrating database from version 2.45.1 to 2.45.2 and then db migrated to 2.45.2. The Uptime Kuma and whoami containers kept running the whole time, both stacks still showed Total control, and the next Git push was live within 46 seconds through polling. The rollback FAQ explains why the database copy matters: a newer database will not start on an older Portainer, so a rollback means restoring portainer.db.bak and starting the old image tag.

Portainer itself is light. At idle on 2.45.1 it used 27 to 34 MiB of RAM and close to 0% CPU. To show it on a start page, Homepage has a Portainer widget. Keep the UI on localhost or a private network, and only expose it through HTTPS with access limited to people who should have root on the host.

FAQ

Setup and access

What does "Your Portainer instance has timed out for security purposes" mean?

You did not create the admin user within 5 minutes of the first start. Restart the container with docker restart portainer, get the new setup token from docker logs portainer, and finish the form within 5 minutes. Users reported the same log line in issue #8457, and the official FAQ gives the restart fix.

Do you need ports 8000 and 9000?

No. The UI and API run on 9443 over HTTPS. Port 8000 is only for Edge Agents and port 9000 is plain HTTP that the docs keep for legacy setups. A user in issue #10797 lost access on 9000 after an upgrade because the new default command no longer publishes it.

Where is the setup token?

In the container log, on the line that starts with setup_token=. Run docker logs portainer 2>&1 | grep setup_token. The setup token FAQ covers the flags that set or skip it.

Stacks and Git

Why do stacks show as Limited, and how do you fix it?

Portainer did not deploy them, so it has no compose file to edit. Run docker compose down without -v in the project folder and deploy the same file as a Portainer stack with the same name. A user in issue #12348 could not delete or edit Limited stacks after reinstalling Portainer and fixed it by redeploying every compose file.

Are Git webhooks and automatic updates free in Portainer CE?

For Git stacks in CE 2.45, yes: polling on the Git source and the Create a Webhook toggle both redeployed the stack after a push, and polling kept working after the upgrade to 2.45.2. Re-pull image and Force redeployment carry a Business Feature badge, and the docs mark webhooks on non-Git stacks as Business Edition. Portainer's features page still lists GitOps automatic updates and webhooks as Business Edition, so check the toggles in your version before you rely on them.

Does a Portainer backup include my containers and volumes?

No. The backup FAQ says it covers Portainer settings, users, environments, stack definitions and credentials, not containers, images, volumes or app data. Back up app volumes on their own.

Homepage Dashboard Docker Setup: Config, Widgets and Labels

DeployLark — Tue, 20 Oct 2026 06:48:35 +0000

Homepage is a static start page for a homelab. You describe services, bookmarks and widgets in YAML files, and it shows live data from the apps behind them, such as container stats, uptime and queue counts. On October 20, 2026, the gethomepage/homepage repository had about 33,200 GitHub stars, and v2.6.0 had shipped three days earlier. This guide runs v2.6.0 with Docker Compose, wires up an Uptime Kuma widget, discovers a container from Docker labels through a read-only socket proxy and fixes the Host validation failed error that trips up most first installs.

TL;DR:

Run ghcr.io/gethomepage/homepage:v2.6.0 with ./config mounted at /app/config and port 3000 bound to 127.0.0.1. The first start writes default YAML files into that folder.
Set HOMEPAGE_ALLOWED_HOSTS to every host and port people or monitors use, comma-separated with no spaces. Only localhost:3000 and 127.0.0.1:3000 work without it.
After any env change, recreate the container with docker compose up -d. A docker compose restart keeps the old value.
For Docker stats and label discovery, point docker.yaml at a tecnativa/docker-socket-proxy container with CONTAINERS=1 and POST=0 instead of mounting the socket into Homepage.
Add homepage.* labels to any container and it shows up on the dashboard, widget included.

Install Homepage with Docker Compose

The compose file

The Docker install docs show a single homepage service with an optional socket mount. This file adds a socket proxy, as the Docker integration docs suggest, plus two services for Homepage to watch: Uptime Kuma 2.5.6 and the tiny traefik/whoami web server. The official examples use :latest. Every tag here is pinned to what ran:

name: hp
services:
  dockerproxy:
    image: tecnativa/docker-socket-proxy:v0.5.0
    environment:
      - CONTAINERS=1
      - POST=0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

  homepage:
    image: ghcr.io/gethomepage/homepage:v2.6.0
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - ./config:/app/config
    environment:
      HOMEPAGE_ALLOWED_HOSTS: ${HOMEPAGE_ALLOWED_HOSTS:-}
    depends_on:
      - dockerproxy
    restart: unless-stopped

  uptime-kuma:
    image: louislam/uptime-kuma:2.5.6
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - kuma-data:/app/data
    restart: unless-stopped

  whoami:
    image: traefik/whoami:v1.12.0
    ports:
      - "127.0.0.1:8081:80"
    labels:
      - homepage.group=Lab
      - homepage.name=whoami
      - homepage.icon=traefik.png
      - homepage.href=http://127.0.0.1:8081/
      - homepage.description=Discovered from Docker labels
      - homepage.widget.type=customapi
      - homepage.widget.url=http://whoami/api
      - homepage.widget.mappings[0].label=Hostname
      - homepage.widget.mappings[0].field=hostname
      - homepage.widget.mappings[1].label=Remote
      - homepage.widget.mappings[1].field=remoteAddr
    restart: unless-stopped

volumes:
  kuma-data:

Put the allowed hosts in a .env file next to it. The section on host validation below explains each entry:

HOMEPAGE_ALLOWED_HOSTS=homepage.lab.test:3000,homepage:3000

Then start it:

mkdir -p config
docker compose up -d
curl -s http://127.0.0.1:3000/api/healthcheck

The health check answered 2.9 seconds after docker compose up -d. That curl works without an allowed-hosts entry only because the host port is 3000. When I published Homepage on 127.0.0.1:3900 instead, the same health check on the server returned 400 until 127.0.0.1:3900 was on the list. By default the container runs as root. The docs support PUID and PGID for a non-root user, and with the socket proxy Homepage does not need socket access at all.

First start and the default config files

Start with an empty ./config folder. After the first start and a few page loads, mine held settings.yaml, services.yaml, widgets.yaml, bookmarks.yaml, docker.yaml, kubernetes.yaml and proxmox.yaml, plus empty custom.css and custom.js files and a logs folder. Most of the YAML files start with a comment that links to their docs page. The default services.yaml holds three placeholder groups pointing at http://localhost/, the default widgets.yaml shows CPU, memory and disk usage plus a DuckDuckGo search box, and the default settings.yaml only has placeholder weather API keys.

Edits to these files do not need a container restart. The settings docs say to click the refresh icon at the bottom right of the page to clear cached dashboard data. Logs go to config/logs/homepage.log as well as docker compose logs homepage.

Add services and info widgets

services.yaml with an Uptime Kuma widget

A service entry is a card with a name, icon, link and description. Add server and container to show a status dot and container stats, and add a widget block to pull data from the app API. The Uptime Kuma widget reads a single status page, so create one in Uptime Kuma first. This one has the slug lab and two HTTP monitors, one for whoami and one for the Homepage health check:

---
- Monitoring:
    - Uptime Kuma:
        icon: uptime-kuma.png
        href: http://127.0.0.1:3001/
        description: Status page lab
        server: lab-docker
        container: hp-uptime-kuma-1
        showStats: true
        widget:
          type: uptimekuma
          url: http://uptime-kuma:3001
          slug: lab

The widget URL uses the Compose service name, because the request comes from the Homepage container, not from the browser. Homepage looks up icon names in the Dashboard Icons set, so you only type the name.

The 67% is the average 24-hour uptime of every monitor on the status page, which is how the widget computes it. When the screenshot was taken, whoami stood at 100% and the Homepage monitor at 33%, because two of its three checks had failed with HTTP 400. The host validation section below explains why.

widgets.yaml and settings.yaml

Info widgets sit in the bar across the top. This file keeps the resources and search widgets from the defaults and adds a clock:

---
- resources:
    cpu: true
    memory: true
    disk: /
- datetime:
    text_size: md
    format:
      dateStyle: medium
      timeStyle: short
- search:
    provider: duckduckgo
    target: _blank

Theming and layout live in settings.yaml. The settings docs cover the full list. These keys set a dark theme with the slate palette, boxed headers, status dots instead of text, and a two-column row layout for each group:

---
title: Lab dashboard
theme: dark
color: slate
headerStyle: boxed
statusStyle: dot
layout:
  Monitoring:
    style: row
    columns: 2
  Lab:
    style: row
    columns: 2

Use background for a wallpaper image and custom.css in the config folder for anything the settings do not cover.

Docker integration and label discovery

docker.yaml through a socket proxy

Homepage talks to the Docker API for container status, CPU and memory stats, and label discovery. The docs offer two ways in. Mounting /var/run/docker.sock into Homepage works, but the docs note that "In order to use the socket directly homepage must be running as root", and socket access gives full control of the host. The :ro mount flag does not change that, because it doesn't limit the Docker API. The safer route is a socket proxy that only exposes read endpoints. Point docker.yaml at it:

---
lab-docker:
  host: dockerproxy
  port: 2375

lab-docker is just a name. Service entries refer to it with server: lab-docker. The proxy listens on port 2375 inside the Compose network only, with no published port. With CONTAINERS=1 and POST=0, curl from another container on the same network got these results:

GET  /containers/json             200
POST /containers/<id>/restart     403
GET  /images/json                 403

So Homepage can list containers and read stats, but it cannot restart anything or browse images. If you run Docker Swarm, the docs add SERVICES=1 and TASKS=1 to the proxy.

Labels on the container

Automatic discovery reads homepage.* labels from every container the Docker server can see. The keys mirror the YAML in services.yaml, written with dots. The whoami container in the compose file above carries a group, name, icon, link and description, plus a customapi widget that calls the whoami JSON endpoint and maps two fields:

labels:
  - homepage.group=Lab
  - homepage.name=whoami
  - homepage.icon=traefik.png
  - homepage.href=http://127.0.0.1:8081/
  - homepage.description=Discovered from Docker labels
  - homepage.widget.type=customapi
  - homepage.widget.url=http://whoami/api
  - homepage.widget.mappings[0].label=Hostname
  - homepage.widget.mappings[0].field=hostname
  - homepage.widget.mappings[1].label=Remote
  - homepage.widget.mappings[1].field=remoteAddr

Nothing about whoami is in services.yaml. After docker compose up -d, the Lab group appeared with the whoami card, a green status dot from the container state and the two mapped values, visible in the dashboard screenshot above. The Remote value is an address on the Compose network, because Homepage makes the widget request from its own container, not from the browser. The docs say the server and container values are inferred for discovered services, and the whoami card needed neither label. To keep one dashboard from picking up labels meant for another, the docs describe instanceName in settings.yaml with matching homepage.instance.<name>.* labels.

The same pattern works for real apps that have a native widget. A Paperless-ngx or Nginx Proxy Manager container can carry its own homepage.widget.type and API credentials as labels, so the dashboard entry lives next to the service it describes.

Fix Host validation failed with HOMEPAGE_ALLOWED_HOSTS

What the error looks like

Since v1.0.0, released on March 14, 2025, Homepage checks the Host header of every API request. The installation docs list it as the one required variable for reaching Homepage through any URL other than localhost. If the host is not on the list, the page and its API calls, /api/healthcheck included, return HTTP 400. This is the response to Host: homepage.lab.test:3000 before the variable was set:

The log line names the exact host and port that failed. Copy that value into the variable. Requests to http://127.0.0.1:3000 and http://localhost:3000 always pass, which is why a first test on the server itself often works and the same dashboard breaks from a laptop on the LAN. That only covers port 3000. If you map another host port, such as 8080:3000, add 127.0.0.1:8080 or the LAN address with :8080, as users found in discussion #4920.

A second case is easy to miss. Uptime Kuma checked http://homepage:3000/api/healthcheck from inside the Compose network, so its requests arrived with Host: homepage:3000. That monitor went Down at 10:12:15 with HTTP 400 and came back Up at 10:14:15, right after homepage:3000 joined the list. Any monitor, reverse proxy or script that reaches Homepage by container name needs that name on the list too, port included. Our Uptime Kuma guide covers setting up that kind of HTTP monitor.

This screenshot came a few minutes later than the dashboard one. By then four of the monitor's six checks had passed, so its own uptime read 66.67%.

The value to set, and recreate the container

The value is a comma-separated list with no spaces. Include the port whenever the browser URL has one:

HOMEPAGE_ALLOWED_HOSTS=homepage.lab.test:3000,homepage:3000

Behind a reverse proxy on port 443, the browser sends the bare domain, such as dash.example.com, so that is the entry. With that list, homepage.lab.test:3000 and homepage:3000 returned 200, and evil.example:3000 still returned 400.

Then recreate the container. I added a third host to .env and ran docker compose restart homepage. Inside the container, the variable still held the old two hosts and the new host got 400. After docker compose up -d homepage, the variable held all three and the request returned 200. Maintainer shamoon wrote in discussion #5033: "You need to re-create a container when you change env variables, not just restart." Check what the container really sees with docker compose exec homepage env | grep ALLOWED.

Setting the variable to * turns the check off. The docs do not recommend it and add that "the built-in host check is a best-effort guard for local setups and is not a substitute for edge protections."

Secure and run Homepage

Put authentication in front of it

Homepage shows internal hostnames and links, and its API proxy calls your services with the keys from your config. Keep it on 127.0.0.1 or a private network and publish it through a reverse proxy with TLS, as in the Nginx Proxy Manager guide. Since v2.0.0 Homepage also includes an optional login gate, which this guide doesn't turn on. The installation docs list HOMEPAGE_AUTH_ENABLED=true, a HOMEPAGE_AUTH_SECRET of at least 32 characters, HOMEPAGE_EXTERNAL_URL, and either HOMEPAGE_AUTH_PASSWORD or OIDC settings. The same docs warn that Homepage does not rate limit password attempts, so a proxy or VPN should still sit in front of any public instance. Keep to the newest release as well. v2.6.0 fixes GHSA-qxcr-4rv3-v23r, a high-severity bypass of that login gate in versions 2.0.0 to 2.5.0.

API keys do not need to sit in plain YAML. Per the Docker install docs, the value of any HOMEPAGE_VAR_NAME environment variable replaces {{HOMEPAGE_VAR_NAME}} in the config, and HOMEPAGE_FILE_NAME points at a file, such as a Docker secret, whose contents replace {{HOMEPAGE_FILE_NAME}}.

Resource use

Homepage is light. At idle, docker stats showed these averages for the four containers:

Container	Memory	CPU
homepage v2.6.0	116.5 MiB	0.00%
uptime-kuma 2.5.6	139.6 MiB	0.41%
docker-socket-proxy v0.5.0	22.3 MiB	0.00%
whoami v1.12.0	2.4 MiB	0.00%
Total	280.8 MiB	0.42%

Homepage never went above 0.04% CPU. It fits next to heavier apps on a small VPS, such as a Coolify host or a box that also runs Plausible.

FAQ

Host validation and setup

Why does the error stay after setting HOMEPAGE_ALLOWED_HOSTS?

Usually the container was restarted, not recreated, so it still has the old environment. Run docker compose up -d and check with docker compose exec homepage env. In discussion #5033 and discussion #5412, the maintainer's answer to this error was to recreate the container, not just restart it. The #5412 user ran Homepage through TrueNAS apps and then Dockge, so check how your stack manager recreates a container.

Does HOMEPAGE_ALLOWED_HOSTS need the port?

Yes, whenever the URL has one. The check compares the full Host header, so 192.168.1.10:3000 and 192.168.1.10 are different entries. Discussion #4920 also shows that a reverse proxy can change the Host header, so match the value printed in the log.

Can the list contain spaces?

No. The docs specify a comma-separated list with no spaces, and discussion #4789 traces a failing setup to a space after a comma.

Widgets and Docker

Why does a widget show API Error?

The widget call from Homepage to the service failed. The troubleshooting page suggests the API Error Information button on the widget, then config/logs/homepage.log, and LOG_LEVEL=debug for more detail. Check that the widget URL works from inside the Homepage container. A container name like http://uptime-kuma:3001 works there, localhost does not.

Why are containers with homepage labels not showing up?

Homepage needs a working Docker connection in docker.yaml, and the labels should include homepage.group and homepage.name, as in the docs examples. With the socket mounted directly, Homepage must run as root or have socket access, a common cause in discussion #3124. A socket proxy with CONTAINERS=1 avoids the permission problem.

Is mounting docker.sock into Homepage safe?

It works, but it hands the container full control of Docker. The Docker integration docs point to a socket proxy for that reason. With POST=0, the proxy above refused a container restart with 403 while still serving the container list.

Originally published on DeployLark: Homepage Dashboard Docker Setup: Config, Widgets and Labels

GitLab CE vs Forgejo: Self-Hosted Git on Docker, Measured

DeployLark — Mon, 19 Oct 2026 03:33:43 +0000

GitLab CE and Forgejo both give you a private Git server with issues, code review, CI and a container registry. They sit at opposite ends of the weight scale. This comparison ran both under Docker Compose on the same box, pushed a real pipeline through each runner, pushed an image to each registry, migrated the same GitHub repository into both and ran each backup command. The numbers below come from that run on October 19, 2026.

TL;DR:

On an 8 vCPU host, Forgejo 15.0.10 with Postgres and a runner idled at 285.7 MiB of RAM and under 1% of one CPU core. GitLab CE 19.5.0 with its runner idled at 8,722.6 MiB with default settings. The GitLab container alone dropped to 2,466.5 MiB with the memory-constrained settings from the GitLab docs.
Forgejo answered its health check 5.4 seconds after docker compose up -d. GitLab served its sign-in page after 145 seconds.
Both ran a trivial CI job, accepted a docker push to the built-in registry, migrated a GitHub repo and wrote a backup archive of 15.6 MB (Forgejo) or 16.2 MB (GitLab).
GitLab CE is MIT licensed, with paid features under a separate EE license. Forgejo is GPL v3 or later. Forgejo federation is experimental and off by default.
Pick Forgejo for a small team or a homelab VPS. Pick GitLab CE when you want its integrated CI/CD and project management and can give it 8 GB or more of RAM.

The measured numbers

Idle RAM and CPU

Each stack ran alone on the same 8 vCPU host. The numbers are idle averages from docker stats, taken after each stack had run a pipeline, a registry push, a migration and a backup. 100% CPU means one full core.

Stack	Avg RAM	Peak RAM	Avg CPU	Peak CPU
Forgejo 15.0.10 + Postgres 17.11 + runner 13.2.0	285.7 MiB	300.1 MiB	0.57%	0.89%
GitLab CE 19.5.0 default + runner 19.5.0	8,722.6 MiB	8,797.6 MiB	16.50%	87.05%
GitLab CE 19.5.0 memory-constrained (container only)	2,466.5 MiB	2,537.5 MiB	9.29%	74.12%

The constrained row leaves out the runner, so add about 65 MiB to compare it with the others. GitLab's default memory also depends on the server. Per the GitLab Puma docs, it starts one Puma worker per CPU, limited by RAM at about 1 GB each, so a 2 vCPU server starts fewer workers than this 8 vCPU host did.

Inside Forgejo, the server process took about 204 MiB, Postgres about 73 MiB and the idle runner about 8 MiB. GitLab is one container with many services. gitlab-ctl status listed 16 of them, including Puma, Sidekiq, Gitaly, PostgreSQL, Redis, Prometheus, Alertmanager, the registry and several exporters. With default settings, ps inside the container showed ten Ruby processes at roughly 1 GB of resident memory each, and the cgroup reported 8,022 MiB of anonymous memory. The GitLab runner added about 65 MiB.

The default GitLab number is in line with what people report on the GitLab forum. In a 2018 thread, one user who had just installed the gitlab-ce container with a single account and no code saw 8.452 GB in docker stats. The installation requirements set 16 GB and 8 vCPU as the single-node baseline, and at least 8 GB for memory-constrained setups.

The memory-constrained profile comes from the GitLab docs page for small environments, which states that "With some adjustments, GitLab can run comfortably on much lower specifications than described in minimum requirements or the reference architectures." The lab applied the page's Puma, Sidekiq, Prometheus and jemalloc settings, plus the Gitaly spawn limit, but not the Gitaly per-repo concurrency block. On this host that cut the GitLab container's idle RAM by about 72%, and a pipeline still ran green. The same page asks for at least 2 GB of RAM plus 1 GB of swap and warns that functionality and performance can degrade.

Forgejo 17.0.0, released October 15, 2026, idled at 315.3 MiB on the same host. As of October 19, 2026, the 17.0.0 release page advises against upgrading because of an issue that "prevents pushing, merging, or other code operations in some cases," so the rest of this guide uses the 15.0 LTS line.

Install time and steps

	Forgejo 15.0.10	GitLab CE 19.5.0
Images	forgejo 188 MB, postgres 297 MB, runner 46 MB	gitlab-ce 4.07 GB, gitlab-runner 245 MB
Pull time on this host	3 to 7 s per image	53 s for gitlab-ce
`up -d` to ready	5.4 s (`/api/healthz` passes)	145 s (`/users/sign_in` returns 200)
Admin account	`forgejo admin user create`	`GITLAB_ROOT_PASSWORD` on first boot
Runner setup	generate token, register, restart runner	create runner in UI or API, register

Image sizes are the local uncompressed sizes from docker images. GitLab also pulled its helper image, gitlab-runner-helper:x86_64-v19.5.0 (112 MB), on the first job. Switching GitLab to the constrained settings and recreating the container took another 98 seconds before the sign-in page came back.

Install both with Docker Compose

Both stacks below publish ports on 127.0.0.1 only. Put a TLS proxy such as Nginx Proxy Manager in front before anyone else uses them, the same pattern as the Plausible CE guide.

Forgejo with Postgres and a runner

The Forgejo Docker docs start from a single server service and add Postgres as an option. The file below adds Postgres, skips the web installer with INSTALL_LOCK, and adds a runner that waits until it has been registered:

name: fj
services:
  server:
    image: codeberg.org/forgejo/forgejo:15.0.10
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=change-me-db-password
      - FORGEJO__security__INSTALL_LOCK=true
      - FORGEJO__server__ROOT_URL=http://127.0.0.1:3000/
      - FORGEJO__server__SSH_PORT=2222
      - FORGEJO__actions__ENABLED=true
      - FORGEJO__actions__DEFAULT_ACTIONS_URL=https://data.forgejo.org
    restart: unless-stopped
    volumes:
      - fj-data:/data
    ports:
      - "127.0.0.1:3000:3000"
      - "127.0.0.1:2222:22"
    depends_on:
      - db
  db:
    image: postgres:17.11-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=change-me-db-password
      - POSTGRES_DB=forgejo
    volumes:
      - fj-pg:/var/lib/postgresql/data
  runner:
    image: code.forgejo.org/forgejo/runner:13.2.0
    user: "0:0"
    restart: unless-stopped
    command: ["/bin/sh", "-c", "while [ ! -f /data/.runner ]; do sleep 2; done; exec forgejo-runner daemon --config /data/config.yml"]
    volumes:
      - fj-runner:/data
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - server
volumes:
  fj-data:
  fj-pg:
  fj-runner:

FORGEJO__actions__ENABLED=true and the default actions URL match the documented defaults and are written out so the file explains itself. Forgejo publishes no latest tag at all, by design, so pinning a full version like 15.0.10 is the normal path.

Start it, create an admin and register the runner:

docker compose up -d
docker compose exec -u git server forgejo admin user create --admin \
  --username labadmin --email you@example.com --password "$(openssl rand -hex 12)" \
  --must-change-password=false
TOKEN=$(docker compose exec -u git server forgejo actions generate-runner-token | tr -d "\r")
docker compose exec runner sh -c "cd /data && forgejo-runner generate-config > config.yml \
  && sed -i \"s/^  network: .*/  network: fj_default/\" config.yml \
  && forgejo-runner register --no-interactive --instance http://server:3000 \
     --token $TOKEN --name lab-runner --labels docker:docker://alpine:3.24.2"
docker compose restart runner

The network: fj_default line puts job containers on the Compose network so they can reach http://server:3000. The runner mounts the Docker socket, which gives it root-level control of the host. Run it on a separate machine if untrusted people can push workflows.

GitLab CE with a runner

The GitLab Docker install docs ask for an externally reachable hostname and say not to use localhost. The lab mapped gitlab.lab.test to 127.0.0.1 in /etc/hosts and gave the container the same name as a network alias, so the runner and job containers resolve it too:

name: gl
services:
  gitlab:
    image: gitlab/gitlab-ce:19.5.0-ce.0
    hostname: gitlab.lab.test
    restart: unless-stopped
    shm_size: "256m"
    environment:
      GITLAB_ROOT_PASSWORD: ${GITLAB_ROOT_PASSWORD}
      GITLAB_OMNIBUS_CONFIG: |
        external_url "http://gitlab.lab.test:8929"
        registry_external_url "http://gitlab.lab.test:5050"
        gitlab_rails["gitlab_shell_ssh_port"] = 2224
    ports:
      - "127.0.0.1:8929:8929"
      - "127.0.0.1:5050:5050"
      - "127.0.0.1:2224:22"
    volumes:
      - gl-config:/etc/gitlab
      - gl-logs:/var/log/gitlab
      - gl-data:/var/opt/gitlab
    networks:
      default:
        aliases:
          - gitlab.lab.test
  runner:
    image: gitlab/gitlab-runner:alpine-v19.5.0
    restart: unless-stopped
    volumes:
      - gl-runner:/etc/gitlab-runner
      - /var/run/docker.sock:/var/run/docker.sock
volumes:
  gl-config:
  gl-logs:
  gl-data:
  gl-runner:

Put GITLAB_ROOT_PASSWORD= with a long random value in a .env file next to it and run docker compose up -d. Without that variable, GitLab writes a generated password to /etc/gitlab/initial_root_password inside the container and deletes it on the first container restart after 24 hours.

For the constrained run, these lines were appended to GITLAB_OMNIBUS_CONFIG and the container recreated:

# memory-constrained settings from docs.gitlab.com/omnibus/settings/memory_constrained_envs
puma["worker_processes"] = 0
sidekiq["concurrency"] = 10
prometheus_monitoring["enable"] = false
gitlab_rails["env"] = { "MALLOC_CONF" => "dirty_decay_ms:1000,muzzy_decay_ms:1000" }
gitaly["env"] = { "MALLOC_CONF" => "dirty_decay_ms:1000,muzzy_decay_ms:1000", "GITALY_COMMAND_SPAWN_MAX_PARALLEL" => "2" }

Then create an instance runner under Admin, CI/CD, Runners (or with POST /api/v4/user/runners), copy the glrt- token and register:

docker compose exec runner gitlab-runner register --non-interactive \
  --url http://gitlab.lab.test:8929 --token glrt-REPLACE_ME \
  --executor docker --docker-image alpine:3.24.2 --docker-network-mode gl_default

CI, registry, issues and merge requests

GitLab CI and Forgejo Actions

Each instance got a hello-ci repository with the same two-step job on alpine:3.24.2. The GitLab version lives in .gitlab-ci.yml:

hello:
  image: alpine:3.24.2
  script:
    - echo "hello from GitLab CI"
    - cat /etc/alpine-release

The pipeline started on push and passed. The job page reported 4 seconds of run time after 1 second in the queue. With the constrained settings, the API reported 2.93 seconds for a rerun.

Forgejo reads workflows from .forgejo/workflows/, and falls back to .github/workflows/ when that folder is missing:

on: [push]
jobs:
  hello:
    runs-on: docker
    steps:
      - run: echo "hello from Forgejo Actions"
      - run: cat /etc/alpine-release

runs-on: docker matches the label given at registration. The run passed, and the Actions page reported about 1 second for the job.

The syntax looks like GitHub Actions on purpose. The Forgejo Actions docs say: "Forgejo Actions is designed to be familiar to users of GitHub Actions, but it is not designed to be compatible." Expect small edits when you bring workflows over. GitLab CI uses its own YAML format, so moving between the two means a rewrite either way.

Registry, issues and code review

Both ship a container registry. On GitLab it is a separate bundled service that turns on when you set registry_external_url, here on port 5050. The requirements page lists a domain and TLS certificates for it in real use. The lab used plain HTTP on a loopback name, which Docker accepts because it treats 127.0.0.0/8 as an insecure registry by default. For any other address, Docker refuses plain HTTP unless the registry is listed under insecure-registries, so put both registries behind HTTPS before you push from another machine. On Forgejo, the registry is part of the package registry and lives on the main web port, so the image name is 127.0.0.1:3000/labadmin/alpine-copy:3.24.2. Both pushes of the same Alpine image succeeded with the same digest, sha256:7cefa58b..., after a docker login with an access token.

Issues and code review worked the same way on both. An issue, a branch, a commit and a pull or merge request with Closes #1 took a handful of API calls. Both linked the issue and showed the passing pipeline on the review page.

GitLab wraps that core in more DevOps menus. The CE project sidebar in the screenshots groups them under Plan, Code, Build, Secure, Deploy, Operate, Monitor and Analyze. Forgejo keeps the GitHub-style layout: issues, pull requests, projects, packages, wiki and Actions as tabs on the repository.

Migrations, upgrades and backups

Migrating a real repository

Both instances imported https://github.com/plausible/community-edition over HTTPS as plain Git. Forgejo returned from POST /api/v1/repos/migrate in 0.4 seconds with 31 commits and 11,425 KB on disk.

GitLab 19.5.0 refused at first. On a fresh install, import_sources was an empty list, so import by URL was off and the API returned 403. Enabling git and github under Admin, Settings, General, Import and export settings fixed it, but the same request kept returning 403 for about three minutes before it succeeded. After that, the import finished within a few seconds, with the same 31 commits and 11.4 MB.

For a move away from GitLab, the Forgejo migrator can also bring issues, labels, milestones, releases and merge requests when you give it a GitLab access token. The Codeberg migration docs list GitLab among the services with metadata support. Forgejo uses one number space for issues and pull requests, so merge request numbers shift on the way in. Forgejo pull request #1790 offsets them by the highest issue number, and pull request #10077, merged in November 2025, rewrites !N references in comments to match.

Upgrades and backups

GitLab ships a minor release every month on the third Thursday, patch releases twice a month and one major release a year, per its maintenance policy. Security fixes reach the current release and the two before it. Jumps between versions must pass through required upgrade stops. For GitLab 19 those are 19.2, 19.5, 19.8 and 19.11, so the tested 19.5.0 is itself a stop. The Docker upgrade docs say to back up at least the database and the secrets file, upgrade the runner to the same version, change the image tag, then run docker compose pull and docker compose up -d. The upgrade path page says to let background migrations finish before the next stop.

Forgejo releases quarterly, with one LTS a year. The release schedule gives 15.0 LTS support until July 15, 2027, while 16.0 reaches end of life on October 29, 2026. The FAQ says major upgrades need a manual check, which is why the project publishes no latest tag. Inside a line, the 15 and 15.0 tags follow the newest minor and patch release.

For backups, GitLab: docker compose exec gitlab gitlab-backup create ran in 24.6 seconds and wrote a 16.2 MB tar to /var/opt/gitlab/backups/. It ended with a warning that gitlab.rb and gitlab-secrets.json are not in the archive. The warning adds: "You will need these files to restore a backup." Copy both separately.

Forgejo: docker compose exec -u git -w /tmp server forgejo dump --type tar.gz --file /tmp/forgejo-dump.tar.gz ran in 0.4 seconds and wrote a 15.6 MB archive with the repositories, packages, forgejo-db.sql and app.ini. That app.ini holds SECRET_KEY, INTERNAL_TOKEN and JWT_SECRET, so treat the dump file as a secret. Copy either archive off the box and test a restore on a scratch instance.

Licensing, federation and which to pick

Licensing and federation

The GitLab LICENSE file puts the code outside the ee/ directory under the MIT Expat license, with the docs under CC BY-SA 4.0. Code in ee/ falls under the EE license, which allows production use only with a GitLab subscription. The gitlab-ce image is the MIT edition, and the 19.5.0 API reported "enterprise":false.

The Forgejo FAQ says versions 9.0 and later are GPL v3 or later, versions up to 8.0 were MIT, and the project is not AGPL.

Federation through ForgeFed is a stated Forgejo goal. The FAQ says: "Federation is under active development, and is considered experimental." It warns of breaking changes that can burn the domain for future federation. The config cheat sheet defaults [federation] ENABLED to false, and the ActivityPub user endpoint returned 404 on the 17.0.0 lab install. Federated stars were the first user-facing feature, per a FOSDEM 2025 talk. Treat federation as a future feature, not a reason to switch today.

Which one to pick

Pick Forgejo when:

The server is a small VPS, a homelab box or anything with 1 to 4 GB of RAM. The whole stack idled under 300 MiB here.
You want GitHub-style repos, pull requests, packages and Actions with little upkeep, and a quarterly release rhythm with a yearly LTS.
You prefer a copyleft license and a community project whose domains are held by the non-profit Codeberg e.V.

Pick GitLab CE when:

You want one integrated DevOps tool: mature CI/CD with stages, a merge request flow and planning in the same UI.
You can give it 8 GB of RAM or more, or accept the constrained profile and its trade-offs at about 2.4 GiB.
You may want paid EE features later. The memory-constrained docs page says you can always upgrade from CE to EE.

For a solo developer or a small team, Forgejo covers the same daily Git work. On this host it used about a thirtieth of the idle RAM of default GitLab. Add an Uptime Kuma monitor on the login page either way, and if you want push-to-deploy on top, connect the repo to Coolify.

FAQ

Resources and CI

Why does GitLab use so much RAM when idle?

It runs many services in one container, and on this 8 vCPU host the ten Ruby processes held about 1 GB each. A default 19.5.0 container idled at 8,657.7 MiB (about 8.5 GiB) here, close to the 8.452 GB that a user reported on a fresh container in the GitLab forum thread on high RAM usage. The memory-constrained settings brought it to about 2.4 GiB.

Can GitLab run on a 4 GB VPS?

It can start with the constrained profile, which idled at 2,466.5 MiB in this run. GitLab documents 8 GB as the floor for constrained single-node installs and 16 GB as the baseline. In a forum thread about memory after the 17.0 upgrade, a reply calls 4 GB the absolute minimum and recommends 8 GB.

Can Forgejo Actions run GitHub Actions workflows unchanged?

Not always. The Forgejo docs say Actions is designed to be familiar to GitHub users but not designed to be compatible, so expect small edits. Forgejo also falls back to .github/workflows/ when .forgejo/workflows/ is missing.

Migration, licensing and federation

Can you migrate from GitLab to Forgejo with issues and merge requests?

Yes, with a GitLab access token in the migration form. Merge requests become pull requests numbered after the highest issue number, and !N references in comments are rewritten since pull request #10077. Cross-repository references are still tracked in issue #11332.

Is Forgejo licensed under the AGPL?

No. The Forgejo FAQ says GPL v3 or later from version 9.0, MIT up to 8.0, and that switching to AGPL or EUPL was proposed without agreement.

Can Forgejo instances federate with each other yet?

Only experimentally. Federation is off by default, the FAQ calls it experimental, and moderation and access control are still missing. The 2025 FOSDEM talk marked federated stars as done and listed following, comments and pull requests across instances as roadmap items.

Originally published on DeployLark: GitLab CE vs Forgejo: Self-Hosted Git on Docker, Measured

Self-Host Plausible Community Edition with Docker

DeployLark — Mon, 19 Oct 2026 03:30:42 +0000

Plausible Community Edition is a self-hosted, cookie-free analytics stack. The same product family powers Plausible Cloud, and CE is the free, AGPL-licensed release you run yourself. On October 18, 2026, the analytics repository had about 29,500 stars, and the community-edition compose repo had about 2,900. This guide installs CE v3.2.1 from the official Compose files, pins every image tag, puts the dashboard on 127.0.0.1, and confirms a real pageview on a lab site.

The Umami Docker and PostgreSQL guide covers a lighter Postgres-only stack. Plausible CE adds ClickHouse for events and ships a different feature set from Cloud. For a broader app platform on the same VPS, see the Coolify install guide.

TL;DR:

Clone plausible/community-edition at tag v3.2.1, set BASE_URL and a 64-byte SECRET_KEY_BASE in .env, and pin Postgres and ClickHouse to exact tags in compose.override.yml.
Bind the app to 127.0.0.1:8000 and put Nginx Proxy Manager or Caddy in front with HTTPS. Keep BASE_URL equal to the public URL.
Open the dashboard, create the first account, add a site, paste the generated script into the site <head>, and confirm a pageview on the dashboard.
Expect about 2 GB of RAM for a calm ClickHouse setup. CPU needs SSE 4.2 or NEON.
Upgrade by checking out a newer CE tag and running docker compose up -d. Back up Postgres with pg_dump and keep the ClickHouse volumes.

What CE gives you, and what stays on Cloud

Feature and licence differences

The self-hosting docs compare Cloud and CE in one table. The points that matter for a home lab or a small team are:

You own the server: installs, upgrades, backups, capacity and uptime are yours.
CE releases twice a year. Cloud ships features continuously.
Marketing funnels, user journeys, ecommerce revenue goals, SSO and the sites API are Cloud-only.
Bot filtering on CE is the basic User-Agent and referrer-spam path. Cloud adds data-center IP filtering and a broader bot model.
Premium human support is Cloud-only. Self-hosting is community-supported only, per the self-hosting docs.
CE is AGPL-3.0 (or later). Cloud is a paid subscription that funds the project.

If you modify CE and offer it as a network service, AGPL requires you to share the corresponding source with users of that service. Read the licence before you ship a public SaaS on top of CE.

Hardware and CPU requirements

The CE README asks for Docker, Docker Compose, a CPU with SSE 4.2 or NEON (ClickHouse needs it), and at least 2 GB of RAM so ClickHouse and Plausible stay clear of OOM kills. The compose file mounts low-resource ClickHouse settings for small servers. On the lab host used for this guide (8 vCPUs with SSE 4.2, Debian 13), the three containers used about 710 MB of RAM after the first pageviews: about 450 MB for Plausible, 185 MB for ClickHouse and 80 MB for Postgres.

Install the official Compose stack

Clone the repo and set `.env`

The install path is the community-edition repository, not a hand-rolled compose file. Clone a specific tag so the ClickHouse config files match the app:

git clone -b v3.2.1 --single-branch https://github.com/plausible/community-edition plausible-ce
cd plausible-ce

Create .env with the two required variables from the configuration wiki:

touch .env
chmod 600 .env
echo "BASE_URL=https://plausible.example.com" >> .env
echo "SECRET_KEY_BASE=$(openssl rand -base64 48)" >> .env
echo "HTTP_PORT=8000" >> .env

BASE_URL has no default. It drives link generation and WebSocket origin checks. Set it to the URL people will type in the browser, including https:// once a reverse proxy terminates TLS. For a local evaluation, the README tip is BASE_URL=http://localhost:8000 (or any free port). The lab run used http://127.0.0.1:8000.

SECRET_KEY_BASE also has no default. It must be at least 64 bytes. openssl rand -base64 48 produces a 64-character value that meets that rule. Runtime config raises if the key is missing: SECRET_KEY_BASE configuration option is required. A short key fails later with cookie store expects conn.secret_key_base to be at least 64 bytes, which matches discussion #3516 and issue #5612.

Pin image tags and bind to localhost

Upstream compose.yml at v3.2.1 uses ghcr.io/plausible/community-edition:v3.2.1, postgres:16-alpine and clickhouse/clickhouse-server:24.12-alpine. The last two float. On October 18, 2026, those tags resolved to PostgreSQL 16.15 and ClickHouse 24.12.6.70. Put the exact tags in compose.override.yml so future docker compose pull calls stay on known builds, and publish the app only on the loopback address as the reverse-proxy wiki shows:

services:
  plausible_db:
    image: postgres:16.15-alpine
  plausible_events_db:
    image: clickhouse/clickhouse-server:24.12.6.70-alpine
  plausible:
    image: ghcr.io/plausible/community-edition:v3.2.1
    ports:
      - "127.0.0.1:8000:8000"

The override file is the supported place for local changes. It survives git pull of a new CE tag better than editing compose.yml.

The stack looks like this once it is up:

Start it:

docker compose up -d
docker compose ps
curl --head http://127.0.0.1:8000

On a warm host with images already pulled, Postgres and ClickHouse became healthy in under a minute, and /register returned HTTP 200 about 15 seconds after the app container started. An Uptime Kuma HTTP monitor on /login is enough to notice when the dashboard stops answering. The first visit is the registration page:

Create that first account right away. Default registration is invite-only after the first user (DISABLE_REGISTRATION defaults to invite_only in the wiki). The first account owns the instance.

Default database credentials in the compose file are postgres / postgres. Change them for anything exposed beyond a private lab by setting POSTGRES_PASSWORD and a matching DATABASE_URL in .env (see the configuration wiki).

Put HTTPS in front

Reverse proxy layout

From CE 2.1.2 onward, Plausible can request Let's Encrypt certificates itself when HTTP_PORT=80 and HTTPS_PORT=443 are published. Behind an existing proxy, keep HTTP_PORT=8000, bind 127.0.0.1:8000, and terminate TLS on the proxy. That is the layout this guide tested.

A minimal Caddy config from the wiki is:

plausible.example.com {
    reverse_proxy localhost:8000
}

Nginx Proxy Manager works the same way: proxy host to http://127.0.0.1:8000, force SSL, and enable WebSockets so /live/websocket stays up for the live dashboard. The same 127.0.0.1 binding pattern shows up in the Vaultwarden HTTPS guide and the Paperless-ngx Compose guide. The wiki's Nginx sample proxies that path with Upgrade and Connection headers.

Keep BASE_URL on the public hostname

Whatever you pick, BASE_URL must match the public URL. With a wrong host, the dashboard HTML can load while the LiveView WebSocket returns 403. Issue #205 shows the log line Could not check origin for Phoenix.Socket transport when the browser origin and BASE_URL disagree. After you change .env, run docker compose up -d so the container recreates. A plain docker compose restart does not reload env vars.

Add a site and confirm a pageview

Install the tracking script

After registration, the wizard asks for a domain and timezone, then shows a site-specific script. Paste it into the <head> of the site. On CE v3.2.1 the snippet looks like this shape (the pa-… filename is unique per site):

<!-- Privacy-friendly analytics by Plausible -->
<script async src="https://plausible.example.com/js/pa-xxxxxxxx.js"></script>
<script>
  window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};
  plausible.init()
</script>

Optional checkboxes turn on outbound-link, file-download and form-submission measurements. The new script updates those choices from the dashboard. Legacy snippets that used data-domain still work. The script update guide covers migration.

The script's event endpoint is taken from BASE_URL (it posts to {BASE_URL}/api/event). Sites that only allowlist their own analytics host in Content-Security-Policy need that origin in connect-src, or an endpoint override in plausible.init as shown in discussion #6126.

Confirm the first pageview

Open the site in a normal browser and watch the CE dashboard for the domain. The lab run added example.test, served a static page with the generated snippet, and recorded pageviews. After four accepted events, the dashboard showed 4 unique visitors, 4 total pageviews and the / path under Top pages:

Two checks that catch false starts:

The script ignores localhost and 127.0.0.1 by design. The browser console prints Ignoring Event: localhost. That matches community-edition issue #92 and the troubleshooting docs. Test on a real hostname (a /etc/hosts entry is enough in a lab).
A 202 from POST /api/event is not always a stored event. The troubleshooting docs say to look for x-plausible-dropped: 1 when a visit is filtered. The lab posts that used a normal browser User-Agent and an X-Forwarded-For address returned 202 without that header, and ClickHouse held four rows in plausible_events_db.events_v2.

Upgrades and backups

Upgrades

The upgrade wiki recommends pinning a full patch tag such as v3.2.1. Security fixes are not backported, so plan to move forward. v3.2.1 itself is a security release that removes an exposed /storybook endpoint (CVE-2026-8467). General steps for a patch or minor bump:

cd plausible-ce
git fetch origin v3.2.1:v3.2.1
git checkout v3.2.1
# keep your .env and compose.override.yml
docker compose up -d

Read the release notes before every major bump. Some releases change ClickHouse config files in the community-edition repo, which is why the checkout step matters.

Backups

Postgres holds users and site settings. ClickHouse holds events. The Upgrade PostgreSQL wiki shows a pg_dump path that doubles as a backup:

docker compose stop plausible
docker compose exec plausible_db sh -c "pg_dump -U postgres plausible_db > plausible_db.bak"
docker compose cp plausible_db:plausible_db.bak ./plausible_db.bak
docker compose start plausible

Keep copies of the ClickHouse volumes (event-data, and event-logs if you care about server logs) with your volume backup tool. There is no separate CE wiki page that ships a one-line ClickHouse dump. Restoring across major ClickHouse versions needs extra care, so keep the image tag pin in compose.override.yml.

Also back up .env. Losing SECRET_KEY_BASE logs everyone out of the dashboard. Site data in Postgres and ClickHouse stays, as ruslandoga noted when rotating the key.

CE can also send account activation, password resets and optional reports when SMTP or a mail provider adapter is configured. The configuration wiki lists SMTP_HOST_ADDR, MAILER_EMAIL and the Postmark, Mailgun, Mandrill and SendGrid variables. Without SMTP, local accounts still work when ENABLE_EMAIL_VERIFICATION stays at its default false. Those providers were not exercised in the lab run.

FAQ

Setup and resources

How much RAM does Plausible CE need?

The CE README recommends at least 2 GB so ClickHouse and Plausible avoid OOM kills. The lab stack with the bundled low-resource ClickHouse config used about 710 MB of RAM after the first pageviews. Builds and heavy queries need more headroom than idle stats.

Why does the dashboard load but live data stay empty?

BASE_URL usually does not match the URL in the browser. The HTML can still load while /live/websocket fails origin checks. Set BASE_URL to the public URL, then recreate the container with docker compose up -d. See issue #205.

Why is SECRET_KEY_BASE required, and how long must it be?

The configuration wiki requires it and asks for at least 64 bytes. Generate one with openssl rand -base64 48. A missing key stops startup. A short key breaks cookie sessions with cookie store expects conn.secret_key_base to be at least 64 bytes.

Tracking and HTTPS

Why does the browser say "Ignoring Event: localhost"?

The tracker refuses localhost and loopback hosts so local development noise stays out of production stats. Use a real hostname for the test site, or a hosts-file entry that is not localhost. Maintainer replies in issue #92 call out the same console warning.

Which Cloud features are missing from CE?

Per the self-hosting docs: marketing funnels, user journeys, ecommerce revenue goals, SSO and the sites API. Bot filtering is also simpler on CE, and there is no premium support channel.

How do you put HTTPS in front of CE?

Either publish ports 80 and 443 and let CE request certificates, or bind 127.0.0.1:8000 and terminate TLS on Caddy or Nginx Proxy Manager. Keep BASE_URL on the https:// URL in both cases. The reverse-proxy wiki has sample configs.

Originally published on DeployLark: Self-Host Plausible Community Edition with Docker

Fix the Vaultwarden "HTTPS Required" Secure Context Error

DeployLark — Sun, 18 Oct 2026 06:26:16 +0000

If you start Vaultwarden with a plain docker run -p 8000:80 and open it from another machine, you don't get a login page. You get this:

You are not using a secure context which is required for the Subtle Crypto API to work. You need to enable HTTPS!

This isn't a bug, and no Vaultwarden setting turns it off. Lots of people hit it, because Vaultwarden is a very common first self-hosted app. On October 14, 2026, the Vaultwarden repository had about 69,000 GitHub stars, and the vaultwarden/server image had been pulled more than 344 million times from Docker Hub. Below I reproduce the error, explain why it happens, and fix it with a reverse proxy.

TL;DR:

The web vault needs the browser's crypto.subtle API, which only exists in a secure context. Plain HTTP from a LAN IP isn't one.
No Vaultwarden setting turns this off. Put a reverse proxy with a certificate in front. Caddy with reverse_proxy 127.0.0.1:8000 fixed it in my test.
Bind Vaultwarden to 127.0.0.1:8000 and set DOMAIN to the HTTPS URL people will type.
http://localhost loads the page, but current Bitwarden clients require HTTPS, so don't rely on it.
Once your own account exists, set SIGNUPS_ALLOWED to "false".

Reproduce the error

Start Vaultwarden over plain HTTP

This is the "broken" compose file I started with:

services:
  vaultwarden:
    image: vaultwarden/server:1.37.4
    container_name: vaultwarden
    restart: unless-stopped
    volumes:
      - ./vw-data:/data
    ports:
      - "8000:80"

$ docker compose up -d
$ docker logs vaultwarden
|                           Version 1.37.4                           |
[start][INFO] Rocket has launched from http://0.0.0.0:80

I opened it from another machine at http://<your server's LAN IP>:8000/, for example http://192.168.1.50:8000/. In my lab the address happened to be 172.30.0.2. In the browser:

window.isSecureContext = false
typeof crypto.subtle   = "undefined"
Error: Could not instantiate WebCryptoFunctionService. Could not locate Subtle crypto.

What about http://localhost?

Opening http://localhost:8000/ does count as a secure context, and the login page rendered:

But the console logged this right away:

Unable to fetch ServerConfig from http://localhost:8000/api ... Insecure URL not allowed. All URLs must use HTTPS.

That matches what a Vaultwarden contributor wrote in PR #7137: since Bitwarden clients v2025.11.0, the clients require HTTPS everywhere. So treat localhost over HTTP as a quick peek at most, not a working setup. I didn't try to log in or sync that way.

Why Vaultwarden requires HTTPS

Web Crypto only works in a secure context

Bitwarden encrypts your vault in the browser using the Web Crypto API (crypto.subtle). Browsers only expose that API in a "secure context", which means a page served over HTTPS or from localhost. The Vaultwarden wiki says HTTPS is "pretty much required nowadays" for this reason.

Over plain HTTP from a LAN IP, crypto.subtle is simply missing. People have reported this error for years. In 2018 it looked like Cannot read property 'importKey' of null (#153). A more recent report is "Web Vault stuck on loading with Subtle crypto errors" (#5485).

Fix it with a reverse proxy

Run Caddy in front of Vaultwarden

The wiki recommends a reverse proxy and suggests Caddy if you don't already have a preference. Vaultwarden's built-in Rocket TLS (ROCKET_TLS=...) exists, but the wiki advises against it.

Here is what I ran. Vaultwarden now listens only on 127.0.0.1, and DOMAIN is set to the HTTPS URL users will actually type:

services:
  vaultwarden:
    image: vaultwarden/server:1.37.4
    container_name: vaultwarden
    restart: unless-stopped
    environment:
      DOMAIN: "https://vault.example.test"
    volumes:
      - ./vw-data:/data
    ports:
      - "127.0.0.1:8000:80"

Caddyfile:

vault.example.test {
  tls internal
  reverse_proxy 127.0.0.1:8000
}

docker compose up -d
docker run -d --name caddy --restart unless-stopped --network host \
  -v "$PWD/Caddyfile":/etc/caddy/Caddyfile:ro \
  -v caddy_data:/data caddy:2-alpine

This command depends on a few things:

--restart unless-stopped makes Caddy come back after a reboot, like Vaultwarden does. My original test run didn't have it, so add it.
--network host means Caddy binds ports 80 and 443 directly on the host, so nothing else may be using them (sudo ss -tlnp | grep -E ':(80|443) ').
vault.example.test has to resolve to the server. On a test box, add a line like 127.0.0.1 vault.example.test to /etc/hosts. On other client machines, use the server's LAN IP instead. On a real server, create a DNS A or AAAA record for your domain.

The wiki's Using Docker Compose page shows a tidier layout for a real server. It runs Caddy as a second service in the same compose file, proxies to vaultwarden:80 over the compose network, and drops the ports: section from Vaultwarden. I tested the docker run version above, not that one.

tls internal makes Caddy issue a certificate from its own local CA, because my test box has no public domain. On a real server with a real domain, delete the tls internal line. According to Caddy's docs, it then gets a Let's Encrypt certificate automatically, as long as ports 80 and 443 are reachable and DNS points at the server. That path needs a public domain, so I couldn't run it here. The Umami analytics guide shows the same Caddy setup for a real domain.

Here is the difference in one picture:

Check that it works

With the proxy in place, https://vault.example.test was a secure context (isSecureContext = true). Vaultwarden reported the right domain in /api/config:

$ curl -sk https://vault.example.test/api/config   # needs the /etc/hosts entry above
... "vault": "https://vault.example.test" ...

The login page loaded with no crypto errors.

To check the crypto was really working, I created an account. That's the step that needs crypto.subtle, because the client derives keys from your master password before sending anything. The server log showed registration succeeding (timestamps trimmed):

[response][INFO] (register_verification_email) POST /identity/accounts/register/send-verification-email => 200 OK
[response][INFO] (register_finish) POST /identity/accounts/register/finish => 200 OK

My browser was set to ignore the untrusted local CA. With tls internal in real use, you'd need to install Caddy's root certificate on every device, which is exactly the hassle the wiki warns about with self-signed certificates.

Lock down your new HTTPS vault

Turn off open registration

With the fixed compose file above, SIGNUPS_ALLOWED is still at its default, which is true. The whole point of this guide is to put the vault on an HTTPS domain, so anyone who can reach the URL can create an account on your server. Once you've created your own account (and any for family or team members), disable sign-ups:

    environment:
      DOMAIN: "https://vault.example.test"
      SIGNUPS_ALLOWED: "false"

Then apply it with docker compose up -d. To add people later, the .env.template lists SIGNUPS_DOMAINS_WHITELIST for allowing only your email domain, or you can invite them from an organization. If you enable the /admin page to manage users, set a strong ADMIN_TOKEN first, as the wiki's Enabling admin page article explains. I didn't re-test with SIGNUPS_ALLOWED set to false or with the admin page.

Keep the HTTP port private

Don't publish Vaultwarden's plain-HTTP port to the network. In the compose file that's host port 8000 ("127.0.0.1:8000:80"). Keep the 127.0.0.1: prefix so the only way in is through the HTTPS proxy, not http://<server-ip>:8000. Then add an Uptime Kuma monitor for the HTTPS URL, so you hear about a broken certificate before your phone does.

Still seeing the error?

Check the URL and DOMAIN

Make sure you're really on https://. Bookmarks and old browser tabs often still point at http://ip:8000.
Set DOMAIN to the exact HTTPS URL, including any subpath. If you change hostnames later, update DOMAIN too (discussion #7715).

Mobile apps and self-signed certificates

Mobile apps are pickier than browsers. The wiki says the mobile app needs a properly configured certificate chain, including OCSP stapling if you run your own CA. A long-running Android thread (#687) and discussion #7544 both ended up being certificate problems. The browser worked and the app didn't. I didn't test mobile apps.

If you can't use a public domain, follow the wiki's private CA guide instead of a one-off self-signed cert, and install the CA on every client.

FAQ

Running without a public server

Can I use Vaultwarden without HTTPS?

Not in practice. Over plain HTTP from another machine, the web vault won't load at all, as shown above. Over http://localhost the page renders, but current Bitwarden clients refuse non-HTTPS server URLs.

Do I need a domain to run Vaultwarden on my home network?

No, but a domain makes it much easier. The wiki has a guide for a private instance with Let's Encrypt certificates that uses the DNS challenge, so the server never has to be reachable from the internet. It covers a free Duck DNS subdomain or a domain on Cloudflare. Without any domain, you're left with a private CA installed on every device, and the wiki says that method is meant for testing and development only.

Can I use Nginx Proxy Manager instead of Caddy?

You should be able to. Any reverse proxy that serves a valid certificate and passes WebSockets gives the browser its secure context. I tested Caddy only. In Nginx Proxy Manager, a proxy host to port 80 with a Let's Encrypt certificate and Websockets Support turned on should do the job. The Nginx Proxy Manager guide walks through that setup. Per the WebSocket notifications wiki page, WebSockets have run on Vaultwarden's main port since v1.29.0, and v1.31.0 removed the old port 3012. You don't need a separate rule for it.

Clients and accounts

Why can't the Bitwarden mobile app connect to my server?

Usually because of the certificate. The browser may accept a chain that the app rejects. Check that your proxy serves the full chain, and see the mobile apps section above.

Why can people still sign up after I set SIGNUPS_ALLOWED to false?

People ask this often (for example in discussion #4058), and Vaultwarden's own docs explain two causes. First, if you ever saved settings on the admin page, Vaultwarden wrote a config.json, and per the wiki, values in that file take precedence over environment variables. Change the setting on the admin page instead. Second, the .env.template says SIGNUPS_DOMAINS_WHITELIST lets listed domains register even when SIGNUPS_ALLOWED is false.

Originally published on DeployLark: Fix the Vaultwarden "HTTPS Required" Secure Context Error

Uptime Kuma Docker Setup: Install, Alerts and Common Fixes

DeployLark — Sun, 18 Oct 2026 06:21:35 +0000

Uptime Kuma is a self-hosted monitor. It checks your sites and services and tells you when they go down. It's also one of the most popular self-hosted tools around. On October 14, 2026, the GitHub repository had about 92,400 stars, and the louislam/uptime-kuma image had been pulled more than 192 million times from Docker Hub.

This guide is the setup I actually ran, plus the problems that come up again and again in the project's GitHub issues.

TL;DR:

Start louislam/uptime-kuma:2.5.6 with the official compose file. If a reverse proxy goes in front, bind the port to 127.0.0.1:3001, and either way create the admin account right after the first start.
Version 2 asks you to pick a database first. SQLite is the simplest choice for one small instance. Keep ./data on a local disk, not NFS or SMB.
Inside the container, localhost is the container itself. Monitor services on the host through the Docker network gateway IP or host.docker.internal.
A notification only fires for monitors it's attached to, so turn on Default enabled or Apply on all existing monitors.
Behind nginx, pass the Upgrade, Connection and Host headers, or the WebSocket handshake fails with a 400.

Install Uptime Kuma with Docker Compose

Start the container

Make a folder and save the official compose file in it:

mkdir uptime-kuma && cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml

At the time of writing it contains:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.6
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      # <Host Port>:<Container Port>
      - "3001:3001"

Watch that port line. "3001:3001" publishes the port on all interfaces (0.0.0.0), and Docker-published ports bypass ufw and firewalld rules. Until you create the admin account, anyone who can reach port 3001 can open the setup wizard, pick the database and make themselves admin. You have two ways to deal with it:

If you'll put a reverse proxy in front (see the reverse proxy section), change the line to "127.0.0.1:3001:3001" so only the proxy on the same host can reach it.
If you keep the upstream binding, create the admin account right after you start the container.

Start it and check the log:

docker compose up -d
docker compose logs uptime-kuma

Here is the full first-start log from a fresh, empty ./data (colour codes stripped, nothing else removed):

Welcome to Uptime Kuma
Your Node.js version: 22.22.3
2026-10-14T03:55:30Z [SERVER] INFO: Env: production
2026-10-14T03:55:31Z [SERVER] INFO: Uptime Kuma Version: 2.5.6
2026-10-14T03:55:31Z [SERVER] INFO: Loading modules
2026-10-14T03:55:32Z [SERVER] INFO: Creating express and socket.io instance
2026-10-14T03:55:32Z [SERVER] INFO: Server Type: HTTP
2026-10-14T03:55:32Z [SERVER] INFO: Data Dir: ./data/
2026-10-14T03:55:32Z [SETUP-DATABASE] INFO: db-config.json is not found or invalid: ENOENT: no such file or directory, open 'data/db-config.json'
2026-10-14T03:55:32Z [SETUP-DATABASE] INFO: Starting Setup Database
2026-10-14T03:55:32Z [SETUP-DATABASE] INFO: Listening on:
2026-10-14T03:55:32Z [SETUP-DATABASE] INFO: -  http://localhost:3001
2026-10-14T03:55:32Z [SETUP-DATABASE] INFO: -  http://172.17.0.2:3001
2026-10-14T03:55:32Z [SETUP-DATABASE] INFO: Waiting for user action...

The ENOENT ... db-config.json line is expected on a first start, because there's no database config yet. The 172.17.0.2 address is the container's own IP and will differ on your machine.

"Waiting for user action" is normal for version 2. It wants you to pick a database in the browser before it starts properly. Keep ./data on a local disk, not on NFS or an SMB share (see database errors).

Pick a database and create the admin account

Open http://<your-server>:3001. Version 2 asks which database to use: Embedded MariaDB, external MariaDB/MySQL, or SQLite.

I picked SQLite. For a single small instance it's the simplest option, and everything lives in ./data/kuma.db. Setup took about 15 seconds, and then the page asked me to create an admin account:

This guide covers SQLite only. I didn't run the two MariaDB options.

Add a monitor and a notification

Add an HTTP monitor

Click Add New Monitor, keep the type as HTTP(s), and fill in a name and a URL. For testing I ran a throwaway nginx container on port 8081 and used a 20-second interval with Retries set to 0, so I could watch the state change quickly. In production, leave retries at 1 or more, or a single dropped packet will page you.

Then I stopped the nginx container. The next check went red with connect ECONNREFUSED 172.18.0.1:8081:

Watch out for Docker networking here. Inside the container, localhost is the container itself. To monitor something that runs on the host, you need an address that points at the host. 172.18.0.1 is the gateway of my compose project's network, and yours will very likely differ. Docker's default bridge is usually 172.17.0.1, and each compose project gets its own subnet. Find yours with:

docker network inspect uptime-kuma_default --format '{{(index .IPAM.Config 0).Gateway}}'

(uptime-kuma_default is <project folder name>_default.) A more portable option, per Docker's compose reference, is to add this to the service in compose.yaml and use host.docker.internal as the hostname in your monitors and webhooks:

    extra_hosts:
      - "host.docker.internal:host-gateway"

My test used the gateway IP. I didn't repeat it with host.docker.internal.

Attach the notification to your monitors

Go to Settings, then Notifications, then Set Up Notification. There are dozens of providers, such as Telegram, Discord, SMTP and ntfy. To keep the test self-contained, I used the generic Webhook type and pointed it at a small HTTP listener on the host (http://172.18.0.1:9999/kuma, using the gateway IP from above), with Request Body set to application/json.

The Test button worked straight away. My listener got:

{"heartbeat":null,"monitor":null,"msg":"Local webhook Testing"}

This is the part that caught me out. The first time, I saved the notification without turning on Default enabled or Apply on all existing monitors. The test message arrived, but when the monitor went down, nothing was sent. A notification only fires for monitors it's attached to. To fix it, edit the monitor and tick the notification, or re-save the notification with Apply on all existing monitors turned on.

After that, both transitions arrived (trimmed):

{"heartbeat":{"monitorID":1,"status":1,"msg":"200 - OK", ... "retries":0, ...},"monitor":{"name":"demo-site", ...}}
{"heartbeat":{"monitorID":1,"status":0,"msg":"connect ECONNREFUSED 172.18.0.1:8081", ... "retries":1, ...}}

Don't be confused by "retries":1 in the down heartbeat. The monitor's Retries setting really was 0 (I checked the maxretries column in kuma.db). The retries field in the payload is a per-heartbeat failure counter, not the configured setting.

Uptime Kuma sends a notification only when the state changes (up to down, or down to up), not on every failed check. If you want repeat alerts while something stays down, use the resend setting in the monitor form. I left it at 0, which means off.

Put Uptime Kuma behind a reverse proxy

Pass the WebSocket headers

Uptime Kuma's UI talks to the server over Socket.IO. I put nginx in front with a bare proxy_pass and nothing else. On the surface nothing looks wrong. The login page still renders:

But the browser console showed:

WebSocket connection to 'ws://localhost:8090/socket.io/?EIO=4&transport=websocket&sid=...' failed: Error during WebSocket handshake: Unexpected response code: 400

In 2.5.6 the client fell back to HTTP long-polling, so I could still log in. It's slower and less reliable, though. People with more monitors or stricter proxies end up with the "Cannot connect to the socket server" reload loop described in #3884 and #958. This is the full nginx server block that fixed the 400 in my test (plain HTTP on port 8091, because the lab had no domain):

server {
  listen 8091;
  location / {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

On a real server, put the location / { ... } part inside your existing TLS server block (the one with listen 443 ssl;, server_name status.example.com; and your ssl_certificate lines) instead of using listen 8091. I tested only the plain-HTTP block above. If you proxy other apps from the same nginx, the common pattern is a map $http_upgrade $connection_upgrade { default upgrade; '' close; } block in the http context and proxy_set_header Connection $connection_upgrade;. With a proxy in front, also bind the container to 127.0.0.1:3001 as described above.

Prefer a web UI to nginx config files? The Nginx Proxy Manager guide covers the same job, including the Websockets Support toggle this case needs. The Vaultwarden HTTPS guide and the Umami analytics guide use the same 127.0.0.1 binding behind Caddy, and both make good first monitors.

Forward the Host header

proxy_set_header Host $host matters too. Since 1.23.9, Uptime Kuma checks that the WebSocket Origin matches the Host. In #4210, the maintainer's recommended fix is to forward the original Host header (ProxyPreserveHost on for Apache). Setting UPTIME_KUMA_WS_ORIGIN_CHECK=bypass also makes the error go away, but he says plainly that it's "not a good idea, since it is a part of security fix." I didn't reproduce the origin-mismatch error itself, because the 2.5.6 client fell back to polling instead.

Fix common Uptime Kuma errors

Container and port errors

"Bind for 0.0.0.0:3001 failed: port is already allocated"

I reproduced this by starting a second copy:

docker: Error response from daemon: driver failed programming external connectivity on endpoint kuma-second (...): Bind for 0.0.0.0:3001 failed: port is already allocated.

Another container or process already has port 3001. Either stop it (docker ps shows what's using it) or change the host side of the mapping, for example "3002:3001".

Permission denied on `/app/data`

Reports like #4370 (EACCES: permission denied, mkdir 'data/upload') come from bind-mounting a folder the container user can't write to, often on NAS shares or in rootless setups. The usual fix is to make sure the folder exists and is writable, or to use a named volume. I didn't hit this with the default compose file running as root.

Database and network errors

Data on NFS or network shares, "database is locked"

Keep the SQLite file off NFS. In #2668 a collaborator points to SQLite's own "How To Corrupt" page, and the wiki now says network filesystems aren't supported. Use a local volume.

If you see SQLITE_BUSY: database is locked after upgrading to 2.2.0 or later, read #7289. According to that thread, the maintainer added UPTIME_KUMA_SQLITE_SINGLE_CONNECTION=true in 2.3.0 to bring back the older single-connection behaviour, and slow storage (the thread mentions eMMC) makes the problem worse. I didn't hit SQLITE_BUSY on my test box.

Lots of "timeout of 48000ms exceeded" while the site is up

This is one of the most-commented issues (#275, 100+ comments). In several reports the cause was DNS on the Uptime Kuma host, not the target. One commenter fixed it by pointing the container straight at a local DNS server, and a maintainer replied that a DNS cache was worth adding. Retries also help, because one slow lookup then won't flip the monitor to down.

Upgrade from Uptime Kuma 1.x

Back up before you change the tag

If you're on louislam/uptime-kuma:1, read the v2.0 release notes before changing the tag. Per those notes, the first start runs a data migration that can take a long time on big databases. Back up ./data first. With SQLite, stop the container so the database file isn't being written while you copy it:

docker compose stop
tar czf kuma-backup-$(date +%F).tgz data
docker compose start

To restore, stop the container and extract the archive in place of ./data. This article doesn't walk through a full 1.x to 2.x migration, and I didn't restore from this backup.

FAQ

Access and setup

How do I reset a forgotten Uptime Kuma password?

Run the reset tool inside the container. The wiki documents the interactive version, npm run reset-password, which asks for the new password twice. With this compose file that's docker compose exec uptime-kuma npm run reset-password. I tested the non-interactive form on 2.5.6, npm run reset-password -- --new-password='...', and it printed "Password reset successfully." The underscore spelling --new_password from older examples failed with "readline was closed". The password can end up in your shell history this way, and the tool warns you about it.

Why does Uptime Kuma show ECONNREFUSED for a service on localhost?

Because localhost inside the container is Uptime Kuma itself, as the reporter in #4517 worked out. Use the Docker gateway IP or host.docker.internal, as shown in the monitor section.

Does Uptime Kuma support PostgreSQL?

Not as of 2.5.6. The setup screen offers Embedded MariaDB, external MariaDB/MySQL and SQLite. PostgreSQL support is still an open feature request (#959).

Alerts and automation

Why do test notifications work but down alerts never arrive?

In my test, the cause was a notification that wasn't attached to the monitor. Edit the monitor and tick the notification, or re-save the notification with Apply on all existing monitors. Also check that the notification service was reachable when the monitor went down. In #6046, a user found that Uptime Kuma doesn't retry a notification if the service is unreachable at that moment, so that alert is simply lost.

Can Uptime Kuma monitor Docker containers?

Yes, with the Docker Container monitor type. The wiki says to mount /var/run/docker.sock into the container, and warns that this gives Uptime Kuma full control over the Docker daemon. It recommends against exposing Uptime Kuma to the internet when you use it. A socket proxy that allows only read access is a common alternative (#4783). I didn't test this monitor type.

Does Uptime Kuma have an API?

Not an official REST API. The feature request (#118) is still open, and in March 2026 a collaborator pointed people to the internal Socket.IO API and third-party wrappers instead. If you build on either, expect changes between releases.

Originally published on DeployLark: Uptime Kuma Docker Setup: Install, Alerts and Common Fixes

Stirling-PDF Docker Setup: Login, OCR Languages and Updates

DeployLark — Sun, 18 Oct 2026 06:16:14 +0000

Stirling-PDF is a self-hosted toolbox for PDFs. Merge, split, compress, sign, redact, convert and OCR run on your own server, so the files never go to an online PDF site. On October 17, 2026, the GitHub repository had about 94,300 stars, and the stirlingtools/stirling-pdf image had about 16.3 million pulls on Docker Hub, plus 22.5 million under the older frooodle/s-pdf name, which still gets new releases.

This guide runs Stirling-PDF 3.2.0 with Docker Compose and fixes the parts the quick start leaves to you. The default login is shown on the login page to anyone who opens it, extra OCR languages need a volume, and uploads through nginx fail above 1 MB until you change one setting. I ran every step on a Debian 13 test server with Docker 29.9.1, OCR'd scans I generated in English and Spanish, and upgraded a second install from 3.1.0 to 3.2.0.

TL;DR:

Use the official compose file with a pinned tag such as docker.stirlingpdf.com/stirlingtools/stirling-pdf:3.2.0, publish the port on 127.0.0.1:8080, and keep mem_limit: 4g.
A fresh install creates admin with the password stirling and prints both on the login page. Set SECURITY_INITIALLOGIN_USERNAME and SECURITY_INITIALLOGIN_PASSWORD before the first start, or log in and change the password right away.
The standard image can OCR English, German, French, Portuguese and Simplified Chinese. For any other language, put its .traineddata file in the folder mounted at /usr/share/tessdata and restart.
Behind nginx, set client_max_body_size 2000M. To update, change the tag, then run docker compose pull and docker compose up -d.

What Stirling-PDF runs and which image to pick

What's in the container

Stirling-PDF is one container. It holds a Java web app plus the command-line tools that do the heavy work. The diagram shows the setup this guide builds:

The 3.2.0 container logs its tool versions at startup. Mine listed OpenJDK 25.0.4, OCRmyPDF 17.13.0, Tesseract 5.3.4, LibreOffice 26.2.6.3, Ghostscript 10.08.0, qpdf 12.4.2 and calibre 9.15.0. LibreOffice doesn't start until the first Office conversion, so it uses no memory until you need it. One feature is off out of the box. The log said Missing dependency: rar - Disabling group: rar (Affected features: PDF To Cbr), which matches the docs.

Settings, the user database and generated keys go in /configs. On first start the app also creates credential-encryption.key there and logs a warning to back it up, because losing it makes stored integration secrets unrecoverable.

Standard, fat or ultra-lite

The Docker install docs list three images:

Tag	Login	What's included	Suggested memory
`3.2.0`	Yes	OCR plus Office, HTML and ebook conversion	4 GB
`3.2.0-fat`	Yes	The same plus a bundled AI engine, off until you turn it on	6 GB
`3.2.0-ultra-lite`	No	Core PDF tools only, no OCR or conversions	2 GB

Use the standard image. It's the one I tested end to end. The compressed download on Docker Hub was 1.17 GB for 3.2.0 and 394 MB for 3.2.0-ultra-lite. On disk they took 3.58 GB and 1.04 GB.

Ultra-lite is lighter, and my test showed what you give up. It used 357 MiB of RAM after starting, against 795 MiB to 1.08 GiB for the standard image. But it has no login at all. The browser went straight to the editor, API calls worked without credentials, and the OCR endpoint answered 403 This endpoint is disabled. Only run it on a network you trust.

The docs use latest in their examples, but latest moves with every release. Pin a version tag instead. All three tags above exist on docker.stirlingpdf.com, Docker Hub and ghcr.io.

Docker Compose setup

The compose file

This is the compose file from the install docs with three changes. The tag is pinned to the version I tested, the port listens on 127.0.0.1 only, and the first admin account comes from a .env file. Create the folder and the .env first:

mkdir -p ~/stirling-pdf/stirling-data/tessdata && cd ~/stirling-pdf
umask 077
cat > .env <<EOF
SECURITY_INITIALLOGIN_USERNAME=pdfadmin
SECURITY_INITIALLOGIN_PASSWORD=$(openssl rand -base64 18 | tr -d '/+=')
EOF
umask 022
cat .env

umask 077 makes .env readable only by you. Save the generated password in your password manager. Then save this as compose.yaml:

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:3.2.0
    container_name: stirling-pdf
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      SECURITY_INITIALLOGIN_USERNAME: ${SECURITY_INITIALLOGIN_USERNAME}
      SECURITY_INITIALLOGIN_PASSWORD: ${SECURITY_INITIALLOGIN_PASSWORD}
    volumes:
      - ./stirling-data/configs:/configs
      - ./stirling-data/logs:/logs
      - ./stirling-data/customFiles:/customFiles
      - ./stirling-data/pipeline:/pipeline
      - ./stirling-data/storage:/storage
      - ./stirling-data/tessdata:/usr/share/tessdata
    mem_limit: 4g
    restart: unless-stopped

Keep mem_limit. The image sizes the Java heap from it. My container logged Detected container memory: 4096MB and let Java use up to 70% of that. Without a limit, the server FAQ says the heap is sized from the host's RAM, which is why people see Stirling-PDF use a lot of memory while idle.

The mkdir creates the tessdata folder in advance on purpose. When I let Docker create it, the folder belonged to root, so I needed sudo to copy language files in later. The other folders ended up owned by UID 1000, the user the container runs as. If your files belong to a different user, the install docs say to set PUID and PGID.

First start

docker compose pull
docker compose up -d
curl -s http://127.0.0.1:8080/api/v1/info/status

The pull took 17 seconds on my server. About 19 seconds after up -d, the status endpoint answered:

{"version":"3.2.0","status":"UP"}

That endpoint needs no login, so it's a good target for an Uptime Kuma HTTP monitor. Port 8080 now only answers on the server itself. To use the web UI from your computer, open an SSH tunnel with ssh -L 8080:127.0.0.1:8080 you@your-server and browse to http://localhost:8080, or put a reverse proxy in front (see below).

Lock down the default login

What a fresh install shows

Login is on by default in the standard image. When I started a fresh install without the .env variables, the log said Default admin user created: admin, and the login page showed this to every visitor:

The page prints the password, so anyone who reaches it before you change it can log in as admin. Upstream's compose file publishes '8080:8080' on every interface, and Docker's published ports skip ufw rules, so a host firewall won't save you. That's the reason for the 127.0.0.1 binding.

Logging in as admin with stirling first asked whether to send anonymous usage data, then forced a new password:

After the change, Stirling-PDF logged me out, and the credentials box was gone from the login page. The sign-in docs add that an account locks for 120 minutes after 5 failed attempts.

Set your own first admin

The .env approach above skips all of that. On a fresh 3.1.0 install with SECURITY_INITIALLOGIN_USERNAME=pdfadmin, the log said Admin user created: pdfadmin. The login page had no credentials box, logging in went straight to the editor with no password prompt, and admin with stirling got a 401. The docs say both variables are ignored once the database has users, so changing them later does nothing. Change the password in the app instead.

Don't turn login off unless only you can reach the server. The server overview puts it plainly for SECURITY_ENABLELOGIN=false: "Anyone who can reach the server can then use it." With login on, the API is protected too. A POST to /api/v1/misc/ocr-pdf without credentials got a 401. The API description at /v1/api-docs and the Swagger page answered 200 without login, but they only describe the endpoints.

Add OCR languages

What's bundled, and what a missing language looks like

The standard image ships Tesseract data for Simplified Chinese, English, French, German and Portuguese. tesseract --list-langs in my container showed chi_sim, deu, eng, fra, osd and por. The ultra-lite image has no OCR.

I generated an image-only scan of an English invoice and OCR'd it through the API in 2.2 seconds. The invoice number, date and amounts came back right. Then I tried a scanned Spanish letter. Asking for Spanish before it was installed got an error:

HTTP 400 {"detail":"Invalid OCR languages format: none of the selected languages are valid", ... "errorCode":"E041"}

Per the docs, the web UI only lists installed languages. Running the Spanish letter with English worked, but every accent was gone, and "señora Núñez" became "sefiora Niifiez".

Add a language with the tessdata volume

The OCR languages docs describe two ways. The in-app download under Settings, Server, Advanced puts files inside the container, so they disappear when the container is recreated. The volume survives that. Download the .traineddata file from tesseract-ocr/tessdata (larger, more accurate) or tessdata_fast (smaller, faster) and restart:

cd ~/stirling-pdf
curl -fL -o stirling-data/tessdata/spa.traineddata \
  https://github.com/tesseract-ocr/tessdata/raw/main/spa.traineddata
docker compose restart
docker exec stirling-pdf tesseract --list-langs

The file was 18 MB. At startup, the log said Found user-mounted tessdata in /usr/share/tessdata, copying to /usr/share/tesseract-ocr/5/tessdata, and spa joined the list. Spanish then showed up in the OCR tool:

Here's what the two runs stored for the same scan:

With spa, the accents and the ñ came out right, but three words were still wrong. OCR on a noisy scan isn't perfect in any language, so check important documents. If you want every scan OCR'd and filed automatically, Paperless-ngx uses the same OCRmyPDF and Tesseract tools on each document it imports. Stirling-PDF fits one-off jobs better.

The volume path is the most common mistake. In a GitHub issue where a user had mounted language files at /data/tessdata, maintainer Frooodle answered: "Your path is wrong, all our docs show it as /usr/share/tessdata". The docs add that files already in Tesseract's folder aren't replaced, and that eng.traineddata must stay, because English is always needed.

Reverse proxy, updates and backups

Big uploads behind nginx

For HTTPS, put Stirling-PDF behind a reverse proxy that forwards to 127.0.0.1:8080. Nginx Proxy Manager does that with a free certificate, and the Umami guide shows the same 127.0.0.1 pattern behind Caddy.

With nginx, check the upload size first. nginx accepts 1 MB request bodies by default, and PDFs are often bigger. I sent a 2.6 MB four-page scan through nginx 1.30.6 with a plain proxy_pass and got 413 Request Entity Too Large. The nginx log said client intended to send too large body: 2602334 bytes. The production checklist has the settings that fixed it:

server {
    # listen 443 ssl, server_name and certificates as usual
    client_max_body_size 2000M;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_buffering off;
        proxy_read_timeout 1800s;
        proxy_send_timeout 1800s;
    }
}

The same request then returned 200 in 2.2 seconds with all four pages OCR'd. 2000 MB matches Stirling-PDF's own default upload limit. The long timeouts and proxy_buffering off are for slow jobs. Nginx Proxy Manager already sets client_max_body_size 2000m in the main nginx.conf of its 2.16.0 image, so this limit mostly bites hand-written nginx configs. The checklist also says to set SYSTEM_FRONTENDURL to your public address, because invite emails and share links use it.

Update and back up

Back up before you update. The production checklist names the folders. configs holds settings, keys and the built-in database, which also writes a nightly backup to configs/backup/db/. storage holds files users saved on the server. A tarball is enough:

cd ~/stirling-pdf
sudo tar czf stirling-backup-$(date +%F).tgz stirling-data/configs stirling-data/storage

Then change the tag and recreate the container. I tested this on a second install that started on 3.1.0 with its own admin account:

sed -i 's/stirling-pdf:3.1.0/stirling-pdf:3.2.0/' compose.yaml
docker compose pull
docker compose up -d
curl -s http://127.0.0.1:8080/api/v1/info/status

22 seconds later the status said 3.2.0, and the admin from the first start could still log in. Read the release notes before each bump. Releases come fast: 3.0.0 came out on September 24, 2026, 3.1.0 on October 5 and 3.2.0 on October 15. Coming from V1, read the upgrade guide the install docs link to first. If you'd rather deploy from a dashboard, the same compose file works as a Docker Compose resource in Coolify.

FAQ

Login and access

What is the default username and password for Stirling-PDF?

admin and stirling. A fresh standard image creates that account and shows it on the login page until you change the password, which the first login forces. To skip the default account, set SECURITY_INITIALLOGIN_USERNAME and SECURITY_INITIALLOGIN_PASSWORD before the first start. They only apply while the user database is empty.

Can I run Stirling-PDF without a login?

Yes. Set SECURITY_ENABLELOGIN=false, or use the ultra-lite image, which has no login at all. Then anyone who can reach the port can use every tool and the API, as my ultra-lite test showed. Keep it on 127.0.0.1 or a private network if you do this.

Is Stirling-PDF free to self-host?

Yes. The repository is MIT licensed, with some folders, such as the proprietary and SaaS code, under their own licenses. Per the plans page, a self-hosted server runs on the Free plan, with all PDF tools, the REST API and OAuth2 single sign-on, for up to 5 users. Team and Enterprise add more users and features like an external database.

OCR and performance

Why doesn't my OCR language show up in Stirling-PDF?

The .traineddata file isn't where the app looks. Mount your folder at /usr/share/tessdata inside the container, restart, and check with docker exec stirling-pdf tesseract --list-langs. If the API returns Invalid OCR languages format, the language you asked for isn't installed.

Why does Stirling-PDF use so much RAM?

Java sizes its heap from the memory it sees. Set mem_limit in compose or --memory with docker run. With a 4 GB limit, my standard container used between 795 MiB and 1.08 GiB while idle. If that's too much and you don't need OCR or conversions, ultra-lite used 357 MiB.

Why do large uploads fail behind a reverse proxy?

The proxy is rejecting the upload. nginx allows 1 MB by default and returned 413 Request Entity Too Large for my 2.6 MB scan. Set client_max_body_size 2000M in the server block and reload nginx. Nginx Proxy Manager already allows 2000 MB.

Originally published on DeployLark: Stirling-PDF Docker Setup: Login, OCR Languages and Updates

How to Self-Host Umami Analytics with Docker and PostgreSQL

DeployLark — Sun, 18 Oct 2026 06:10:53 +0000

Umami is a small, privacy-friendly alternative to Google Analytics. You can run it yourself with two containers: the app and a PostgreSQL database. It has a big following among self-hosters. On October 14, 2026, the Umami repository had about 39,400 GitHub stars.

PostgreSQL is the database to use. When a user tried Umami 3 on MySQL in #3859, maintainer Mike Cao answered: "v3 does not run on MySQL".

TL;DR:

Run ghcr.io/umami-software/umami:3.4.0 with postgres:15.19-alpine. Umami v3 doesn't run on MySQL.
Put POSTGRES_PASSWORD, APP_SECRET and TWO_FACTOR_ENCRYPTION_KEY in a .env file. Choose the database password once, because changing it later breaks the app.
Bind the port to 127.0.0.1:3000 and put Caddy in front for HTTPS.
The default login is admin / umami. Change the password before you do anything else, then add your website and paste the tracking script into your site's <head>.

Prepare the secrets and the compose file

Create the secrets

Don't use the placeholder passwords from the example file. Put real ones in a .env file next to the compose file:

mkdir umami && cd umami
cat > .env <<EOF
POSTGRES_PASSWORD=$(openssl rand -hex 16)
APP_SECRET=$(openssl rand -hex 32)
TWO_FACTOR_ENCRYPTION_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

chmod 600 keeps the secrets readable only by your user. The values are hex on purpose. Hex has no quotes, $ or @ characters that could break the DATABASE_URL or a shell command later.

Choose POSTGRES_PASSWORD once and keep it. Changing it later breaks the app (see the 28P01 error).

TWO_FACTOR_ENCRYPTION_KEY is newer. Older guides leave it out, and people who then turned on 2FA found their instance blocked by "TWO_FACTOR_ENCRYPTION_KEY is missing or invalid" (#4443). Set it from the start.

Write the compose file

This is the official docker-compose.yml with the hard-coded secrets replaced by values from .env, and one more change: the port is bound to 127.0.0.1.

services:
  umami:
    image: ghcr.io/umami-software/umami:3.4.0
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:${POSTGRES_PASSWORD}@db:5432/umami
      APP_SECRET: ${APP_SECRET}
      TWO_FACTOR_ENCRYPTION_KEY: ${TWO_FACTOR_ENCRYPTION_KEY}
    depends_on:
      db:
        condition: service_healthy
    init: true
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "curl http://localhost:3000/api/heartbeat"]
      interval: 5s
      timeout: 5s
      retries: 5
  db:
    image: postgres:15.19-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  umami-db-data:

Why 127.0.0.1:3000:3000? Upstream publishes "3000:3000", which listens on all interfaces, and Docker-published ports bypass ufw. Umami starts with a default admin / umami login, so until you change it, anyone who can reach port 3000 could log in as admin. Binding to localhost means only the reverse proxy on the same host can reach it.

Here's what I tested with that binding. I did a first start on a fresh volume with the port bound to 127.0.0.1:3900. The migrations ran, the heartbeat answered on 127.0.0.1, and the port didn't answer on the host's network address. The logs matched the excerpt below. The later steps (logging in, adding a website and tracking a view) ran on upstream's "3000:3000" binding, not the localhost one. If you keep upstream's binding, change the password before the port is reachable from outside.

This is the capture from that run, trimmed. The … lines mark removed output, and the last two lines are my notes on the two curl results:

The healthcheck is upstream's, so I kept it. Note that curl without -f exits 0 even on an HTTP 500, so it only catches a dead process. With curl -f http://localhost:3000/api/heartbeat, errors would count too. If you have a large existing database, also give migrations more time before the healthcheck gives up, for example with start_period: 300s or more retries (see the check-db error below). I didn't test either change.

If you plan to upgrade on purpose rather than whenever latest moves, pin a version tag instead of latest.

Start Umami and log in

Run the first start

docker compose up -d
docker compose logs -f umami

On the first start, Umami creates the database schema itself. Here's an excerpt from my log on a fresh, empty volume (the umami-1 | prefixes and the long list of migration folders removed):

✓ DATABASE_URL is defined.
✓ Database connection successful.
✓ Database version check successful.
26 migrations found in prisma/migrations
Applying migration `01_init`
...
Applying migration `26_add_api_key`
All migrations have been successfully applied.
✓ Database is up to date.
▲ Next.js 16.3.4
- Local:         http://localhost:3000
- Network:       http://0.0.0.0:3000
✓ Ready in 0ms

On later restarts you'll see No pending migrations to apply. instead of the Applying migration lines.

The heartbeat endpoint is a quick way to check it's up. It also makes a good target for an Uptime Kuma monitor:

$ curl localhost:3000/api/heartbeat
{"ok":true}

Change the default password

With the localhost binding, open http://localhost:3000 on the server itself. You can also tunnel it from your laptop with ssh -L 3000:127.0.0.1:3000 you@server and open http://localhost:3000 there, or set up the HTTPS proxy below first and log in through it. The default login is admin / umami.

Change the password before you do anything else. The easy way is the dashboard, under Settings, then Profile. I did it through the API, which works the same way. It needs jq (sudo apt install jq):

TOKEN=$(curl -s localhost:3000/api/auth/login -H 'content-type: application/json' \
  -d '{"username":"admin","password":"umami"}' | jq -r .token)
curl -s localhost:3000/api/me/password -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"currentPassword":"umami","newPassword":"<new password>"}'

That returned 200, and after that admin / umami got 401 incorrect-username-password.

Add your website and HTTPS

Add the tracking script

In the dashboard, go to Settings, then Websites, then Add website. I used the API instead (POST /api/websites with {"name":"Test site","domain":"localhost"}). Umami gives you a website ID.

Put the script in your site's <head>:

<script defer src="https://analytics.example.com/script.js"
        data-website-id="a91472cb-2673-40ad-8940-7a865af4701d"></script>

I served a test page with that tag from a second container and visited it. The beacon request went to /api/send and the view showed up on the dashboard:

Put Caddy in front for HTTPS

The script tag above uses https://analytics.example.com, and on a real site it has to be HTTPS, because an HTTPS page won't load a script from http://. The simplest way is Caddy on the same host. Per Caddy's docs, it gets a Let's Encrypt certificate automatically. Point a DNS A or AAAA record for analytics.example.com at your server, make sure ports 80 and 443 are open, and use this Caddyfile (/etc/caddy/Caddyfile for the Debian package):

analytics.example.com {
    reverse_proxy 127.0.0.1:3000
}

Then run sudo systemctl reload caddy. This is why the compose file binds Umami to 127.0.0.1. Caddy connects locally, and the outside world only sees HTTPS. I ran my tests over plain HTTP on localhost with no public domain, so this step follows Caddy's docs rather than my lab. The Vaultwarden HTTPS guide shows a tested Caddy setup with a local certificate, and the Nginx Proxy Manager guide covers a web-UI alternative.

Fix common Umami errors

Tracking errors

Page views don't appear, but `/api/send` returns 200

This one cost me some time. My first test visit came from a headless browser. /api/send answered 200 OK with this body:

{"beep":"boop"}

Nothing was saved. Umami runs every request through the isbot library and silently drops anything that looks like a bot. A headless Chrome user agent counts as one. Here's the check in src/app/api/send/route.ts:

if (!process.env.DISABLE_BOT_CHECK && isbot(userAgent)) {
  return json({ beep: 'boop' });
}

The same page loaded with a normal Chrome user agent was recorded straight away. If you test with curl, Playwright or an uptime checker, you'll see nothing. That's working as designed. DISABLE_BOT_CHECK exists if you really need it.

Database errors

`password authentication failed for user "umami"` (28P01) after changing the password

I reproduced this on purpose. I changed POSTGRES_PASSWORD in .env and ran docker compose up -d again. Umami went into a restart loop:

✓ DATABASE_URL is defined.
✓ Database connection successful.
✗
Invalid `prisma.$queryRaw()` invocation:
Raw query failed. Code: `28P01`. Message: `password authentication failed for user "umami"`

Yes, it prints "Database connection successful" right before failing. Don't let that fool you.

The reason is that the Postgres image only reads POSTGRES_PASSWORD when it creates an empty data volume. After that, the password is stored in the database, and changing the env var does nothing. To fix it, set the database password to match the new value:

docker compose exec db psql -U umami -d umami \
  -c "ALTER USER umami WITH PASSWORD '<new password from .env>';"
docker compose restart umami

Keep the password in single quotes inside the SQL. That's how PostgreSQL marks a string literal. If you generated it with openssl rand -hex as shown earlier, it's only 0-9a-f, so there's nothing to escape.

After that, the app container was healthy again and /api/heartbeat returned {"ok":true}. If you get Prisma errors like P1000 even though the credentials look right, also read #4459. There, a collaborator traced one case back to 2FA being enabled without TWO_FACTOR_ENCRYPTION_KEY.

`ERROR: "check-db" exited with 1` after an upgrade

On upgrades, Umami runs database migrations at startup. In #3408 (2.17 to 2.18), a migration on a large table took more than 15 minutes. Meanwhile the compose healthcheck (5 s × 5 retries) marked the container unhealthy and restarted it partway through. If you have a lot of data, back up first, watch the logs, and don't restart while migrations are running. My test database was empty, so I didn't see this myself.

Prisma `P3009` (failed migration)

If a migration was interrupted, Umami refuses to start with P3009 (#2645, 58 comments). The collaborator's advice is to look in the _prisma_migrations table to see which migration failed. If its changes are actually in place, mark it as applied, for example with npx prisma migrate resolve --applied "<migration name>". Use the name of your own failed migration from _prisma_migrations. 05_add_visit_id was the one in that v2-era thread and is only an example. I haven't checked whether npx prisma is available in the v3 runtime image, so you may need to run it from a checkout of the Umami source instead.

`relation "account" does not exist` in the Postgres log

On a fresh database you may see this in the Postgres log. A collaborator explained in #2145 that it comes from the startup check probing for an old table, and it's harmless if Umami starts normally.

Managed Postgres that requires SSL

Hosted databases often reject connections without encryption ("no pg_hba.conf entry ... no encryption", #3687). The usual fix is to add ?sslmode=require to DATABASE_URL. I used a local container, so I didn't run this case.

FAQ

Setup

What is the default Umami username and password?

It's admin / umami, per the install docs, and that's what my fresh install accepted. Change it right after the first login. Users have asked for a way to set it with environment variables instead (#4083).

Can I use MySQL with Umami v3?

No. The maintainer confirmed in #3859 that v3 doesn't run on MySQL. Use PostgreSQL, as in this guide.

Tracking

Why isn't Umami tracking page views after I added the script?

Questions like this discussion come up often. First check the bot filter described above. Visits from headless browsers and test tools are dropped while /api/send still returns 200. Then check that the data-website-id matches the website in your dashboard, and that the script loads over HTTPS on an HTTPS site.

How do I stop ad blockers from blocking Umami?

The Umami docs give two environment variables for self-hosted instances. TRACKER_SCRIPT_NAME renames script.js (for example to x.js), and COLLECT_API_ENDPOINT renames /api/send (for example to /api/x). This is a common complaint, as in #726 about Brave. I didn't test ad blockers.

How do I exclude my own visits?

Per the docs, open your site, open the browser console and run localStorage.setItem('umami.disabled', 1);. The setting is per website, so repeat it on each site you track. localStorage.removeItem('umami.disabled'); turns tracking back on. People ask about this in discussion #2305, and I didn't test it.

Originally published on DeployLark: How to Self-Host Umami Analytics with Docker and PostgreSQL

Paperless-ngx Docker Compose Setup with OCR

DeployLark — Sun, 18 Oct 2026 06:05:31 +0000

Paperless-ngx turns a pile of paper into a searchable archive. You scan a letter or drop a PDF into a folder, and Paperless runs OCR on it, stores the original plus a searchable PDF/A copy, and makes every word findable. It's one of the most popular self-hosted apps. On October 15, 2026, the GitHub repository had about 46,700 stars, and the paperlessngx/paperless-ngx image had been pulled about 38 million times from Docker Hub. That figure leaves out GitHub's registry, which the official compose files use by default.

The official compose files get you running, but they leave three traps for a new install. They ship a placeholder secret key that v3 refuses to start with, they publish the web UI on every interface before you've created the admin account, and they say little about OCR languages, which decide whether "Müller" ends up in your archive as "Muller". This guide fixes all three. I ran every step below on a test box with Paperless-ngx 3.3.1, OCR'd scans I generated in English, German and Polish, imported a Word file and an email attachment, then tested a backup and an upgrade.

TL;DR:

Start from the official docker-compose.postgres-tika.yml, pin every image tag, bind the port to 127.0.0.1:8000, and put a random PAPERLESS_SECRET_KEY and database password in a .env file.
Open the web UI right away. The first account you sign up with becomes the superuser.
PAPERLESS_OCR_LANGUAGE picks the OCR languages (deu+eng). PAPERLESS_OCR_LANGUAGES installs extra ones (pol). English, German, French, Italian and Spanish are already in the image.
Drop files into ./consume or add an IMAP account and a mail rule. Back up with document_exporter --passphrase, and upgrade by changing the tag and running docker compose up -d.

What you need and the compose file

The five containers

Paperless-ngx in Docker is one app container plus helpers. The diagram shows the stack this guide builds:

webserver is Paperless itself. The image bundles the web UI, the background workers, the consume folder watcher and the OCR tools. In 3.3.1 that was Tesseract 5.5.0 and OCRmyPDF 17.12.1.
db is PostgreSQL. The setup docs recommend it for new installs. SQLite and MariaDB also work.
broker is Valkey, a Redis-compatible store that queues background tasks.
tika and gotenberg are optional. They let Paperless read Office files such as .docx, .xlsx and .odt, plus .eml email files. Without them, it handles PDFs, images and plain text.

You need a Linux host with Docker and the Compose plugin. The project doesn't publish minimum hardware. On my 8-core test box, after all the tests below, the five containers used about 1.3 GB of RAM together, and most of that was Paperless itself (825 MB) and Tika (261 MB). The setup docs have a section for low-powered devices like a Raspberry Pi, with settings such as PAPERLESS_OCR_PAGES=1 that cut the OCR work.

The compose file and secrets

The official files live in the repo's docker/compose folder. This is docker-compose.postgres-tika.yml from the v3.3.1 tag with four changes. Every image is pinned to the exact version I tested (upstream uses latest for Paperless and tags like postgres:18 and valkey:9-alpine that move with each release), the port listens on 127.0.0.1 only, and the database password and secret key come from .env instead of being hard-coded.

mkdir -p ~/paperless/consume ~/paperless/export && cd ~/paperless
umask 077
cat > .env <<EOF
COMPOSE_PROJECT_NAME=paperless
POSTGRES_PASSWORD=$(openssl rand -hex 24)
PAPERLESS_SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_urlsafe(64))')
EOF
umask 022

umask 077 makes the new .env readable only by you. Compose reads .env automatically and fills in the ${...} values below. Keep COMPOSE_PROJECT_NAME=paperless, because upstream's .env sets it too, and it decides the volume names (paperless_media and so on).

services:
  broker:
    image: docker.io/valkey/valkey:9.1.2-alpine
    restart: unless-stopped
    volumes:
      - redisdata:/data
  db:
    image: docker.io/library/postgres:18.6
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:3.3.1
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "127.0.0.1:8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBENGINE: postgresql
      PAPERLESS_DBPASS: ${POSTGRES_PASSWORD}
      PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY}
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.37.0
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-javascript=true"
      - "--chromium-allow-list=^file:///tmp/.*"
  tika:
    image: docker.io/apache/tika:3.3.1.0
    restart: unless-stopped
volumes:
  data:
  media:
  pgdata:
  redisdata:

Save it as docker-compose.yml. The Gotenberg flags are upstream's. Gotenberg's Chromium converts .eml files, and the compose file's own comment says the flags stop it from loading external content such as tracking pixels or JavaScript.

The PostgreSQL volume is mounted at /var/lib/postgresql, not /var/lib/postgresql/data. That's correct for PostgreSQL 18. The 18.6 image sets PGDATA=/var/lib/postgresql/18/docker, so the database sits in a versioned folder inside the volume.

Next, docker-compose.env holds the Paperless settings. Upstream's copy contains PAPERLESS_SECRET_KEY=change-me. Don't keep that line. This is the file I ended up with:

USERMAP_UID=1000
USERMAP_GID=1000
PAPERLESS_TIME_ZONE=Europe/Berlin
PAPERLESS_OCR_LANGUAGE=deu+eng
#PAPERLESS_OCR_LANGUAGES=pol
#PAPERLESS_URL=https://paperless.example.com

Set USERMAP_UID and USERMAP_GID to the output of id -u and id -g, so the container can read and delete what you put in ./consume. Set PAPERLESS_TIME_ZONE to your own zone, since it defaults to UTC. The OCR and URL lines are explained below.

Why the secret key matters: in v3 it's required. The configuration docs say "Paperless will refuse to start if this is not set." It refuses the placeholder too. When I started 3.3.1 without a key, it stopped with:

django.core.exceptions.ImproperlyConfigured: PAPERLESS_SECRET_KEY is not set or is the default 'change-me' value. A unique, secret key is required for secure operation. Generate one with: python3 -c "import secrets; print(secrets.token_urlsafe(64))"

First start and the superuser

Start the stack

docker compose pull
docker compose up -d
docker compose logs -f webserver

With the images already pulled, my first start took about 35 seconds from up -d to a working login page. The log runs the database migrations and ends with lines like these:

[init-complete] paperless-ngx docker container init completed in 22 seconds
[INFO] Listening at: http://:::8000
[paperless.management.consumer] Watching /usr/src/paperless/consume using native file system events

Port 8000 now only answers on the server itself. Reach it with an SSH tunnel (ssh -L 8000:127.0.0.1:8000 you@server, then open http://localhost:8000), or put a reverse proxy in front. The Nginx Proxy Manager guide covers a web UI proxy with a free certificate, and the Umami guide shows the same 127.0.0.1 binding behind Caddy.

Create the admin account

There's no default login. On a fresh install, the first visit redirects to a sign-up page:

That note is the reason for the 127.0.0.1 binding. Whoever reaches this page first owns every document. Upstream's "8000:8000" publishes the port on all interfaces, and Docker's firewall docs explain that published ports skip ufw's rules. The Open WebUI guide runs into the same first-account problem. Create your account as soon as the stack is up.

You can also have the container create it. Per the configuration docs, PAPERLESS_ADMIN_USER and PAPERLESS_ADMIN_PASSWORD create a superuser at start, and they won't change an existing user's password. On a test stack, with the values passed through environment: like the secret key, the log printed [init-superuser] Creating superuser... and logging in with them worked.

The setup docs also suggest making a separate everyday user, since a superuser can see and change everything.

OCR languages that actually work

PAPERLESS_OCR_LANGUAGE vs PAPERLESS_OCR_LANGUAGES

The two names differ by one letter and do different jobs:

PAPERLESS_OCR_LANGUAGE (singular) tells Tesseract which language or languages to read. It takes three-letter codes joined with +, such as deu+eng. It defaults to eng.
PAPERLESS_OCR_LANGUAGES (plural) is Docker only. It installs extra language packs when the container starts, as a space-separated list such as pol tur.

The image already contains English, German, French, Italian and Spanish. tesseract --list-langs inside my 3.3.1 container showed deu, eng, fra, ita, spa and osd (orientation detection), plus pol once I added it.

To see why the singular setting matters, I generated a scanned German letter with no text layer and fed it in twice. Here's what Paperless stored:

With eng, every umlaut was dropped and "Grüßen" became "Griffen". The search index forgave some of that. A search for "Müller" found both copies. A search for "Grüßen" found only the one read with deu+eng. Set the language before you import your archive, because documents you've already added keep their old text unless you reprocess them.

For a language that isn't in the image, you need both settings. First I set only PAPERLESS_OCR_LANGUAGE=pol+eng. The container refused to finish starting and restarted over and over with:

?: The selected ocr language pol is not installed. Paperless cannot OCR your documents without it. Please fix PAPERLESS_OCR_LANGUAGE.

Adding the install line fixed it:

PAPERLESS_OCR_LANGUAGE=pol+eng
PAPERLESS_OCR_LANGUAGES=pol

The log showed [init-tesseract-langs] Installing package tesseract-ocr-pol... and then Installed tesseract-ocr-pol. A scanned Polish letter then came back with "Urząd Skarbowy w Łodzi", "Żeromskiego" and "1 234,56 zł" intact.

Two things to know about that install. It downloads the Debian package when the container starts, so the container needs internet access then. And it happens again every time the container is recreated. After a plain restart the log said Package tesseract-ocr-pol already installed!, but after docker compose up -d with changed settings it downloaded the package again. The docs add that this option doesn't work in rootless containers. Package names use hyphens where Tesseract codes use underscores, so traditional Chinese is chi-tra in PAPERLESS_OCR_LANGUAGES and chi_tra in PAPERLESS_OCR_LANGUAGE. When a user asked how to install a language pack by hand, maintainer stumpylog replied: "You don't do it manually with Docker." Use the environment variable.

Every language you add costs time. The docs warn that "Tesseract uses much more CPU time with multiple languages enabled," so list only the ones your documents use.

Other OCR settings worth knowing

The defaults are sensible. These are the ones you're most likely to change, as described in the configuration docs:

PAPERLESS_OCR_MODE defaults to auto. Paperless checks whether a PDF already has text and skips OCR if it does. redo replaces existing text layers, which helps when your scanner's own OCR is poor. force rasterizes everything first. off never runs OCR.
PAPERLESS_ARCHIVE_FILE_GENERATION decides when a PDF/A copy is made. The default auto makes one for scans and image PDFs and skips born-digital PDFs.
PAPERLESS_OCR_PAGES=1 OCRs only the first page, which the docs suggest for slow hardware.
PAPERLESS_OCR_CLEAN runs unpaper before OCR. The default is clean. The setup docs say none speeds up OCR and uses less memory, at the cost of slightly worse results.

Version 3 removed some older OCR settings, including PAPERLESS_OCR_MODE=skip and PAPERLESS_OCR_SKIP_ARCHIVE_FILE. The v3 migration guide maps each one to its replacement, and old values aren't honored, so check any settings you copy from an older guide.

OCR is good, not perfect. On my test invoice, the invoice number, both dates and the total came out exactly, and a search for RP-2026-0457 found the document. Two line items with dotted leaders (Labour, 2 hours ......) came out garbled. Expect to fix titles and dates by hand now and then, and keep the original file, which Paperless always does.

Getting documents in: consume folder and email

The consume folder

Anything you put in ./consume gets imported and then removed from the folder. When I copied the English scan in, the watcher waited until the file had stopped changing (the default stability delay is 5 seconds), and the import itself took about 7 seconds:

[paperless.management.consumer] File is stable: /usr/src/paperless/consume/invoice-scan-en.pdf
[ocrmypdf._pipelines._common] Output file is a PDF/A-2b (as expected)
[paperless.consumer] Document 2026-10-03 invoice-scan-en consumption finished

Paperless also read the date from the text. The document got 2026-10-03, the invoice date printed on it. Open any document and the Content tab shows the text OCR produced, next to a preview:

With Tika and Gotenberg running, Office files work the same way. A .docx I dropped in went to Tika for its text, then to Gotenberg for a PDF copy. One catch: Paperless took the document date from the file's metadata. My generated test file carried a 2013 creation date from its template, so the document was filed under December 24, 2013. Check dates on Office files.

Scanners and sync tools often write files as a different user. To see what that looks like, I put a file in ./consume owned by root with mode 600. Paperless runs as UID 1000, so it logged:

[ERROR] [paperless.management.consumer] Error while queuing document /usr/src/paperless/consume/root-owned.pdf
PermissionError: [Errno 13] Permission denied: '/usr/src/paperless/consume/root-owned.pdf'

After sudo chown 1000:1000 on the file, Paperless picked it up again by itself and imported it. If your scanner writes to the folder over the network, make sure the files arrive owned by the UID in USERMAP_UID, or readable by it.

If the folder is on NFS or an SMB share, Paperless may never notice new files, because those file systems often don't send change notifications. The configuration docs say to set PAPERLESS_CONSUMER_POLLING_INTERVAL to a number of seconds in that case. That's the v3 name. Older guides call it PAPERLESS_CONSUMER_POLLING.

Email import basics

Paperless can also pull attachments from a mailbox. In the UI, go to Mail, add an account, then add a rule for it. I tested this against a throwaway IMAP server on the same Docker network:

Mail account: IMAP server, port, security (None, SSL or STARTTLS), username and password.
Mail rule: folder INBOX, maximum age 30 days, "Only process attachments", and the action "Mark as read".

I sent a mail with a PDF attachment to the test mailbox and triggered a fetch through the API, which is what the Process Mail button does. The log showed Rule Lab inbox.Scans to Paperless: Consuming attachment stadtwerke-brief.pdf from mail Scan from office printer from scanner@lab.test, and the new document took its title from the mail subject. Without a manual trigger, Paperless checks mail on a schedule. PAPERLESS_EMAIL_TASK_CRON defaults to every ten minutes.

The rule action matters. Per the usage docs, "Mark as read" means Paperless ignores mail that's already read, so a mail you open on your phone first won't be imported. "Move to folder" or a custom tag avoids that. "Delete" removes consumed mail right away, and the docs say to use it with caution.

Backups, upgrades and common errors

Back up and upgrade

The document exporter writes all documents, thumbnails and database contents to a folder. With the compose file above, that's ./export on the host:

docker compose exec -T webserver document_exporter ../export --passphrase 'a-long-passphrase'

Don't skip --passphrase. Without it, the exporter printed No passphrase was given, sensitive fields will be in plaintext, and my test mail account's password was readable in export/manifest.json. With a passphrase, that field was encrypted. Keep the passphrase somewhere other than the backup.

The administration docs add a warning: you can't import an export into a different Paperless version. The other option is to back up the Docker volumes themselves (paperless_media, paperless_data and paperless_pgdata), which you need root to read.

To upgrade, back up first, then change the tag. I tested this from 3.3.0 to 3.3.1 on a separate stack:

docker compose exec -T webserver document_exporter ../export --passphrase 'a-long-passphrase'
docker compose down
# edit docker-compose.yml: paperless-ngx:3.3.0 -> paperless-ngx:3.3.1
docker compose pull
docker compose up -d

docker compose down without -v keeps the volumes. The new container ran the migration step (No migrations to apply. for this patch release), /api/status/ reported version 3.3.1, and the test document was still there and searchable. Read the release notes before every bump. Coming from v2, the v3 migration guide says you must be on 2.20.15 first.

Two v3 changes catch people coming from older guides. PAPERLESS_DBENGINE: postgresql is now required for PostgreSQL, and duplicates are no longer rejected (see the FAQ). Once it runs, an Uptime Kuma HTTP monitor on the login page tells you when it stops answering.

Common errors

The container restarts in a loop after you change OCR settings

Check docker compose logs webserver for The selected ocr language ... is not installed. Add the language to PAPERLESS_OCR_LANGUAGES, or remove it from PAPERLESS_OCR_LANGUAGE. Remember the underscore rule for codes like chi_tra.

CSRF verification failed when you log in through a proxy

The login page loads, but logging in returns 403 CSRF verification failed. Request aborted. To reproduce it without a real proxy, I sent the login request with curl, using the headers a TLS-terminating proxy adds for https://paperless.example.test. The log said:

[WARNING] [django.security.csrf] Forbidden (Origin checking failed - https://paperless.example.test does not match any trusted origins.): /accounts/login/

The fix is PAPERLESS_URL, set to the public address with no trailing slash:

PAPERLESS_URL=https://paperless.example.test

After docker compose up -d, the same request logged in. Per the configuration docs, PAPERLESS_URL fills in Django's allowed hosts, CORS and CSRF trusted origins in one go. If it's set and you still get Origin checking failed - null, a support thread traced that to a Referrer-Policy: no-referrer header added by the proxy.

FAQ

Setup and storage

How much RAM does Paperless-ngx need?

The project doesn't publish a minimum. On my test box, the full stack with PostgreSQL, Valkey, Tika and Gotenberg used about 1.3 GB of RAM after several OCR jobs. Tika and Gotenberg are optional, and leaving them out drops support for Office files. For small machines, the setup docs suggest settings like PAPERLESS_OCR_PAGES=1 and PAPERLESS_OCR_CLEAN=none.

Where are my documents stored with Docker?

In the paperless_media volume, which on Linux is usually under /var/lib/docker/volumes/paperless_media/_data. The FAQ says not to mess with that folder by hand. Files you put in ./consume are copied into the media volume and removed from the consume folder. To get your files out with readable names, use the exporter.

Does Paperless-ngx reject duplicate documents?

Not since v3. When my mail test brought in a PDF I had already imported, the log said Consuming duplicate stadtwerke-brief.pdf: 2 existing document(s) share the same content. and imported it anyway. Per the FAQ, the document page then shows a Duplicates tab that lists the copies. Set PAPERLESS_CONSUMER_DELETE_DUPLICATES=true if you want the old behavior of rejecting them.

OCR and import

Why does Paperless say the selected OCR language is not installed?

PAPERLESS_OCR_LANGUAGE names a language the image doesn't contain. Add it to PAPERLESS_OCR_LANGUAGES so the container installs it at startup, and give the container internet access while it starts. For codes with an underscore, write chi_tra in the singular setting and chi-tra in the plural one.

Why isn't Paperless picking up files from my consume folder?

Check docker compose logs webserver first. A PermissionError means the files belong to a different user than USERMAP_UID, so fix the ownership. If nothing is logged at all and the folder is on NFS or SMB, set PAPERLESS_CONSUMER_POLLING_INTERVAL as the docs describe. Also check that you're writing to the folder that's mounted to /usr/src/paperless/consume in the compose file.

How do I fix "CSRF verification failed" behind a reverse proxy?

Set PAPERLESS_URL to the exact public URL, like https://paperless.example.com with no trailing slash, and recreate the container with docker compose up -d. In my test, that turned a 403 into a successful login.

Originally published on DeployLark: Paperless-ngx Docker Compose Setup with OCR

Nginx Proxy Manager with Docker: Proxy Hosts and Free SSL

DeployLark — Sat, 17 Oct 2026 11:20:05 +0000

Once you run more than one self-hosted app, you hit the same problem every time. Each app wants its own port, and none of them has HTTPS. Nginx Proxy Manager (NPM) fixes both. It sits in front of your apps, answers on ports 80 and 443, sends each domain to the right container, and gets free Let's Encrypt certificates for you, all from a web UI.

It's a popular choice. On October 14, 2026, the project's GitHub repository had about 34,400 stars, and the jc21/nginx-proxy-manager image had been pulled more than 285 million times from Docker Hub.

This guide covers a clean install, the first-run setup (it changed in recent versions, so a lot of older guides are wrong), your first proxy host, both ways to get a certificate, and the errors you're most likely to hit.

TL;DR:

Run jc21/nginx-proxy-manager:2.16.0 with ports 80 and 443 public, bind the admin UI to 127.0.0.1:81, and keep both the /data and /etc/letsencrypt volumes.
There's no admin@example.com / changeme login on 2.16. You create the admin account on the first-run screen, so use a real email, because NPM also uses it for Let's Encrypt.
Put NPM and your apps on one shared Docker network and forward to the service name and the container's internal port. localhost there means NPM itself and gives you a 502.
Request the certificate in the SSL tab. HTTP-01 needs DNS pointing at the server and port 80 open. DNS-01 with a scoped Cloudflare token also covers wildcards.

Install Nginx Proxy Manager with Docker Compose

Before you start

Without a reverse proxy, you reach apps like this: http://203.0.113.10:3001, http://203.0.113.10:8080, and so on. That's one open port per app and no TLS.

With a reverse proxy, only ports 80 and 443 are open. A request for https://status.example.com reaches NPM. NPM reads the hostname and passes the request to the container that serves it (for example uptime-kuma:3001) over the internal Docker network. NPM handles HTTPS, so the app behind it doesn't need to know anything about certificates.

You need:

A Linux server with Docker and the Docker Compose plugin.
A domain, with an A record for each hostname (or a wildcard *.example.com) pointing at the server's public IP.
Ports 80 and 443 reachable from the internet (cloud firewall, router port forwarding). Port 80 matters even if you only want HTTPS, because Let's Encrypt's HTTP-01 check only works on port 80.
Nothing else already listening on 80, 443 or 81 on the host.

The compose file and first start

Create a folder and a compose file. This is the official quick-setup file with three changes. The image is pinned to the current release, there's a timezone you'll want to change, and the admin port is bound to 127.0.0.1:

mkdir -p ~/npm && cd ~/npm
nano compose.yaml

services:
  app:
    image: 'jc21/nginx-proxy-manager:2.16.0'
    restart: unless-stopped
    ports:
      - '80:80'              # public HTTP
      - '443:443'            # public HTTPS
      - '127.0.0.1:81:81'    # admin UI, only reachable from the server itself
    environment:
      TZ: "Europe/London"   # change to your timezone
      # DISABLE_IPV6: 'true'  # uncomment if your host has no IPv6
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

Start it:

docker compose up -d
docker compose logs -f app

The first start runs database migrations and takes a little while. When you see Backend PID ... listening on port 3000, it's ready. Check from the server itself, since port 81 only answers there now:

curl -s http://127.0.0.1:81/api/

On a fresh install that returned:

{"status":"OK","setup":false,"version":{"major":2,"minor":16,"revision":0}}

"setup":false means no admin account exists yet. That's the next step.

Why bind port 81 to localhost? It's your admin panel, and upstream's file publishes '81:81' on every interface. A host firewall won't save you here. Docker's firewall docs say that when you publish a container's ports, "traffic to and from that container gets diverted before it goes through the ufw firewall settings." On my test box, with the 127.0.0.1 binding, the API answered on 127.0.0.1 but not on the server's network address. To use the admin UI from your laptop, open an SSH tunnel:

ssh -L 8181:127.0.0.1:81 you@your-server

Then browse to http://localhost:8181. Once NPM works, you can also put the admin UI behind its own proxy host with an access list.

A few more things I learned in testing:

Keep both volumes. When I started the image without /etc/letsencrypt mounted, it refused to start and logged ERROR: /etc/letsencrypt is not mounted! Check your docker configuration.
SQLite is the default and is fine for a single server. The full setup docs also have MariaDB, MySQL and Postgres variants.
The project doesn't publish minimum requirements. On my test box the idle container used about 110 to 130 MB of RAM.
Images are built for amd64 and arm64. The setup docs say armv7 was dropped in 2.14 and point 32-bit ARM users to the 2.13.7 tag.

Create the admin account

The setup screen replaced the default login

Open the admin UI through the SSH tunnel at http://localhost:8181. If you kept upstream's '81:81', use http://<server-ip>:81.

If you've read an older guide, you're expecting to log in with admin@example.com and changeme. That was true up to the 2.12.x releases (it's in the v2.12.6 README), but it was removed from the README in 2.13.0. On 2.16.0 there is no default account. You get a "Welcome! Get started by creating your admin account" screen with Full Name, Email address and New Password.

Use a real email address here. NPM uses your account email as the Let's Encrypt account email. In my test the certificate request ran certbot ... -m admin@lab.test ..., and Let's Encrypt rejected it with The ACME server believes admin@lab.test is an invalid email address. A made-up address here means certificate requests fail later.

Scripted setup and two-factor login

If you'd rather create the admin account without the setup screen (useful for scripted installs), the advanced config docs list two variables for it. Don't type the password into compose.yaml. Put it in a .env file next to it that only you can read:

cat > .env <<'EOF2'
INITIAL_ADMIN_EMAIL=you@example.com
INITIAL_ADMIN_PASSWORD=a-long-random-password
EOF2
chmod 600 .env

Then reference the variables in compose.yaml:

    environment:
      INITIAL_ADMIN_EMAIL: ${INITIAL_ADMIN_EMAIL}
      INITIAL_ADMIN_PASSWORD: ${INITIAL_ADMIN_PASSWORD}

After the first start, delete both lines from compose.yaml, delete .env, and run docker compose up -d. I tested this. The account was created, /api/ reported "setup":true, and after removing the variables and recreating the container I could still log in with the same password. Change the password in the UI if it was ever stored anywhere else.

NPM has supported TOTP two-factor authentication since 2.13.6. The 2.16 UI includes an "Enable Two-Factor Authentication" option for your account. Turn it on, because this panel controls all your traffic.

Add a proxy host

Connect NPM to your apps with a shared network

The easiest way to connect NPM to your apps is a shared Docker network. NPM then reaches each app by its service name, and the apps don't need to publish any ports to the host. This is the approach the NPM docs recommend:

docker network create proxy

Add this to the bottom of NPM's compose.yaml and to each app's compose file:

networks:
  default:
    external: true
    name: proxy

Then run docker compose up -d again in each folder. If an app's compose file already defines its own networks, attach just the web service to proxy instead.

In the NPM UI, go to Hosts > Proxy Hosts > Add Proxy Host. The Details tab has:

Domain Names: status.example.com
Scheme: http. This is the protocol between NPM and the app, which is almost always plain HTTP.
Forward Hostname / IP: the container's service name, for example uptime-kuma.
Forward Port: the port the app listens on inside its container (for example 3001), not a host port.
Access List: leave it as Publicly Accessible for now.
Options: Block Common Exploits is a sensible default. Turn on Websockets Support for any app with a live UI (see below).

This is the Details tab from my lab run, pointing a test hostname at a container named whoami:

Save, then test from any machine:

curl -I http://status.example.com

In my lab, a proxy host pointing at a container named whoami on the shared network returned that container's page, and a hostname with no proxy host got NPM's "Congratulations!" default site. You can change that default under Settings > Default Site.

The saved host shows up in the Proxy Hosts list:

For a full example app behind NPM, see Uptime Kuma with Docker.

Websockets, access lists and custom locations

Some apps won't work at all without HTTPS. Vaultwarden's web vault is one, as the Vaultwarden HTTPS guide shows. I tested that fix with Caddy, and an NPM proxy host with a Let's Encrypt certificate should fix it the same way.

Websockets Support (Details tab) matters for apps with a live UI, such as Uptime Kuma, n8n, Home Assistant or Open WebUI. They break in strange ways without it, with "connection lost" banners and dashboards that never update. The n8n guide and the Open WebUI guide show what that looks like. When I turned the toggle on, NPM added these lines to the generated nginx config:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
proxy_http_version 1.1;

If you aren't sure whether an app needs it, turn it on. It doesn't hurt plain HTTP apps.

Access lists (Access Lists menu) hold HTTP basic-auth users and allow or deny IP rules. Pick one in a proxy host's Access List field. It's a cheap way to lock down admin panels that have weak or no auth of their own. NPM 2.16.0 also added per-path access lists inside the proxy host modal.

Custom Locations (a tab in the proxy host) send a path such as /api to a different container or port than the rest of the host. Most single-app hosts don't need them.

The Advanced tab (gear icon) takes raw nginx directives for the server block. Use it sparingly. If a snippet breaks the config, 2.16.0 keeps the failed file as .conf.err so you can see what went wrong.

Get a free Let's Encrypt certificate

Edit the proxy host and open the SSL tab. Under SSL Certificate, pick "Request a new Certificate (with Let's Encrypt)". The other toggles are:

Force SSL redirects HTTP to HTTPS. Turn it on once the certificate works.
HTTP/2 Support is safe to enable.
HSTS Enabled and HSTS Sub-domains tell browsers to use only HTTPS for this host (and its subdomains) for a long time. Leave these off until you're sure HTTPS works everywhere, because they're hard to undo.

Then pick a challenge type.

HTTP-01 (the default)

Per Let's Encrypt's docs, HTTP-01 asks for a token at http://<your-domain>/.well-known/acme-challenge/... and checks that your server returns it. NPM serves that path itself, from a letsencrypt-acme-challenge folder in its data volume. The challenge can only succeed when DNS for the hostname already points at this server and port 80 is reachable from the internet. On Oct 14, 2026, I verified this domain and HTTP-01 path by getting a real Let's Encrypt certificate over HTTP-01 on a public Debian 13 server running Caddy, while NPM's own certificate request screen follows NPM's documentation.

HTTP-01 can't issue wildcard certificates, and it fails if your ISP blocks port 80.

NPM 2.16's code also includes a reachability check for HTTP-01. It writes a test file and asks an outside service (site24x7.com) to fetch it from your domain. Run it before you request a real certificate, because failed attempts count toward rate limits (covered below).

DNS-01 with Cloudflare

With DNS-01, according to Let's Encrypt's docs, certbot proves you control the domain by creating a TXT record at _acme-challenge.<your-domain>. Use it when:

you want a wildcard certificate (*.example.com),
the server isn't reachable on port 80 (a home lab behind CGNAT, or an internal-only service), or
you have several servers.

In the SSL tab, turn on Use DNS Challenge, choose your DNS Provider, and paste the credentials. NPM 2.16.0 ships certbot plugins for a long list of providers, Cloudflare included. For Cloudflare, NPM's template is:

# Cloudflare API token
dns_cloudflare_api_token=your-cloudflare-api-token

Create an API token (not the Global API Key) in the Cloudflare dashboard. The certbot-dns-cloudflare docs say it needs Zone:DNS:Edit permission, only for the zones you need certificates for.

Two cautions:

That token can change your DNS. Let's Encrypt's challenge docs warn that keeping DNS API credentials on a web server raises the stakes if the server is compromised, so scope the token as narrowly as you can.
2.16.0 updated certbot, and the release notes warn that some DNS plugins may need dependency tweaks. If your provider's plugin errors after an upgrade, check the issue tracker before you assume your token is wrong.

Fix common SSL errors

Certificate requests that fail

"Internal Error" when requesting a certificate

This is NPM's generic message. The real reason is in the certbot log, which sits in your data volume:

sudo tail -n 50 ~/npm/data/logs/letsencrypt.log   # the data folder is owned by root
docker compose logs app | grep -i -A5 "SSL\|certbot"

The usual causes are DNS not pointing at the server yet, port 80 blocked, or an invalid account email (see above).

Challenge fails with "Timeout", "Connection refused" or the wrong IP

Let's Encrypt couldn't fetch the token. Check these from outside your network (mobile data works):

dig +short status.example.com       # should print your server's public IP
curl -I http://status.example.com   # should answer from NPM, not time out

If the IP is wrong, fix DNS and wait for it to update. If you get a timeout, open port 80 in the cloud firewall or router. If you use Cloudflare's proxy (orange cloud) and HTTP-01 keeps failing, switch to the DNS challenge, which doesn't depend on the HTTP path.

Rate limited

Retrying over and over burns Let's Encrypt's rate limits. The ones you're most likely to hit while troubleshooting:

5 failed validations per hostname, per account, per hour.
5 certificates for the exact same set of hostnames every 7 days. Reinstalling and requesting again is the classic way to hit this one.
50 certificates per registered domain every 7 days.

Revoking certificates doesn't reset these limits. Fix the cause first, test it, then request once.

Errors after the certificate is issued

ERR_TOO_MANY_REDIRECTS behind Cloudflare

If Cloudflare's SSL/TLS mode is Flexible, Cloudflare talks to your server over plain HTTP. With Force SSL on, NPM redirects that to HTTPS, and Cloudflare requests HTTP again, in a loop. Cloudflare's fix is to set the mode to Full or higher, which needs a valid certificate on the origin (NPM's Let's Encrypt certificate works here), or else to stop redirecting at the origin.

502 Bad Gateway after a "successful" setup

The certificate is fine, but NPM can't reach the app. The most common mistake is putting localhost or 127.0.0.1 in Forward Hostname. Inside the NPM container, that address means NPM itself. In my lab, a proxy host pointed at 127.0.0.1:8080 returned 502, and the host's error log said:

connect() failed (111: Connection refused) while connecting to upstream ... upstream: "http://127.0.0.1:8080/"

Use the app's service name on the shared Docker network, with the container's internal port. If the app runs directly on the host instead of in Docker, use the host's LAN IP. Per-host logs are in ~/npm/data/logs/proxy-host-<id>_error.log.

FAQ

Logging in and updating

Why doesn't admin@example.com / changeme work?

Because 2.16 has no default account. Since 2.13.0, a fresh install shows a setup screen where you create the admin account yourself.

How do I update Nginx Proxy Manager?

The upgrading page says to run docker compose pull and docker compose up -d, and adds: "This project will automatically update any databases or other requirements so you don't have to follow any crazy instructions." Some releases do add migrations, so I'd back up first. With a pinned tag, change it in compose.yaml, then:

cd ~/npm
docker compose stop                       # don't copy the SQLite file while it's in use
sudo cp -a data data.bak-$(date +%F)
docker compose pull && docker compose up -d

Read the release notes before major bumps. 2.15.0 and 2.16.0 both updated certbot and warned that DNS plugins may need changes. Version 2.13.3 added a migration and warned that you can't easily downgrade after it.

Why are my settings gone after Docker restarts?

NPM keeps its database and config in /data and its certificates in /etc/letsencrypt. If those aren't mounted to folders or volumes on the host, recreating the container starts from scratch. Use both volume lines from the compose file above. The official image won't even start without /etc/letsencrypt mounted.

Certificates and errors

How do I get a wildcard certificate?

Use the DNS challenge. HTTP-01 can't issue wildcards. Request a certificate for *.example.com (and example.com if you want the bare domain too), turn on Use DNS Challenge, pick your provider and paste a scoped API token, as in the Cloudflare example above.

Why do I get 502 Bad Gateway?

NPM can't reach the app at the Forward Hostname and port you gave it. Don't use localhost or 127.0.0.1, which mean the NPM container itself. Put NPM and the app on the same Docker network and use the service name and the container's internal port.

How do I protect the admin panel on port 81?

Don't publish it to the internet. Port 81 serves the login form over plain HTTP. The compose file above binds it to 127.0.0.1, and on my test box it then answered only on the server itself. Reach it through an SSH tunnel (ssh -L 8181:127.0.0.1:81 you@your-server). A reply in issue #481 suggests another option: a proxy host such as npm.example.com that forwards to 127.0.0.1 port 81 with SSL, after which you remove the port 81 mapping from the compose file. If you go that way, I'd also add an access list to that proxy host so only your own IP addresses can reach it. Turn on two-factor login either way.

Originally published on DeployLark: Nginx Proxy Manager with Docker: Proxy Hosts and Free SSL

Fix n8n 'Connection Lost' and Webhook URLs Behind a Proxy

DeployLark — Fri, 16 Oct 2026 06:48:05 +0000

You put n8n behind a reverse proxy, open https://n8n.example.com, and two things go wrong:

A red "Connection lost" badge sits in the editor. Hovering it says: "You have a connection issue or the server is down. n8n should reconnect automatically once the issue is resolved." It never reconnects. Executions don't update live.
The Webhook node shows URLs like http://localhost:5678/webhook/..., or https://n8n.example.com:5678/webhook/..., that nobody outside the server can call.

They're separate problems with separate fixes. The first is the proxy. The second is n8n's environment variables. A third, quieter problem (n8n not trusting the proxy's headers) usually shows up in the logs at the same time. Each one was reproduced on a test box, using a test hostname over plain HTTP through the proxy, and checked every fix below.

Short version:

Webhook URL shows localhost:5678: set N8N_WEBHOOK_URL=https://n8n.example.com/ (or WEBHOOK_URL before n8n 2.30.0) and recreate the container with docker compose up -d.
"Connection lost" in the editor: the proxy has to pass WebSocket upgrades (Upgrade and Connection headers over HTTP/1.1) and keep the original Host. In Nginx Proxy Manager, that's the Websockets Support toggle.
Set N8N_PROXY_HOPS=1 for one proxy, so n8n trusts the X-Forwarded-* headers.
Test with a Webhook node. Both of its URLs should start with your domain, with no :5678.

Why n8n breaks behind a reverse proxy

Symptoms and causes at a glance

What you see	Cause	Fix
Webhook URL starts with `http://localhost:5678/`	n8n doesn't know its public URL	Set `N8N_WEBHOOK_URL`
Webhook URL is `https://your-domain:5678/`	`N8N_HOST` and `N8N_PROTOCOL` set, but no webhook URL	Set `N8N_WEBHOOK_URL`
"Connection lost" in the editor, browser console shows `[WebSocketClient] Connection lost, code=...`	Proxy isn't passing WebSocket upgrades, or is rewriting the `Host` header	Fix the proxy
Logs show `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR`	n8n doesn't trust the proxy	Set `N8N_PROXY_HOPS=1`
Login page warns about a secure cookie	You're on plain HTTP	See the FAQ

A minimal n8n Docker Compose file

This is the setup the rest of the article fixes up. It follows the shape of the official Docker Compose docs: the image from n8n's own registry, a named volume for /home/node/.n8n, and the port bound to localhost only, so the proxy is the only way in.

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:2.43.4
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      - GENERIC_TIMEZONE=Europe/Berlin
      - TZ=Europe/Berlin
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

Pin a version tag rather than latest, so an upgrade only happens when you choose. 2.43.4 was the current stable release at the time of testing. Check n8n's release notes for newer ones.

If your proxy also runs in Docker (Nginx Proxy Manager, Traefik, Caddy), put both containers on a shared network so the proxy can reach http://n8n:5678 by service name. You can then drop the ports: section entirely. The Nginx Proxy Manager guide shows the shared-network setup.

At idle, n8n used about 690 MiB of RAM on the test box (docker stats). n8n's docs don't list an official minimum.

Back up the n8n_data volume. Per n8n's docs, n8n generates a random encryption key on first launch, saves it in that folder, and uses it to encrypt your saved credentials. Lose the volume and you lose the key, and with it access to every credential. If you'd rather manage the key yourself, set N8N_ENCRYPTION_KEY before the first start.

n8n is one of the most popular self-hosted automation tools. On October 14, 2026, its GitHub repository had about 207,300 stars, and the n8nio/n8n image had been pulled more than 271 million times from Docker Hub. So the fixes below get searched a lot.

Fix 1: tell n8n its public URL

Set N8N_WEBHOOK_URL

With the file above, open any Webhook node and the URL is http://localhost:5678/webhook/.... n8n builds webhook URLs from what it knows about itself, and by default that's localhost, port 5678, plain HTTP. It can't learn your domain from the proxy for this.

This is the Webhook node on a default install in the lab:

The common half-fix is to set N8N_HOST and N8N_PROTOCOL:

      - N8N_HOST=n8n.example.com
      - N8N_PROTOCOL=https

On n8n 2.43.4 that produced https://n8n.example.com:5678/webhook/... in testing. The internal port leaks into the URL, because n8n doesn't know the proxy is listening on 443.

The full fix is to set the webhook base URL explicitly:

    environment:
      - GENERIC_TIMEZONE=Europe/Berlin
      - TZ=Europe/Berlin
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_HOST=n8n.example.com
      - N8N_PROTOCOL=https
      - N8N_WEBHOOK_URL=https://n8n.example.com/
      - N8N_PROXY_HOPS=1

Then recreate the container (a restart doesn't pick up new env vars):

docker compose up -d

Webhook URLs now read https://n8n.example.com/webhook/..., with no port.

In the lab, with n8n.lab.test standing in for the real domain, the Production URL looked like this:

N8N_WEBHOOK_URL or WEBHOOK_URL?

Most older guides and forum answers say WEBHOOK_URL. n8n's current docs use N8N_WEBHOOK_URL. The Docker Compose page says it's "available from n8n 2.30.0" and to use WEBHOOK_URL on earlier versions. The webhook URL page says WEBHOOK_URL "is deprecated from n8n 2.35.0". On 2.43.4, WEBHOOK_URL still works but prints this at startup:

WEBHOOK_URL -> Use N8N_WEBHOOK_URL instead, which sets the base URL for both test and production webhooks.

So: on 2.30.0 or later, use N8N_WEBHOOK_URL. On anything older, use WEBHOOK_URL. Don't set both.

If the editor itself lives at a different URL than the webhooks, there's also N8N_EDITOR_BASE_URL. For a normal single-domain setup you don't need it.

Fix 2: pass WebSockets and the Host header

Other apps with a live UI need the same thing from a proxy. Uptime Kuma and Open WebUI both break without WebSocket support.

"Connection lost" is about the editor's live connection to the server, called the push connection. The browser opens it at /rest/push. By default it's a WebSocket (N8N_PUSH_BACKEND defaults to websocket), so the proxy has to do two things:

Pass the WebSocket upgrade. Forward the Upgrade and Connection headers, over HTTP/1.1.
Keep the original Host. n8n compares the browser's Origin header with the host the request was sent to. It checks Forwarded, then X-Forwarded-Host, then Host. If they don't match, it rejects the connection.

Here's what each broken setup did in testing, so you can match it to your own:

Proxy setup	Result on `/rest/push`
Nginx Proxy Manager, Websockets Support off	`401 Unauthorized` (the request reaches n8n as a plain GET, not an upgrade)
nginx with only `proxy_pass`	`HTTP 500`
nginx with `Upgrade`/`Connection` headers but no `Host` header	Connection opens, then closes with code 1008 and `Invalid origin!`
Either proxy configured as below	Works

For the third case, n8n's log spells it out:

Origin header does NOT match the expected origin. (Origin: "http://n8n.lab.test" -> "n8n.lab.test", Expected: "n8n:5678" -> "n8n:5678", Protocol: "http")

nginx sent Host: n8n:5678 (its upstream name) instead of the domain the browser used. n8n saw the mismatch and refused.

In the browser, that setup left the editor with the "Connection lost" badge in the top right corner:

Nginx Proxy Manager

Edit the proxy host and, on the Details tab, turn on Websockets Support. That's the whole fix. NPM already sends the original Host and the X-Forwarded-* headers. Use these settings:

Domain Names: n8n.example.com
Scheme: http
Forward Hostname / IP: n8n (the service name, if both are on the same Docker network)
Forward Port: 5678
Websockets Support: on
SSL tab: your certificate, with Force SSL on

After turning it on, the push connection through NPM stayed open and the badge went away.

Plain nginx

This is the server block that worked in testing. The map goes in the http {} context, for example at the top of a file in /etc/nginx/conf.d/:

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name n8n.example.com;
    # for HTTPS, use your usual "listen 443 ssl;" and ssl_certificate lines instead

    location / {
        proxy_pass http://n8n:5678;    # or http://127.0.0.1:5678 if nginx runs on the host
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_buffering off;
        proxy_read_timeout 3600s;
    }
}

proxy_buffering off keeps streamed responses flowing instead of nginx holding them back. The long proxy_read_timeout stops nginx from closing an idle push connection after its default 60 seconds.

Reload nginx (nginx -t && nginx -s reload), hard-refresh the editor, and the badge should be gone.

Through the working server block in the lab, the same workflow loaded with no badge:

If you reach n8n at something like https://n8n.example.com:8443, the browser's Origin includes :8443. If your proxy forwards only the hostname, n8n sees n8n.example.com vs n8n.example.com:8443 and rejects it with Invalid origin!. This reproduces through NPM. The simplest fix is to serve n8n on the standard port 443. If you can't, look at what the check compares. n8n's origin check (in its origin-validator code) compares the Origin's host and port with the forwarded host, so the Host / X-Forwarded-Host your proxy sends has to include the port too. In nginx, $http_host passes on the host exactly as the browser sent it, port included. $host drops the port.

Fix 3: trust the proxy, then test a webhook

Set N8N_PROXY_HOPS

Behind a proxy, log in once and check docker compose logs n8n. Without N8N_PROXY_HOPS, this appeared on every login through NPM:

ValidationError: The 'X-Forwarded-For' header is set but the Express 'trust proxy' setting is false (default). ... ERR_ERL_UNEXPECTED_X_FORWARDED_FOR

n8n's web server (Express) doesn't trust X-Forwarded-* headers unless told how many proxies are in front of it. N8N_PROXY_HOPS defaults to 0. Set it to the number of reverse proxies between the internet and n8n. For one Nginx Proxy Manager or one nginx, that's 1:

      - N8N_PROXY_HOPS=1

With that set, the warning went away. If you also have Cloudflare proxying in front of your own proxy, that's two hops.

Verify with a test webhook

Create a workflow and add a Webhook trigger. Set HTTP Method to POST and give it a fixed Path, like deploylark-test.
The node panel has two URLs, Test URL and Production URL. Both should start with https://n8n.example.com/. If either shows localhost or :5678, go back to Fix 1.
Test URL. Click Listen for test event (or Execute workflow), then from any machine:

   curl -X POST https://n8n.example.com/webhook-test/deploylark-test -d 'hello=world'

The data should show up in the editor right away. If it only shows up after a refresh, the push connection is still broken (Fix 2).

Production URL. Publish the workflow, then:

   curl -X POST https://n8n.example.com/webhook/deploylark-test -d 'hello=world'

With the default "Respond: Immediately", the response was {"message":"Workflow was started"}. Production runs don't appear on the canvas. Check the workflow's Executions tab.

The two 404s you'll hit while testing mean different things:

Test URL, not listening: The requested webhook "deploylark-test" is not registered. with a hint to click Execute workflow first. The test URL only works for one call after each click.
Production URL, workflow not published: The requested webhook "POST deploylark-test" is not registered. The workflow must be published (the hint text still says "active" and "toggle", from older versions).

Both 404s came through the proxy with the right domain, so they mean the proxy is fine and n8n just isn't listening on that path.

FAQ

Webhooks and login

How do you change localhost:5678 in the webhook URL?

Set N8N_WEBHOOK_URL=https://n8n.example.com/ (or WEBHOOK_URL before n8n 2.30.0) and recreate the container with docker compose up -d. Setting only N8N_HOST and N8N_PROTOCOL gave https://n8n.example.com:5678/, with the internal port still in it. See Fix 1.

Why does the login page say the n8n server is configured to use a secure cookie?

The full message is "Your n8n server is configured to use a secure cookie, however you are either visiting this via an insecure URL, or using Safari." N8N_SECURE_COOKIE defaults to true, so the login cookie only works over HTTPS. Put a certificate on the proxy and use the https:// URL. Only set N8N_SECURE_COOKIE=false for a throwaway local test, never on an instance reachable from the internet.

Changed the env vars and nothing happened?

docker compose restart reuses the old container config. Run docker compose up -d so Compose recreates the container with the new environment. If you keep the values in a .env file, Compose only uses them to fill in ${...} placeholders in compose.yaml, so each variable still needs a line under environment:. Then check that it took effect:

docker compose exec n8n printenv | grep N8N_

Proxies and Cloudflare

My proxy can't do WebSockets at all. Is there another option?

Yes. Set N8N_PUSH_BACKEND=sse and n8n uses Server-Sent Events, which is ordinary HTTP streaming. This was tested through Nginx Proxy Manager with Websockets Support off. /rest/push returned 200 with Content-Type: text/event-stream and stayed open. On plain nginx, the server block above already has proxy_buffering off and a long proxy_read_timeout, both sensible for a long-lived stream. WebSockets is n8n's default, so only switch if you have to.

Why do you get "Connection lost" behind Cloudflare?

According to Cloudflare's docs, proxied WebSockets are supported on all plans, with a WebSockets toggle on the zone's Network page. Make sure it's on. Then check three things:

If n8n's log shows Invalid origin!, the host that reaches n8n doesn't match the browser's Origin. Fix the Host and X-Forwarded-Host headers as in Fix 2.
Cloudflare's proxy sits in front of yours, so count it in N8N_PROXY_HOPS (see Fix 3).
Cloudflare documents redirect loops with SSL mode "Flexible" in front of an origin that forces HTTPS. The Nginx Proxy Manager guide covers that loop.

Originally published on DeployLark: Fix n8n 'Connection Lost' and Webhook URLs Behind a Proxy

DEV Community: DeployLark

Self-Host Supabase with Docker: Studio, API Keys and Errors

What self-hosted Supabase includes, and what stays on Cloud

Cloud-only features

Hardware and ports

Install Supabase with Docker Compose

Clone the pinned release

Generate JWT_SECRET, ANON_KEY and SERVICE_ROLE_KEY

Start the stack and create a table in Studio

Keep the ports on localhost and start the stack

Create a table and read it over REST

Fix API key, RLS, Storage and signup errors

API keys and RLS: 401, PGRST301, [] and 42501

Storage and signup: NoSuchBucket, AccessDenied and 504

HTTPS, backups and upgrades

Set SITE_URL and add HTTPS

Back up and upgrade with update.sh

FAQ

Setup, limits and login

How much RAM does self-hosted Supabase need?

Can one self-hosted Supabase run multiple projects?

Why does my new dashboard password not work?

Keys, email and redirects

Why does REST return "No suitable key or wrong key type" while Auth works?

Why does signup fail with "Error sending confirmation email"?

Why do auth emails redirect to localhost:3000?

Portainer CE on Docker: Install, Stacks and Git Updates

Install Portainer CE with Docker Compose

The compose file and ports

First login and the setup token

Fix the admin setup timeout

What the timeout looks like

Restart and finish within five minutes

Move existing compose projects into Portainer

Why the stack shows Limited

Take full control without losing data

Deploy stacks from Git and keep them updated

Add a Git source and deploy the stack

Polling and webhooks in CE

Back up, upgrade and keep it private

Back up the configuration

Upgrade to a new version

FAQ

Setup and access

What does "Your Portainer instance has timed out for security purposes" mean?

Do you need ports 8000 and 9000?

Where is the setup token?

Stacks and Git

Why do stacks show as Limited, and how do you fix it?

Are Git webhooks and automatic updates free in Portainer CE?

Does a Portainer backup include my containers and volumes?

Homepage Dashboard Docker Setup: Config, Widgets and Labels

Install Homepage with Docker Compose

The compose file

First start and the default config files

Add services and info widgets

services.yaml with an Uptime Kuma widget

widgets.yaml and settings.yaml

Docker integration and label discovery

docker.yaml through a socket proxy

Labels on the container

Fix Host validation failed with HOMEPAGE_ALLOWED_HOSTS

What the error looks like

The value to set, and recreate the container

Secure and run Homepage

Put authentication in front of it

Resource use

FAQ

Host validation and setup

Why does the error stay after setting HOMEPAGE_ALLOWED_HOSTS?

Does HOMEPAGE_ALLOWED_HOSTS need the port?

Can the list contain spaces?

Widgets and Docker

Why does a widget show API Error?

Why are containers with homepage labels not showing up?

Is mounting docker.sock into Homepage safe?

GitLab CE vs Forgejo: Self-Hosted Git on Docker, Measured

Table of contents

The measured numbers

Idle RAM and CPU

Clone the repo and set `.env`