DEV Community: DeployLark

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

Open WebUI Can't Connect to Ollama in Docker: The Fixes

DeployLark — Fri, 16 Oct 2026 06:42:41 +0000

You start Open WebUI, open the model picker, and it's empty. Or the admin connection check fails. Ollama is clearly running, because curl localhost:11434 on the server answers Ollama is running. So why can't Open WebUI see it?

Almost always, Open WebUI is trying to reach Ollama at an address that doesn't lead to Ollama from inside its container. This guide gives you the URL that works for each common setup, a quick test you can run from inside the container, and the saved-settings trap that makes a correct fix look like it did nothing.

Lots of people run this pair. On October 14, 2026, the Open WebUI repository had about 155,600 GitHub stars, and the ollama/ollama image had been pulled more than 186 million times from Docker Hub.

One warning before you start. Open WebUI's roles documentation says: "The very first account created on a fresh installation is automatically assigned the Admin role." If port 3000 is reachable from the internet before you sign up, a stranger can create that account and take over the instance. Docker-published ports also skip UFW, according to Docker's firewall docs. So every example below binds the UI to 127.0.0.1:3000. Reach it through a reverse proxy such as Nginx Proxy Manager or an SSH tunnel (ssh -L 3000:127.0.0.1:3000 you@server), and create your admin account right away.

Short version:

Inside the Open WebUI container, localhost is the container itself, so http://localhost:11434 never reaches Ollama.
Use http://ollama:11434 when both run in one Compose file. With Ollama on a Linux host, use http://host.docker.internal:11434 plus an extra_hosts entry host.docker.internal:host-gateway, and make Ollama listen on more than 127.0.0.1.
Test from inside the container, for example docker exec open-webui curl -s http://ollama:11434. You want Ollama is running.
Changed OLLAMA_BASE_URL and nothing happened? Open WebUI saved the first value in its database. Change it under Admin Panel > Settings > Connections.

The right Ollama URL for your setup

Quick answer

Where Ollama runs	`OLLAMA_BASE_URL`	Also needed
Same Compose file as Open WebUI	`http://ollama:11434` (the service name)	Nothing else
Directly on the Docker host (install script, systemd service)	`http://host.docker.internal:11434`	On Linux, an `extra_hosts` entry `- host.docker.internal:host-gateway`, and Ollama listening on something other than `127.0.0.1`
Another machine	`http://<that-machine-ip>:11434`	Ollama listening on `0.0.0.0` there, port reachable

If you changed OLLAMA_BASE_URL and nothing happened, skip to the section on saved settings.

Why localhost fails inside a container

Each container has its own network namespace. Inside the Open WebUI container, localhost and 127.0.0.1 mean the Open WebUI container itself, not your server. Nothing in that container listens on 11434, so the connection is refused.

The problem reproduces with OLLAMA_BASE_URL=http://localhost:11434 and Ollama running in a separate container. The model list came back as {"models":[]}, with no error in the UI. The Open WebUI log had the real message:

ERROR | open_webui.routers.ollama:send_get_request:88 - Connection error: Cannot connect to host localhost:11434 ssl:default [Connect call failed ('127.0.0.1', 11434)]

In the browser, the model picker just said "No models available":

The connection check in the admin settings did show a problem. Clicking the verify button in the Edit Connection dialog for http://localhost:11434 gave a red "Ollama: Network Problem" message:

Check your own log first:

docker logs open-webui 2>&1 | grep -i "ollama\|11434" | tail

Test the connection from inside the container

Run curl where Open WebUI runs

Don't test from your laptop or the host shell. Test from where Open WebUI actually runs. The official image includes curl:

docker exec open-webui curl -s http://ollama:11434
docker exec open-webui curl -s http://host.docker.internal:11434/api/version

You want Ollama is running for the first and something like {"version":"0.40.4"} for the second. Once it works, you can keep an eye on it with an HTTP monitor in Uptime Kuma pointed at the same URL, from a container that has the same network access. Replace open-webui with your container name. docker ps shows it, and Compose names look like myproject-open-webui-1.

This is the same test from the lab, first in a container set to localhost, then in one set to the service name:

What the curl errors mean

curl: (7) Failed to connect ... Couldn't connect to server: the name resolved, but nothing accepted the connection on that IP and port. Ollama is probably listening on 127.0.0.1 only (see the next section).
Could not resolve host: the name doesn't exist inside the container. On Linux, host.docker.internal needs extra_hosts. A Compose service name only resolves inside the same Compose network.
A hang until timeout: something is dropping packets, usually a firewall.

Ollama installed on the host

This is the setup where you ran Ollama's install script on the server, so Ollama runs as a systemd service, and Open WebUI runs in Docker. It needs two fixes, and most people only make the first.

Add host.docker.internal on Linux

On Docker Desktop (Mac and Windows), host.docker.internal works out of the box. On Linux it doesn't exist unless you add it. Docker's special host-gateway value maps it to the host's address on the default bridge network. On the test box that was 172.17.0.1.

That's why Open WebUI's own quick-start command includes --add-host. Here it is with the port bound to localhost. The docs use -p 3000:8080, which listens on every interface.

openssl rand -hex 32 > ~/.open-webui-secret && chmod 600 ~/.open-webui-secret
docker run -d -p 127.0.0.1:3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY="$(cat ~/.open-webui-secret)" \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:v0.12.0

Or in Compose:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:v0.12.0
    ports:
      - "127.0.0.1:3000:8080"
    volumes:
      - open-webui:/app/backend/data
    extra_hosts:
      - host.docker.internal:host-gateway
    environment:
      - WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}
      # - OLLAMA_BASE_URL=http://host.docker.internal:11434  # this is already the image's default
    restart: unless-stopped

volumes:
  open-webui:

Open WebUI's environment variable reference lists http://host.docker.internal:11434 as the Docker default for OLLAMA_BASE_URL. So for this setup, extra_hosts is often the only thing missing from the compose file.

Put the secret in a .env file next to compose.yaml instead of typing it into the file. Compose reads .env automatically:

echo "WEBUI_SECRET_KEY=$(openssl rand -hex 32)" > .env
chmod 600 .env

Why bother with a fixed key? Without one, Open WebUI generates a key file inside the container. The same reference says that when the container is recreated and that file isn't in a persisted volume, a new key is generated. Every user gets logged out, OAuth sessions stop working, MCP tools fail to decrypt their tokens, and Open WebUI refuses to start if MFA is on (unless MFA_ENCRYPTION_KEY is set).

Run either key-generating line once. Running it again overwrites the key with a new one, and a new key has exactly those effects: everyone is logged out.

Make Ollama listen on more than 127.0.0.1

This one catches nearly everyone with Ollama on the host. Ollama's FAQ puts it plainly: "Ollama binds 127.0.0.1 port 11434 by default." That's loopback only. A request from a container arrives on the Docker bridge address (172.17.0.1), not on loopback, so Ollama never sees it. The Open WebUI connection guide names the same cause first.

To reproduce this, Ollama ran Ollama on the host network bound to 127.0.0.1:11434. From a container with host-gateway set:

$ getent hosts host.docker.internal
172.17.0.1      host.docker.internal
$ curl http://host.docker.internal:11434
curl: (7) Failed to connect to host.docker.internal port 11434 after 0 ms: Couldn't connect to server

The name resolves correctly, but the connection is refused. Meanwhile curl localhost:11434 on the host works fine, which is why this is so confusing.

The fix is to make Ollama listen on more than loopback. For the Linux systemd install, the FAQ's method is:

sudo systemctl edit ollama.service

Add:

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

Then:

sudo systemctl daemon-reload
sudo systemctl restart ollama
ss -ltn | grep 11434     # should now show *:11434 or 0.0.0.0:11434, not 127.0.0.1:11434

After that change, the same curl from the container returned Ollama is running.

Be careful with 0.0.0.0. It means every interface, including your public one, and Ollama's API has no authentication. On a VPS, block 11434 from the internet in your cloud firewall. Or bind Ollama to the Docker bridge address only:

[Service]
Environment="OLLAMA_HOST=172.17.0.1:11434"

That was tested too. Containers on the default bridge and on a Compose network could both reach it through host.docker.internal, and nothing outside the host could. The catch is that localhost:11434 on the host stops working, so the ollama CLI needs OLLAMA_HOST=172.17.0.1:11434 set in your shell as well.

172.17.0.1 belongs to Docker's docker0 bridge, so it only exists while Docker is running. To have systemd start Ollama after Docker at boot, also put After=docker.service under a [Unit] section in the same override.

UFW can also get in the way here. Traffic from a container to 172.17.0.1:11434 is addressed to the host itself, not to a published container port, so UFW's normal input rules apply to it. If your UFW default is deny incoming and requests from the container hang, a rule that allows only Docker's subnets to that port looks like this:

sudo ufw allow from 172.16.0.0/12 to any port 11434 proto tcp

172.16.0.0/12 covers 172.16.0.0 to 172.31.255.255, where all of the test box's Docker networks were (172.17.0.0/16 and 172.27.0.0/16, for example). Yours may differ, so check the subnets you actually have with docker network inspect bridge <your-compose-network> --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}' and adjust the rule.

There's also a shortcut. Open WebUI's connection guide suggests running the container with --network=host, which puts it directly on the host's network. 127.0.0.1 then points at the host, so a loopback-bound Ollama works without changes:

docker run -d --network=host -v open-webui:/app/backend/data \
  -e OLLAMA_BASE_URL=http://127.0.0.1:11434 \
  --name open-webui --restart always ghcr.io/open-webui/open-webui:v0.12.0

With host networking, -p mappings don't apply, and the UI is on port 8080, not 3000. It's a fine shortcut on a single-purpose box, but you give up network isolation, and the app listens on all host interfaces.

Ollama in the same Compose file or on another machine

One Compose file for both

This is the cleanest setup. Containers in the same Compose project share a user-defined network, and Docker resolves service names on those networks. So Open WebUI reaches Ollama at http://ollama:11434. You don't need host.docker.internal, and you don't need to publish Ollama's port to the host.

This is the tested file. The test run published "3000:8080", and the localhost binding shown here is the only change.

services:
  ollama:
    image: ollama/ollama:0.40.4
    restart: unless-stopped
    volumes:
      - ollama:/root/.ollama
    # no "ports:" needed, only Open WebUI talks to it

  open-webui:
    image: ghcr.io/open-webui/open-webui:v0.12.0
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:8080"
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434
      - WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}   # from .env, see above
    volumes:
      - open-webui:/app/backend/data
    depends_on:
      - ollama

volumes:
  ollama:
  open-webui:

docker compose up -d
docker compose exec ollama ollama pull llama3.2   # or any model from Ollama's library that fits your RAM
docker compose exec open-webui curl -s http://ollama:11434

You don't need to change OLLAMA_HOST here. The official ollama/ollama image already sets OLLAMA_HOST=0.0.0.0:11434 (docker image inspect ollama/ollama shows it), so Ollama listens on the container network.

The test box couldn't download from Ollama's model registry, so a small model was loaded (SmolLM2-135M-Instruct) from a GGUF file with ollama create instead of ollama pull. Open WebUI listed it once pointed at http://ollama:11434, and a chat completion through Open WebUI's API worked on CPU.

With http://ollama:11434 set, the connection check in the admin settings passed:

Two things break this setup:

Two separate Compose projects. If Ollama and Open WebUI live in different folders and files, they're on different networks, and ollama won't resolve. Put both services in one file, or attach both to a shared external network (docker network create ai, then declare it as external: true in both files).
The wrong service name. The hostname is the service key under services: (ollama above), not the image name. If you set container_name, that name resolves too.

Don't publish Ollama's port unless you need it. Docker's firewall docs explain that traffic to published container ports is routed in the NAT table before UFW's rules apply. So with -p 11434:11434, Ollama is reachable from the internet even if ufw status says otherwise. If you need it on the host, publish it to loopback only: 127.0.0.1:11434:11434.

Ollama on another machine

Treat it like the host setup, but over the LAN:

On the Ollama machine, set OLLAMA_HOST=0.0.0.0:11434 and restart Ollama.
In that machine's firewall, allow port 11434 from the Open WebUI machine only.
Set the URL to http://192.168.1.50:11434 (your IP) in Admin Panel > Settings > Connections, or with OLLAMA_BASE_URL on a fresh install.
Test with docker exec open-webui curl -s http://192.168.1.50:11434.

You don't need OLLAMA_ORIGINS for this. Open WebUI's backend calls Ollama server to server, and Ollama's FAQ describes OLLAMA_ORIGINS as the setting for extra web origins, such as browser extensions.

If you put Ollama behind its own reverse proxy, Ollama's FAQ shows that it expects the Host header rewritten (proxy_set_header Host localhost:11434; in its nginx example).

Changed OLLAMA_BASE_URL and nothing happened?

Why the old URL sticks

This is the trap that makes people think their fix is wrong. OLLAMA_BASE_URL is a ConfigVar (the docs used to call these PersistentConfig). On first start, Open WebUI saves the value in its database. The env reference says values saved in the database take precedence, so on later starts the environment variable is ignored for that setting.

The test confirmed it. It started with the wrong URL, then changed the compose file to http://ollama:11434 and recreated the container. docker exec ... printenv OLLAMA_BASE_URL showed the new value, but Open WebUI's Ollama config still said:

{"ENABLE_OLLAMA_API":true,"OLLAMA_BASE_URLS":["http://localhost:11434"]}

Three ways to apply the new URL

Change it in the UI. This is the recommended option. Click your avatar, then Admin Panel > Settings > Connections, and edit the Ollama URL there. UI changes are saved to the database and take effect.
Force a reset from the environment once. Add RESET_CONFIG_ON_START=true, run docker compose up -d, check that it worked, then remove the variable. In testing this switched the stored URL to the env value on the next start. It resets the stored config to your environment values, not just this one setting.
Ignore the database for config. ENABLE_PERSISTENT_CONFIG=false makes Open WebUI read env vars on every start. The catch is that settings changed in the admin UI then don't survive a restart.

Deleting the open-webui volume also works, but it deletes your users and chats too. Avoid it.

One more thing came up in testing. Right after adding a model to Ollama, a chat request through Open WebUI returned {"detail":"Model not found"} until the model list had been refreshed. If a new model isn't showing, reload the model list or the page before you blame the connection.

FAQ

Models and connections

Why does Open WebUI show no models?

Open WebUI can't reach Ollama at the URL it has saved, and the model list comes back empty without an error in the UI. Check the container log for Cannot connect to host, then run curl from inside the container as shown above. With Ollama on the host, the usual cause is Ollama listening on 127.0.0.1 only.

Why is OLLAMA_BASE_URL ignored after a restart of the container?

Open WebUI stored the first value in its database, and the stored value wins. Change the URL under Admin Panel > Settings > Connections, or use RESET_CONFIG_ON_START=true for one start.

Can Open WebUI and Ollama run on different machines?

Yes. Make Ollama listen on the network (OLLAMA_HOST=0.0.0.0:11434), allow port 11434 from the Open WebUI machine in the firewall, and point Open WebUI at http://<ollama-ip>:11434. If curl to that address from the Open WebUI container doesn't answer Ollama is running, fix that first.

Access and proxies

How do you open Open WebUI from other devices on your network?

Open WebUI listens on port 8080 inside the container, and -p decides where it appears on the host. This guide binds it to 127.0.0.1:3000, which only the server itself can reach. For other devices, put a reverse proxy in front, or bind to the server's LAN IP (-p 192.168.1.10:3000:8080). With --network=host there's no mapping, so it's port 8080 on every interface. Either way, create the admin account before anyone else can reach the page.

Why do you get "Open WebUI backend required" through an SSH tunnel or proxy?

Open WebUI's connection guide says the page loaded but its request to /api/config on the same address failed. It's usually a port mapping or tunnel that doesn't lead to container port 8080, or a stale cached page. Run curl http://localhost:3000/api/config through the tunnel. JSON back means the backend is reachable. Then try a private window. Behind a proxy, also turn on WebSocket support, which Open WebUI requires from v0.5.0 on, per the same guide. In Nginx Proxy Manager that's the Websockets Support toggle. The n8n reverse proxy guide shows the matching headers for plain nginx.

Originally published on DeployLark: Open WebUI Can't Connect to Ollama in Docker: The Fixes

Install Coolify on a VPS and Deploy Your First App

DeployLark — Fri, 16 Oct 2026 06:42:35 +0000

Coolify is a self-hosted alternative to Heroku, Vercel and Netlify. You install it on your own server, point it at a Git repository, and it builds the app, runs it in Docker, routes a domain to it and gets a certificate. On October 16, 2026, the GitHub repository had about 63,000 stars, and the coollabsio/coolify image had about 3.3 million pulls on Docker Hub. Version 4.0.0, the first stable v4 release, came out on April 27, 2026, and 4.4.6 followed on October 9.

This guide installs Coolify 4.4.6 with the official script, closes the hole a fresh install leaves open, deploys a small Node.js app from a public GitHub repository and adds a domain with HTTPS. Every step ran on Ubuntu 24.04.5 LTS. It ran as a container with its own Docker Engine and systemd, standing in for a VPS, so the server IPs and the HTTPS test differ from a real cloud server, and the guide points out where.

Short version:

Use a fresh Ubuntu LTS server with at least 2 cores, 2 GB of RAM and 10 GB free. Run curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash -s 4.4.6 to install a specific version.
The dashboard is at http://your-server-ip:8000, and the first person to open it becomes root. Create your account right away, or bind port 8000 to 127.0.0.1 with a compose override and use an SSH tunnel.
In the dashboard, pick This machine, then add a Public Git Repository with the right base directory and port, and click Deploy. My first build took 37 seconds.
Add an https:// domain, redeploy, and Traefik requests a Let's Encrypt certificate. That needs a DNS record pointing at the server and port 80 open.
Coolify updates itself every night by default. Turn that off if you want to stay on the version you tested.

What Coolify installs and what you need

What runs on the server

Coolify isn't one container. The installer sets up Docker, then runs Coolify's own containers next to the apps you deploy:

coolify is the dashboard and API. It also serves real-time updates on port 6001 and the web terminal on port 6002.
coolify-db and coolify-redis are PostgreSQL and Redis for Coolify's own data. The 4.4.6 compose file uses postgres:15-alpine and redis:7-alpine.
coolify-proxy is Traefik. It owns ports 80 and 443 and sends each domain to the right app.
coolify-sentinel collects server metrics.

Coolify manages the server it runs on the same way it manages a remote one, over SSH. The installer generates a key, adds it to root's ~/.ssh/authorized_keys, and the dashboard then logs in as root at host.docker.internal. That's why it needs SSH running and root login with a key allowed. Ubuntu's default (PermitRootLogin prohibit-password) is fine.

After the setup below, with one small app deployed, docker stats on the test server showed about 500 MB for Coolify's own containers: 428 MB for coolify, 45 MB for the database, 22 MB for Traefik, 7 MB for Redis and 3 MB for Sentinel. The Railpack build container stayed running after the build and used another 549 MB.

Server requirements and ports

The installation docs ask for 2 CPU cores, 2 GB of RAM and 10 GB of free disk, on amd64 or arm64. They add that Coolify can run on smaller servers, "but this is not recommended", and that builds on the same server as Coolify need watching because high resource use can make the server unresponsive. Ubuntu should be an LTS release. The docs name 20.04, 22.04 and 24.04 and suggest the manual install if the script fails on a non-LTS release. Ubuntu 26.04 isn't on that list yet, which is why the test used 24.04.

Use a fresh server. The script installs Docker Engine itself, rewrites /etc/docker/daemon.json (it keeps a backup of an existing one) and expects ports 80 and 443 to be free. If you already run Nginx Proxy Manager or another proxy on 80 and 443, give Coolify its own server.

The firewall docs list the ports:

Port	Used for
22	SSH
80 and 443	Your apps through Traefik, and Let's Encrypt
8000	The dashboard at `http://server-ip:8000`
6001 and 6002	Real-time updates and the web terminal when you use the IP address

Once the dashboard has its own domain through the proxy, the docs say you can close 8000, 6001 and 6002. Use your hosting provider's firewall for this. On Linux, Docker publishes ports through its own firewall rules, so ufw rules don't stop traffic to a container port.

Install Coolify with the script

Run the installer with a pinned version

SSH in as root or a sudo user and run the script. The plain command from the docs installs the newest release. Adding a version number after bash -s installs that one instead, which the script supports and which is what this guide does:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash -s 4.4.6

To read the script before it runs as root, download it with curl -fsSL https://cdn.coollabs.io/coolify/install.sh -o install.sh, look through it and run sudo bash install.sh 4.4.6.

On the test server it finished in 1 minute 22 seconds. The output, with the server's addresses replaced by an example IP and the private addresses left out:

  1/9  Installing required packages  curl wget git jq openssl            23.1s done
  2/9  Checking OpenSSH server configuration                              0.0s done
  3/9  Installing Docker Engine  v29.9.1                                 22.4s done
  4/9  Configuring Docker daemon  log rotation, address pools            1.4s done
  5/9  Downloading required files from CDN                                0.2s done
  6/9  Setting up environment variables                                   0.0s done
  7/9  Checking SSH key for localhost access  generated new key           0.0s done
  8/9  Pulling images  coolify, postgres, redis, helper               18.6s done
  9/9  Starting Coolify  v4.4.6                                          16.0s done
  Coolify is ready!  Installed in 1m 22s
  Public IPv4   http://203.0.113.10:8000
  ! Back up /data/coolify/source/.env to a safe place outside this server (e.g. a password manager).

Step 4 set log rotation (10 MB files, 3 per container) and an address pool of 10.0.0.0/8 for Docker networks in /etc/docker/daemon.json. If your VPS provider uses addresses in that range, the docs have a custom network option for the installer.

Do what the last line says. /data/coolify/source/.env holds the generated secrets, including APP_KEY, which encrypts values in Coolify's database. The docs say you need it to restore Coolify from a backup.

Lock down port 8000 before anyone else finds it

The dashboard is now live on port 8000 on every interface, and it has no account yet. The installation docs warn: "Anyone who reaches the registration page first can become the instance admin and gain root access to your server." Do one of these right away.

The quick fix is to open http://your-server-ip:8000 and create your account (next section). The safer fix is to stop publishing the dashboard to the internet at all. Coolify reads a compose override from /data/coolify/source/docker-compose.custom.yml and keeps it across upgrades. The installation docs show this example for binding the dashboard to localhost:

services:
  coolify:
    ports:
      - "127.0.0.1:8000:8080"

That didn't work as written on 4.4.6. Compose adds override ports to the existing list instead of replacing it, so the merged config had both 8000 on all interfaces and 127.0.0.1:8000. Applying it failed and left the dashboard stopped:

failed to bind host port 127.0.0.1:8000/tcp: address already in use

Compose's !override tag replaces the whole list. The firewall docs already use it in their version of this override. This one worked, and it also keeps the real-time and terminal ports off the internet:

services:
  coolify:
    ports: !override
      - "127.0.0.1:8000:8080"
      - "127.0.0.1:6001:6001"
      - "127.0.0.1:6002:6002"

Apply it with the command from the docs:

cd /data/coolify/source
sudo docker compose --env-file /data/coolify/source/.env \
  -f docker-compose.yml -f docker-compose.prod.yml -f docker-compose.custom.yml \
  up -d --pull always --remove-orphans --force-recreate

After that, docker port coolify listed all three ports on 127.0.0.1 only. From your own computer, open a tunnel and use the dashboard at http://localhost:8000:

ssh -L 8000:127.0.0.1:8000 -L 6001:127.0.0.1:6001 -L 6002:127.0.0.1:6002 root@your-server-ip

Logging in through that tunnel worked, and real-time updates worked, because the browser reaches 6001 and 6002 through the same tunnel. You can also skip the open registration page completely. The docs describe ROOT_USERNAME, ROOT_USER_EMAIL and ROOT_USER_PASSWORD variables that create the root account during the install.

First login and connecting the server

Create the root account

The first visit shows the sign-up form, with a clear warning:

The password needs at least 8 characters with uppercase, lowercase, a number and a symbol. Use a password manager, and turn on two-factor authentication in your profile once you're in. This account can run commands as root on every server you connect.

Connect this machine

After sign-up, an onboarding wizard asks where to deploy. Pick This machine. Coolify then connects to the server over SSH as root with the key the installer created and checks that Docker works. On the test server, that check passed in a few seconds and the wizard moved on to creating a project. This guide accepts the default, "My first project", with a production environment.

During that step, Coolify also started coolify-proxy, the Traefik container that will receive web traffic. Run sudo docker ps afterwards and you should see coolify, coolify-db, coolify-redis, coolify-proxy and coolify-sentinel.

If the wizard says the server isn't reachable, it's an SSH problem between the Coolify container and the host. Check that sshd is running, that root may log in with a key, and that the public key shown in the wizard is in /root/.ssh/authorized_keys.

Deploy your first app from Git

Pick the repository and build settings

Open your project, go to the production environment and click New resource. Under Applications, the first option is Public Git Repository. It needs no credentials. For private repositories, Coolify offers a deploy key or a GitHub App. The resource picker describes the GitHub App option as the one with automatic webhooks and pull request previews.

This guide uses Coolify's own example repository, https://github.com/coollabsio/coolify-examples, which holds many small apps in subfolders. After Check Repository, Coolify read the default branch and showed the build settings:

Build pack: Railpack was the default on 4.4.6. It detects the language and builds an image without a Dockerfile. Pick Dockerfile or Docker Compose if your repository has one.
Base directory: the folder with the app. Here it's /javascript/runtimes/nodejs, a small Fastify server.
Port: the port the app listens on inside the container. This app uses 3000. Get this wrong and the app builds fine but the domain returns errors.

Click Continue. Coolify creates the application and opens its settings page.

Deploy and check the result

Click Deploy at the top. The Deployment Logs page shows each step:

My first deployment took 37 seconds. Coolify cloned the commit, generated a Railpack build plan, built the image, then did a rolling update: start the new container, then remove the old one. Click Show Debug Logs to see the full build output when a build fails.

Coolify also gave the app a generated sslip.io address. In the lab that address didn't resolve to the server from the browser, so the test went through Traefik with the matching Host header and got the app's response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"hello":"from nodejs #2"}

The app's status read "Running (no healthcheck)". Add a health check under Healthcheck (this app has a /health route) so Coolify can tell when a new version is broken. If you'd rather run a ready-made app than build one, the same New resource page has Docker Compose and Docker image options, so the compose files from the Uptime Kuma, Umami or Paperless-ngx guides are a starting point there too.

Domains, HTTPS and updates

Add a domain with automatic HTTPS

First, create a DNS A record (and an AAAA record if the server has working IPv6) for your domain, pointing at the server. Then open the app's Domains page and click Add Domain. Pick https, enter the host name and the app's port, and save. Coolify then showed the domain twice:

Coolify added the www. version of the domain on its own, and it shows Changes pending. The new domain only takes effect after you redeploy. After clicking Deploy again, Traefik redirected plain HTTP to HTTPS with a 307 Temporary Redirect and served the app on HTTPS.

The certificate step is the part that couldn't be finished in a lab. Traefik asks Let's Encrypt for a certificate using the HTTP challenge on port 80. The test domain ended in .test, which Let's Encrypt never issues for, so the proxy log showed:

Unable to obtain ACME certificate for domains ... Cannot issue for "hello.coolify-lab.test": Domain name does not end with a valid public suffix (TLD)

Meanwhile, Traefik served its fallback certificate, with subject=CN=TRAEFIK DEFAULT CERT. That's the same certificate you'll see on a real domain whenever the certificate request fails. The Let's Encrypt troubleshooting page lists the usual causes: port 80 closed, a third-party proxy such as Cloudflare in front of the domain, or an AAAA record pointing at a server without working IPv6. The docs point to Servers, your server, Proxy, Logs in the dashboard for the proxy log. sudo docker logs coolify-proxy on the server shows the same thing.

Keep Coolify updated

Coolify updates itself by default. On a fresh 4.4.6 install, automatic updates were already on, which matches the default in Coolify's instance settings migration, with an update frequency of 0 0 * * *, daily at midnight in the instance's time zone. It also means a server you installed with 4.4.6 won't stay on 4.4.6.

To control updates yourself, turn off Automatic updates under Settings, then Updates, and update by hand after reading the release notes. The update docs describe two ways: the Upgrade Now button in the dashboard, or the upgrade script with a version number:

curl -fsSL https://cdn.coollabs.io/coolify/upgrade.sh | sudo bash -s 4.4.6

Replace 4.4.6 with the version you want. The docs warn not to rerun install.sh on an existing instance, because it resets ownership and permissions under /data/coolify. They also say to check for running deployments first, since an update can make them fail. Back up /data/coolify/source/.env before any update.

FAQ

Server and setup

How much RAM does Coolify need?

The docs ask for 2 GB of RAM and 2 CPU cores. On the test server, Coolify's own five containers used about 500 MB, and the build container added about 550 MB while it was running. That fits in 2 GB with a small app, but larger builds on the same server need more memory or swap.

Can Coolify run on the same server as your apps?

Yes. That's what the This machine option does, and it's how the test app ran. Coolify's own containers and your apps share the server's CPU and RAM, so a heavy build or a busy app slows the dashboard too. The docs show the same pattern for production, with a 4 GB example server running more than 40 small services next to Coolify, with the apps built elsewhere.

Does Coolify update itself automatically?

Yes, by default. My fresh install had automatic updates on, scheduled daily at midnight. Turn them off under Settings, then Updates, if you want to choose when to upgrade, and use the dashboard or upgrade.sh with a version number.

Dashboard and HTTPS

Why does Coolify say "Cannot connect to real-time service"?

Your browser can't reach port 6001 on the server. This message showed on every page while port 6001 wasn't reachable, and it went away once the browser could connect. Open 6001 and 6002 in the firewall, forward them through your SSH tunnel, or give the dashboard a domain so the proxy carries that traffic over 443.

Why does a Coolify app show TRAEFIK DEFAULT CERT?

Traefik couldn't get a Let's Encrypt certificate for that domain, so it served its built-in fallback. Check the proxy log for the ACME error. In the test the reason was a .test domain. On a real domain, check that DNS points at the server, that port 80 is open, and that no third-party proxy sits in front during the HTTP challenge. Redeploy the app after you change its domain.

How do you open the dashboard on a domain instead of port 8000?

Set Instance Domain under Settings to a domain that points at the server. Coolify team member Cinzya explained: "If you set up the Instance Domain under Settings you don't need to add the port at the end of the URL anymore, as you would access coolify through the proxy." Once that works, the firewall docs say you can close ports 8000, 6001 and 6002.

Originally published on DeployLark: Install Coolify on a VPS and Deploy Your First App