DEV Community: DeployLark

Elasticsearch in Docker: Fix vm.max_map_count Too Low

DeployLark — Sat, 07 Nov 2026 02:46:33 +0000

You paste an Elasticsearch service into Compose, run docker compose up, and the container exits with code 78. The log says max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]. Or the node starts, your app still can't talk to it because localhost:9200 is the app's own loopback, or security returns 401 until you set ELASTIC_PASSWORD.

This guide reproduces those failures with docker.elastic.co/elasticsearch/elasticsearch:9.1.5 and a curlimages/curl:8.16.0 client on the same Compose network, then fixes them. Every error string below comes from that lab run on November 7, 2026. The Stack Overflow question Elasticsearch: Max virtual memory areas vm.max_map_count [65530] is too low had 402,986 views that day, How to increase vm.max_map_count? had 201,093, and Docker - ELK - vm.max_map_count had 72,355.

The short version:

Raise vm.max_map_count on the Docker host, not inside the container. Elastic's current docs recommend 1048576. The bootstrap check text still says at least 262144.
Production-style settings (network.host plus cluster.initial_master_nodes) enforce the check and exit 78. discovery.type=single-node may only WARN and still start.
From another container, use the Compose service name (http://elasticsearch:9200), not localhost.
With security enabled (the 8.x and 9.x default), set ELASTIC_PASSWORD and send Basic auth.
Persist the sysctl in /etc/sysctl.d/ so a reboot does not bring the failure back.

Fix vm.max_map_count bootstrap exit 78

Start with the map. Match the message you see to the cause and the fix:

Confirm the host value and the exact log line

The lab host started at the classic low default:

With a production-style Compose file that binds a non-loopback address and sets cluster.initial_master_nodes, Elasticsearch enforced bootstrap checks and died:

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:9.1.5
    environment:
      - cluster.name=eslab
      - node.name=eslab-node
      - cluster.initial_master_nodes=eslab-node
      - xpack.security.enabled=false
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
      - network.host=0.0.0.0
    ports:
      - "127.0.0.1:9200:9200"

The container status was Exited (78). The log named the check:

bound or publishing to a non-loopback address, enforcing bootstrap checks
ERROR node validation exception
[1] bootstrap checks failed. You must address the points described in the following [1] lines before starting Elasticsearch.
bootstrap check failure [1] of [1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
ERROR: Elasticsearch died while starting up, with exit code 78

Elasticsearch uses memory-mapped files for indices by default. The kernel limit vm.max_map_count caps how many mappings a process may hold. The Increase virtual memory docs say: "If the operating system's default vm.max_map_count value is 1048576 or higher, no configuration change is necessary. If the default value is lower than 1048576, configure the vm.max_map_count parameter to 1048576." The Docker production guide repeats that the setting "must be set to 1048576." The check message still quotes the older floor of 262144. Raise the host to 1048576 so you clear both the check and the current docs.

Raise it on the Docker host, then persist it

You cannot fix this from inside the container. The value lives on the host kernel. On Linux:

sudo sysctl -w vm.max_map_count=1048576
echo 'vm.max_map_count=1048576' | sudo tee /etc/sysctl.d/99-vm-max-map-count.conf
sudo sysctl --system

Verify with cat /proc/sys/vm/max_map_count or sysctl vm.max_map_count. After the lab raised the host to 1048576 and restarted the same Compose file, curl http://127.0.0.1:9200 returned the cluster root JSON with "number" : "9.1.5".

On Docker Desktop for Windows or Mac the knob sits in the Linux VM behind Docker, not in your Windows or macOS shell. Elastic's Docker production page documents wsl -d docker-desktop and .wslconfig paths for WSL2. Change it there, then restart the container.

single-node can WARN and still start

With discovery.type=single-node and the same low host value of 65530, the lab only logged a WARN and the node stayed up with HTTP 200:

WARN max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

That soft path is why some Compose snippets "work" on a laptop and then explode when you switch to production-style networking. Fix the host either way. Do not treat single-node as a substitute for sysctl.

Fix Connection refused to localhost:9200

Don't connect to localhost from the app container

Once Elasticsearch was healthy, a curl client on the same Compose network played the app. With http://127.0.0.1:9200/ it never reached Elasticsearch:

curl: (7) Failed to connect to 127.0.0.1 port 9200 after 0 ms: Could not connect to server

The same client with http://elasticsearch:9200/ got the cluster root JSON. Each container has its own loopback interface, so localhost inside the app is the app. Elasticsearch listens in the elasticsearch service. The Redis guide and the RabbitMQ guide show the same mistake for those brokers.

From the Docker host itself you also need a published port. Without ports, a host tool cannot reach 9200. Add ports: ["127.0.0.1:9200:9200"] if a process on the host must talk HTTP. Other Compose services do not need that mapping.

Wait until the HTTP port is ready

depends_on: [elasticsearch] only waits for the container process to start. Right after a restart in the lab, an immediate curl http://elasticsearch:9200/ still failed to connect. After the healthcheck flipped to healthy, the same request returned 200. Use a healthcheck and condition: service_healthy, the pattern also used in the Umami guide with PostgreSQL:

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:9.1.5
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:9200 >/dev/null || exit 1"]
      interval: 5s
      timeout: 5s
      retries: 24
      start_period: 25s
  app:
    image: your-app:tag
    depends_on:
      elasticsearch:
        condition: service_healthy

Fix 401 missing authentication credentials

Elasticsearch 8.x and 9.x enable security by default. The lab turned it on with xpack.security.enabled=true, set ELASTIC_PASSWORD=LabPassw0rd!, and disabled HTTP TLS for a local Compose network with xpack.security.http.ssl.enabled=false.

Without credentials, curl got:

{"error":{"type":"security_exception","reason":"missing authentication credentials for REST request [/]"},"status":401}

With a wrong password it got unable to authenticate user [elastic]. With -u elastic:LabPassw0rd! the root endpoint returned 200, a document indexed under lab-notes, and a search hit after _refresh. The same password pattern shows up for other databases in the PostgreSQL Docker auth guide and the MongoDB Docker auth guide.

Minimal secure Compose shape used in the lab:

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:9.1.5
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=true
      - ELASTIC_PASSWORD=LabPassw0rd!
      - xpack.security.http.ssl.enabled=false
      - ES_JAVA_OPTS=-Xms512m -Xmx512m
    ports:
      - "127.0.0.1:9200:9200"
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS -u elastic:LabPassw0rd! http://127.0.0.1:9200 >/dev/null || exit 1"]
      interval: 5s
      timeout: 5s
      retries: 30
      start_period: 40s

Put the password in an env file or a secret, not in a public git repo. For production TLS and enrollment tokens, follow Elastic's current Docker docs rather than disabling HTTP SSL.

Working Compose checklist

Set host vm.max_map_count=1048576 and persist it under /etc/sysctl.d/.
Pin the image tag (9.1.5 in this lab, never latest).
Give the node enough heap for your box (ES_JAVA_OPTS=-Xms512m -Xmx512m was enough here).
Bind a data volume to /usr/share/elasticsearch/data.
Point app containers at http://elasticsearch:9200 (or your service name) with credentials when security is on.
Gate app start on condition: service_healthy.
Manage the stack from Portainer if you prefer a UI over the CLI.

The Grafana and Prometheus permission guide is another case where the Docker host, not the Compose YAML alone, owns the fix.

FAQ

What does vm.max_map_count control?

It is the Linux kernel limit on memory-mapped areas per process. Elasticsearch maps index files with mmap, so a low value fails bootstrap or risks mapping errors. See SO 42889241 and Elastic's virtual memory docs.

Why does the container exit with code 78?

Exit 78 is the lab result when bootstrap checks fail under enforced mode. The log line names vm.max_map_count. Fix the host and start again.

Does discovery.type=single-node remove the need for sysctl?

No. In the lab it only logged a WARN and still started. Production-style networking enforced the check and exited 78. Raise the host either way.

Can I set vm.max_map_count inside the Elasticsearch container?

No. Threads such as SO 41064572 hit a read-only /proc from inside the container. Change the Docker host (or the Docker Desktop VM).

Why does my app get connection refused on localhost:9200?

localhost inside the app container is that container. Use the Compose service name and wait for the healthcheck. Same pattern as Redis and RabbitMQ on this site.

How do I set the elastic user password in Compose?

Set ELASTIC_PASSWORD (and keep security enabled). Call the API with -u elastic:$ELASTIC_PASSWORD. Missing or wrong credentials return security_exception with status 401, as captured in the lab.

Redis in Docker: Fix Connection Refused, NOAUTH and MISCONF

DeployLark — Fri, 06 Nov 2026 10:38:55 +0000

You add the official redis image to a Compose file, and your app logs Could not connect to Redis at 127.0.0.1:6379: Connection refused. Or it gets DENIED Redis is running in protected mode, or NOAUTH Authentication required. Or Redis works until its first snapshot, and then every write fails with MISCONF Redis is configured to save RDB snapshots, but it's currently unable to persist to disk.

This guide reproduces each of those errors with redis:8.10.3 in Docker Compose and fixes them. Every error message and log line below comes from that lab run on October 31, 2026, when redis:latest pulled the same 8.10.3 image. These errors are common. The Stack Overflow question MISCONF Redis is configured to save RDB snapshots had 646,097 views that day, Connecting to Redis running in Docker Container from Host machine had 306,329, and the image repo issue Set password and other options via ENV variable has 53 comments.

The short version:

From another container, localhost is that container. Connect to the Compose service name, for example redis.
A mounted stock redis.conf listens on 127.0.0.1 only and turns protected mode on. Change bind and set a password.
The official image ignores REDIS_PASSWORD and REDIS_ARGS. Pass --requirepass on the command line or use a config or ACL file.
redis-cli ping exits 0 on NOAUTH, so a plain ping healthcheck stays healthy. Set REDISCLI_AUTH and check for PONG.
MISCONF and appendonlydir: Permission denied mean the Redis user (uid 999) can't write /data. Fix the ownership instead of turning the check off.

Fix `Connection refused` from another container

Start with the map. Find the message you see in the left column:

The lab started with the smallest possible service, no config file and no published port:

services:
  redis:
    image: redis:8.10.3
    volumes:
      - redis-data:/data

volumes:
  redis-data:

Don't connect to localhost from the app container

A one-off redis:8.10.3 container on the same Compose network played the app:

$ redis-cli -h localhost PING
Could not connect to Redis at localhost:6379: Connection refused
$ redis-cli -h 127.0.0.1 -p 6379 PING
Could not connect to Redis at 127.0.0.1:6379: Connection refused
$ redis-cli -h redis PING
PONG

Each container has its own loopback interface, so localhost inside the app container is the app container. Redis listens in its own container, which Compose names after the service. Set your app's Redis host to redis (or whatever you called the service), for example redis://redis:6379/0. The container name redislab-redis-1 also answered. The MySQL guide shows the same mistake with ERROR 2002 and 2003.

From the Docker host itself, the port was closed too. docker compose ps listed 6379/tcp with no host mapping, and a TCP connect to 127.0.0.1:6379 on the host was refused. Add ports: ["127.0.0.1:6379:6379"] if a tool on the host needs Redis. Keep the 127.0.0.1 part. Other containers on the network don't need ports at all.

Check `bind` in a mounted redis.conf

The image docs show how to start Redis with your own redis.conf. If you start from the upstream file, note that the 8.10.3 version from the redis/redis repository contains bind 127.0.0.1 -::1 and protected-mode yes. Mounted as-is, Redis answers inside its own container and refuses everyone else:

CONFIG GET bind inside the container returned 127.0.0.1 -::1. A published port didn't help either: from the host, redis-cli got Error: Connection reset by peer. This is the accepted answer on the 306,329-view question above: the server only listens on loopback. Change the line to bind * -::*, which the same file describes as "like the default, all available interfaces". That leads straight to the next error.

Fix `DENIED Redis is running in protected mode`

Why the plain image has no protected mode

Without a config file, the image turns protected mode off. In the lab, CONFIG GET protected-mode returned no, bind was * -::* and requirepass was empty. Redis logged this on startup:

WARNING: Redis does not require authentication and is not protected by network restrictions. Redis will accept connections from any IP address on any network interface.

The Docker Official Image docs explain the choice: "For the ease of accessing Redis from other containers via Docker networking, the "Protected mode" is turned off by default. This means that if you expose the port outside of your host (e.g., via -p on docker run), it will be open without a password to anyone."

Set a password instead of turning protected mode off

With a mounted redis.conf you get the upstream default, protected-mode yes. After the bind * -::* change and no password, every client from another container got the long DENIED reply:

The message offers four ways out. Three of them switch protected mode off. Option 4, a password for the default user, is the one to pick. Adding requirepass Lab-Pass-4821 to redis.conf and restarting turned DENIED into NOAUTH Authentication required., and the same client with the password got PONG. The Redis security docs state the design plainly: "Redis is designed to be accessed by trusted clients inside trusted environments." A password plus a private Compose network keeps it that way.

Fix NOAUTH and a password that never applied

Pass the password with `--requirepass`

The first lab file had REDIS_PASSWORD: "ChangeMe123" in environment. Redis started without a password anyway: CONFIG GET requirepass came back empty, and a client from another container ran PING without any auth. The entrypoint script in redis:8.10.3 never reads REDIS_PASSWORD, and it contains no REDIS_ARGS either. A test with REDIS_ARGS: "--requirepass Lab-Pass-4821" also left Redis open, and SET worked without a password. A Stack Overflow answer notes that REDIS_ARGS works with the redis/redis-stack images. The official redis image doesn't support it.

Instead, put the password in .env and let Compose interpolate it into the command:

services:
  redis:
    image: redis:8.10.3
    command: ["redis-server", "--requirepass", "${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}"]

With REDIS_PASSWORD=Lab-Pass-4821 in .env, this produced the errors your app shows when its password is missing or wrong:

NOAUTH Authentication required. means the client sent no password. WRONGPASS invalid username-password pair or user is disabled. means it sent the wrong one. With -a, redis-cli also prints a warning that a password on the command line may not be safe. Set REDISCLI_AUTH instead, or add --no-auth-warning. Without .env, the :? form stops Compose with required variable REDIS_PASSWORD is missing a value, so Redis never starts open by accident.

Two details from the lab. docker inspect shows the password in the container's Args. And the shell form from a 41-vote answer also worked, with redis-server --requirepass "$${REDIS_PASSWORD:?REDIS_PASSWORD variable is not set}" after /bin/sh -c and the password in environment. The $$ stops Compose from replacing the variable itself. That keeps the value out of Args, but it still sits in the container's environment.

The healthcheck has the same blind spot, as the bottom of the screenshot above shows. A healthcheck of ["CMD", "redis-cli", "ping"] against a password-protected Redis stayed healthy. Its last probe printed NOAUTH Authentication required. and exited 0. So depends_on: condition: service_healthy lets your app start against a Redis it can't log in to.

This check reports the truth:

    environment:
      REDISCLI_AUTH: ${REDIS_PASSWORD}
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep -q PONG"]

With the right password the service was healthy. With a wrong REDISCLI_AUTH it turned unhealthy, and the probe log showed the WRONGPASS error.

Use an ACL user when your app wants a username

Some apps ask for a Redis username and password. Define the user in an ACL file:

user default off
user app on >App-Pass-7730 ~app:* +@all -@dangerous

Mount it read-only and start Redis with command: ["redis-server", "--aclfile", "/usr/local/etc/redis/users.acl"]. In the lab, redis-cli --user app --pass App-Pass-7730 PING returned PONG, and a URL like redis://app:App-Pass-7730@redis:6379 worked too. A password without the username failed with WRONGPASS, because the default user is off. The ~app:* key pattern did its job: SET other 1 returned NOPERM No permissions to access a key, and FLUSHALL was refused. Putting the same rules on the command line went wrong in the lab. Written as one list item after --user, Redis exited with Spaces not allowed in ACL usernames. The file avoids that.

Fix MISCONF and append-only Permission denied

Why saves to /data fail

The Redis server runs as uid 999 (redis) in this image. When the container starts as root, the entrypoint fixes the ownership of /data itself. The image docs add a limit: "This adjustment is only performed in basic, default scenarios to avoid interfering with custom or user-specific configurations."

The lab hit that limit with a bind mount, ./data:/data, owned by root and holding a .gitkeep file. The entrypoint printed Notice: Unknown file './.gitkeep' found in data dir. Permissions will not be modified. and left the directory alone. Redis started, and reads and writes worked until the first snapshot:

The default save rule was 3600 1 300 100 60 10000. After a failed BGSAVE, the log said Failed opening the temp RDB file temp-51.rdb (in server root dir /data) for saving: Permission denied, INFO persistence showed rdb_last_bgsave_status:err, and the next SET returned MISCONF. Reads still worked, as GET a returned 1.

With --appendonly yes the same mount fails at once. The container exited with code 1 after Can't open or create append-only dir appendonlydir: Permission denied. A user: "1000:1000" line on a fresh named volume, which the image creates owned by 999, failed with the same message.

Every start in the lab logged WARNING Memory overcommit must be enabled!, because the host had vm.overcommit_memory set to 0. The warning says it can make a background save fail under low memory, and it names the fix: "To fix this issue add 'vm.overcommit_memory = 1' to /etc/sysctl.conf and then reboot or run the command 'sysctl vm.overcommit_memory=1' for this to take effect." This is a host setting. docker run --sysctl vm.overcommit_memory=1 failed with sysctl 'vm.overcommit_memory=1' is not allowed, and the container read the host value of 0. Set it on the Docker host. A permission error, not this warning, caused every MISCONF in this lab.

Fix ownership, don't switch off the check

The 533-vote answer on the MISCONF question runs config set stop-writes-on-bgsave-error no and adds that you should check why the save failed. The lab shows why that matters. After that command, SET worked again, but the next BGSAVE still ended with rdb_last_bgsave_status:err. Nothing reached the disk.

Fix the directory instead. Any of these worked in the lab:

Change the owner to the Redis user with sudo chown -R 999:999 ./data and restart. Writes worked, BGSAVE returned rdb_last_bgsave_status:ok and dump.rdb appeared with owner 999.
Run the command from the image docs, docker run --rm -v /your/host/path:/data redis:8.10.3 chown -R redis:redis /data. It set the same root-owned folder to 999:999.
Remove the unknown files, so the entrypoint fixes the folder on its own. With .gitkeep gone it changed the owner to 999 and created appendonlydir.
If you run Redis with user: "1000:1000", make the volume belong to that user, for example docker run --rm -v <volume>:/data alpine:3.22 chown 1000:1000 /data. After that the AOF service started and aof_last_write_status:ok.

The Grafana and Prometheus guide walks through the same uid mismatch with two other images.

A Redis Compose file that avoids these errors

compose.yaml and .env

This file ran verbatim in the lab:

services:
  redis:
    image: redis:8.10.3
    restart: unless-stopped
    command:
      - redis-server
      - --requirepass
      - ${REDIS_PASSWORD:?set REDIS_PASSWORD in .env}
      - --appendonly
      - "yes"
    environment:
      REDISCLI_AUTH: ${REDIS_PASSWORD}
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep -q PONG"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 5s

  app:
    image: redis:8.10.3
    depends_on:
      redis:
        condition: service_healthy
    environment:
      REDISCLI_AUTH: ${REDIS_PASSWORD}
    command: ["redis-cli", "-h", "redis", "INCR", "app:visits"]

volumes:
  redis-data:

REDIS_PASSWORD=f3Kq9-Lab-Only-2Vx7

Replace app with your real service and give it the host redis and the same password. The named volume belongs to the Redis user from the start, AOF is on, and the healthcheck only passes on a real PONG. Drop the ports block if nothing on the host needs Redis. If your password contains $, read the dollar sign section of the MySQL guide first, because Compose interpolates .env the same way. The Umami guide uses the same service_healthy pattern with PostgreSQL.

Check it

$ docker compose up -d
 Container redisfinal-redis-1  Waiting
 Container redisfinal-redis-1  Healthy
 Container redisfinal-app-1  Started
$ docker compose logs --no-log-prefix app
1
$ docker compose run --rm app
2
$ docker compose exec redis redis-cli INFO persistence | grep -E 'aof_enabled|aof_last_write_status'
aof_enabled:1
aof_last_write_status:ok
$ docker compose restart redis
$ docker compose exec redis redis-cli GET app:visits
2

From the host, redis-cli -h 127.0.0.1 PING without a password got NOAUTH Authentication required., and with REDISCLI_AUTH set it read the counter. The value survived the restart. Paperless-ngx uses a Redis-compatible broker in the same way, as the Paperless-ngx guide shows with Valkey.

FAQ

Connection errors

Why does Redis refuse connections between Docker Compose containers?

Usually the app connects to localhost or 127.0.0.1, which is the app's own container. Use the service name, such as redis. If you mounted your own redis.conf, check its bind line. The stock file has bind 127.0.0.1 -::1, so other containers get Connection refused until you change it.

How do I connect to Redis in Docker from the host machine?

Publish the port, for example ports: ["127.0.0.1:6379:6379"], and connect to 127.0.0.1:6379. Without ports, the host connection is refused. If Redis uses the stock redis.conf with bind 127.0.0.1 -::1, the published port still fails. In the lab, redis-cli on the host got Error: Connection reset by peer.

How do I fix `DENIED Redis is running in protected mode` in Docker?

Set a password with requirepass or define an ACL user. Protected mode only blocks remote clients when the default user has no password. The plain image starts with protected mode off, so this error usually comes from a mounted redis.conf.

Password and persistence errors

How do I set a Redis password with an environment variable in docker-compose?

The official image doesn't read REDIS_PASSWORD. Put the value in .env and pass it in command, as in ["redis-server", "--requirepass", "${REDIS_PASSWORD}"]. Check with CONFIG GET requirepass or a PING without a password, which should return NOAUTH.

How do I use a Redis username with a password in docker-compose?

Create an ACL file with user default off and a line such as user app on >password ~app:* +@all, mount it, and start Redis with --aclfile. Clients then log in with --user and --pass, or a URL like redis://app:password@redis:6379.

How do I fix `MISCONF Redis is configured to save RDB snapshots` in Docker?

Read the Redis log for the reason. In Docker it is often Permission denied on /data. Change the data directory's owner to uid 999, or to the user you set with user:, then restart. Setting stop-writes-on-bgsave-error no hides the error but doesn't save anything.

MongoDB in Docker: Fix Authentication Failed and Init Scripts

DeployLark — Fri, 06 Nov 2026 10:35:54 +0000

You set MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD in Compose, start the official mongo image, and your app logs MongoServerError: Authentication failed. The password is right. You can see it in the container's environment. Or you changed the password in .env, recreated the container, and now nothing can log in. Or the user your docker-entrypoint-initdb.d script should create never shows up.

This guide reproduces each of those failures with mongo:9.0.4 in Docker Compose and fixes them. Every error and log line below comes from that lab run on November 1, 2026, when mongo:latest pointed to the same 9.0.4 image digest. The questions behind these errors get a lot of traffic. On Stack Overflow, How can I create a database for a MongoDB container on startup? had 325,066 views that day and How to enable authentication on MongoDB through Docker? had 316,972. The image repo issue Initialization of a user defined database, username, and password using environment variables has 29 comments.

The short version:

From another container, localhost is that container. Connect to the Compose service name, for example mongodb://mongo:27017.
The root user from MONGO_INITDB_ROOT_USERNAME lives in the admin database. If your connection string names another database, add ?authSource=admin.
The MONGO_INITDB_* variables and the /docker-entrypoint-initdb.d scripts only run when /data/db is empty. Changing them later does nothing. Change the password with changeUserPassword() or run the script by hand.
Percent-encode @ : / ? # [ ] $ in the password part of the connection string.
docker logs on the MongoDB container tells you why a login failed. Look for Failed to authenticate.

Fix Authentication failed with MONGO_INITDB_ROOT_USERNAME

Start with the map. Find the message you see in the left column:

The lab started with the smallest Compose file that turns on authentication:

services:
  mongo:
    image: mongo:9.0.4
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_ROOT_PASSWORD}
    volumes:
      - mongo-data:/data/db

volumes:
  mongo-data:

MONGO_ROOT_PASSWORD=Lab-Pass-4821

On the first start, the entrypoint ran a temporary mongod bound to 127.0.0.1, created the root user, shut it down and then started the real server as mongod --auth --bind_ip_all. A one-off mongo:9.0.4 container on the same Compose network played the app and ran mongosh 2.14.0. mongosh is built on the Node.js driver (the server log named driver 7.5.0), so Node.js apps get the same error names.

Connect to the service name, not localhost

client$ mongosh 'mongodb://localhost:27017' --eval 'db.runCommand({ping:1})'
MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27017
client$ mongosh 'mongodb://mongo:27017' --eval 'db.runCommand({ping:1})'
{ ok: 1 }

Inside the app container, localhost points back at the app itself. Nothing listens on port 27017 there, so the connection is refused. Use the service name from your Compose file. The same rule applies to MySQL and Redis, as the MySQL guide and the Redis guide show.

Note that ping worked without a password. MongoDB lets unauthenticated clients run ping, but a real query failed with MongoServerError: Command find requires authentication. That message means you connected without credentials. Authentication failed. means you sent credentials and the server rejected them.

Add authSource=admin for the root user

When the password is right and the login still fails, check the database in the connection string first. Here it named the app database, and the right password failed:

client$ mongosh 'mongodb://root:Lab-Pass-4821@mongo:27017/appdb' --eval 'db.items.insertOne({a:1})'
MongoServerError: Authentication failed.
client$ mongosh 'mongodb://root:Lab-Pass-4821@mongo:27017/appdb?authSource=admin' --eval 'db.items.insertOne({a:1}).acknowledged'
true

A MongoDB user belongs to the database where it was created. The Docker Hub page for the image says MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD are for "creating a simple user with the role root in the admin authentication database". The MongoDB connection string docs describe authSource as the "Database name associated with the user's credentials. Defaults to defaultauthdb if specified, otherwise defaults to admin." So /appdb in the path made the driver look for root in appdb. Without a database in the path, as in mongodb://root:Lab-Pass-4821@mongo:27017/, the login worked because the default was admin.

The server log shows the difference between a wrong database and a wrong password. The client gets the same message for both:

$ docker logs mongolab-mongo-1 2>&1 | grep '"Failed to authenticate"'
Failed to authenticate user=root db=appdb error=UserNotFound: Could not find user "root" for db "appdb"
Failed to authenticate user=root db=admin error=AuthenticationFailed: SCRAM authentication failed, storedKey mismatch

The raw lines are JSON. The lab filtered them with jq to show attr.user, attr.db and attr.error. UserNotFound means fix the authSource or the user name. storedKey mismatch means the user exists and the password is wrong.

Fix a password that changed in .env but not in MongoDB

Why MONGO_INITDB_ROOT_PASSWORD is ignored on restart

The lab changed MONGO_ROOT_PASSWORD in .env from Lab-Pass-4821 to New-Pass-7310 and ran docker compose up -d --force-recreate. The new container had the new value in its environment, but the new password failed:

The init step never ran. The entrypoint checks /data/db for files such as WiredTiger, journal and storage.bson, and skips initialization when any of them exist. The Docker Hub page says it directly: "Do note that none of the variables below will have any effect if you start the container with a data directory that already contains a database: any pre-existing database will always be left untouched on container startup."

So the old password stays valid until you change it inside MongoDB.

Change the password with mongosh

client$ mongosh 'mongodb://root:Lab-Pass-4821@mongo:27017/?authSource=admin' \
          --eval 'db.getSiblingDB("admin").changeUserPassword("root", "New-Pass-7310")'
{ ok: 1 }
client$ mongosh 'mongodb://root:New-Pass-7310@mongo:27017/?authSource=admin' \
          --eval 'db.runCommand({connectionStatus:1}).authInfo.authenticatedUsers'
[ { user: 'root', db: 'admin' } ]

If you lost the old password, or the volume only holds test data, docker compose down -v deletes the volume. In the lab, the next start ran the init step again and the new .env password worked. That also deletes every database in the volume.

A related trap: the lab started a volume with no auth variables, wrote data, then added MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD. The entrypoint still added --auth (the process ran as mongod --auth --bind_ip_all), but it did not create the user, because the volume was not empty. Every login failed with UserNotFound: Could not find user "root" for db "admin", and queries without credentials failed with Command aggregate requires authentication. MongoDB's localhost exception "allows you to create the first user or role in the system after enabling access control." It only works from inside the container, so the fix ran there:

docker exec mongolate-mongo-1 sh -c 'mongosh --quiet admin --eval "db.createUser({user: process.env.MONGO_INITDB_ROOT_USERNAME, pwd: process.env.MONGO_INITDB_ROOT_PASSWORD, roles: [\"root\"]}).ok"'

It printed 1, and the root login worked. The old data was still there.

Fix docker-entrypoint-initdb.d scripts that don't run

Create the app user in the right database

Most apps should not log in as root. The usual pattern is a script in /docker-entrypoint-initdb.d that creates an app user. The lab mounted this file:

// Runs once, against MONGO_INITDB_DATABASE, only when /data/db is empty
db.createUser({
  user: "app",
  pwd: process.env.APP_DB_PASSWORD,
  roles: [{ role: "readWrite", db: "appdb" }],
});
db.items.insertOne({ seeded: true });

With MONGO_INITDB_DATABASE: appdb and APP_DB_PASSWORD passed into the mongo service, the log showed running /docker-entrypoint-initdb.d/01-create-app-user.js and MongoDB init process complete; ready for start up. The .js file read the password with process.env, so it never sat in the script.

Now the authSource rule flips. The script ran in appdb, so the app user lives in appdb, not in admin:

client$ mongosh 'mongodb://app:App-Pass-5532@mongo:27017/appdb?authSource=admin' --eval 'db.items.countDocuments()'
MongoServerError: Authentication failed.
client$ mongosh 'mongodb://app:App-Pass-5532@mongo:27017/appdb' --eval 'db.items.countDocuments()'
1

Copying ?authSource=admin from a root example into an app user's connection string breaks it. Set authSource to the database the script ran in, or leave it out when that database is already in the path. The readWrite role on appdb also limits the user. A write to another database failed with MongoServerError: not authorized on other to execute command.

MONGO_INITDB_DATABASE only picks the database the .js scripts run against. The Docker Hub page notes that "MongoDB is fundamentally designed for "create on first use", so if you do not insert data with your JavaScript files, then no database is created." The insertOne line in the script creates appdb.

Run a new script on an existing volume

The lab then added 02-create-report-user.js and recreated the container on the same volume. The script did not run, and the user did not exist:

Init scripts follow the same rule as the root variables. They run once, on the first start of an empty /data/db. You don't need to delete the volume to apply a new one. Run it with mongosh inside the container, logged in as root, against the same database the entrypoint would use:

docker exec mongoinit-mongo-1 sh -c 'mongosh --quiet -u root -p "$MONGO_INITDB_ROOT_PASSWORD" \
  --authenticationDatabase admin appdb /docker-entrypoint-initdb.d/02-create-report-user.js'

After that, the report user logged in to appdb. The entrypoint also runs .sh files from the same folder, and ignores any other extension. On a fresh volume with no scripts, the log shows ignoring /docker-entrypoint-initdb.d/*.

Fix MongoParseError for passwords with special characters

Percent-encode the password in the connection string

The lab set the root password to p@ss:w/rd#1. The Compose value worked, because the entrypoint passes it to createUser and never builds a URL. The connection string was the problem:

client$ mongosh 'mongodb://root:p@ss:w/rd#1@mongo:27017/?authSource=admin' --eval 1
MongoRuntimeError: Unable to parse ss:w with URL
client$ mongosh 'mongodb://root:pa:ss@mongo:27017/?authSource=admin' --eval 1
MongoParseError: Password contains unescaped characters
client$ mongosh 'mongodb://root:pa@ss@mongo:27017/?authSource=admin' --eval 1
MongoParseError: Invalid connection string

The MongoDB docs say that if the username or password includes $ : / ? # [ ] @, "those characters must be converted using percent encoding". Python's urllib.parse.quote("p@ss:w/rd#1", safe="") printed p%40ss%3Aw%2Frd%231, and that version logged in. Put the encoded form only in the connection string. The MONGO_INITDB_ROOT_PASSWORD value stays as typed. If the password contains $, Compose also treats it as a variable, which the MySQL guide covers.

Connect from the host through a published port

Without a ports entry, nothing on the host can reach MongoDB. The lab published 127.0.0.1:27018:27017, and mongosh with host networking connected to 127.0.0.1:27018 and printed 9.0.4. Port 27017 on the host was refused, because only 27018 was published. Binding to 127.0.0.1 keeps the port off the network, so only the host itself can connect.

A MongoDB Compose file that avoids these errors

compose.yaml, .env and the secret file

This file ran verbatim in the lab:

services:
  mongo:
    image: mongo:9.0.4
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD_FILE: /run/secrets/mongo_root_password
      MONGO_INITDB_DATABASE: appdb
      APP_DB_PASSWORD: ${APP_DB_PASSWORD}
    secrets:
      - mongo_root_password
    volumes:
      - mongo-data:/data/db
      - ./init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  app:
    image: mongo:9.0.4
    depends_on:
      mongo:
        condition: service_healthy
    environment:
      MONGODB_URI: mongodb://app:${APP_DB_PASSWORD}@mongo:27017/appdb?authSource=appdb
    command: ["sh", "-c", "mongosh --quiet \"$$MONGODB_URI\" --eval 'db.items.countDocuments()'"]

secrets:
  mongo_root_password:
    file: ./secrets/mongo_root_password

volumes:
  mongo-data:

APP_DB_PASSWORD=App-Pass-5532

./secrets/mongo_root_password holds the root password, and ./init/01-create-app-user.js is the script from above. The _FILE suffix is documented on Docker Hub for both root variables. With it, docker inspect on the container did not show the root password. Replace app with your real service and give it the MONGODB_URI. Keep APP_DB_PASSWORD URL-safe or percent-encode it in the URI.

The healthcheck only proves that mongod answers, since ping needs no login. It doesn't test the app's password. That is enough for depends_on. A wrong app password still shows up in the app's own log as Authentication failed. The Umami guide uses the same service_healthy pattern with PostgreSQL.

Check it

<code>text $ docker compose up -d Container mongofinal-mongo-1 Started Container mongofinal-mongo-1 Healthy Container mongofinal-app-1 Started $ docker compose ps -a --format '{{.Service}} {{.Status}}' app Exited (0) 7 seconds ago mongo Up 18 seconds (healthy) $ docker compose logs --no-log-prefix app 1 $ docker compose restart mongo $ docker compose run --rm app 1 </code>

The log showed running /docker-entrypoint-initdb.d/01-create-app-user.js once, on the first start. Root logged in with the password from the secret file and ?authSource=admin. After the restart, the seeded document was still there. Keep the image pinned to an exact version such as mongo:9.0.4, so a restart never pulls a new major version onto your data volume. The PostgreSQL 17 to 18 guide shows what a planned major upgrade of a database volume looks like.

FAQ

Login errors

Why does MongoDB in Docker say Authentication failed when the password is right?

Check which database the user lives in. The root user from MONGO_INITDB_ROOT_USERNAME is in admin, so a URI like mongodb://root:pass@mongo:27017/appdb needs ?authSource=admin. Run docker logs on the MongoDB container. UserNotFound points to the database, storedKey mismatch to the password.

What is the default username and password for the MongoDB Docker image?

There is none. Without MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD, the lab's server ran without --auth, logged "Access control is not enabled for the database" and accepted writes without a login. If you set only one of the two, the container exits with error: missing 'MONGO_INITDB_ROOT_USERNAME' or 'MONGO_INITDB_ROOT_PASSWORD'.

How do I connect to MongoDB in Docker from the host?

Publish the port, for example ports: ["127.0.0.1:27017:27017"], and connect to 127.0.0.1 with ?authSource=admin for the root user. Without a published port, the host can't reach the container.

Setup and init scripts

Why are my docker-entrypoint-initdb.d scripts not running?

The volume already holds a database. The entrypoint runs the scripts only when /data/db has no data files. Run the script with mongosh inside the container, or delete the volume if the data doesn't matter. Only .js and .sh files run.

How do I create a database and user for a MongoDB container on startup?

Set MONGO_INITDB_DATABASE and mount a .js file into /docker-entrypoint-initdb.d that calls db.createUser() and inserts one document. MongoDB creates a database on the first write. The app then connects to that database without authSource=admin.

How do I change the MongoDB root password in Docker?

Changing MONGO_INITDB_ROOT_PASSWORD has no effect on an existing volume. Log in with the old password and run db.getSiblingDB("admin").changeUserPassword("root", "new-password"), then update .env to match.

PostgreSQL in Docker: Fix Password Authentication Failed

DeployLark — Fri, 06 Nov 2026 10:32:53 +0000

Your Postgres container runs, but every login fails with password authentication failed for user "postgres". Or psql inside the container says role "root" does not exist. Or the container exits right away with Database is uninitialized and superuser password is not specified. The password in your .env file looks right, and that is the trap.

This guide reproduces each of these errors with the official postgres:18.6 image in Docker Compose and fixes them. Every error message below comes from that lab run on November 3, 2026, with a small Node.js client (pg 8.23.1) standing in for your app. Most of them have one root cause: the image reads its POSTGRES_* variables only once, the first time it creates the database.

These questions get a lot of traffic. On Stack Overflow, Connecting to Postgresql in a docker container from outside had 986,699 views on November 3, 2026, and postgres with docker compose gives FATAL: role "root" does not exist error had 188,086.

The short version:

Changing POSTGRES_PASSWORD after the first start does nothing. The log says Skipping initialization. Change the password with ALTER ROLE ... PASSWORD through docker compose exec, or delete the volume if the data is disposable.
role "root" does not exist means psql or pg_isready ran without -U. Pass -U with the user from POSTGRES_USER. If you set POSTGRES_USER, there is no postgres role at all.
superuser password is not specified means the password reached the container empty. Check for an unset .env variable or a $ in the password, and use ${DB_PASSWORD:?} so Compose stops before it starts anything.
From another container, connect to the service name, not localhost, and wait for a healthcheck with condition: service_healthy. URL-encode special characters in connection strings.

Fix `password authentication failed` after changing POSTGRES_PASSWORD

You started the stack once, then changed the password in .env or compose.yaml, recreated the container, and now nothing can log in with the new password.

Why the new password never applied

The official image runs initdb only when the data directory is empty. The image documentation says it plainly: "the Docker specific variables will only have an effect if you start the container with a data directory that is empty." An existing database is left as it is.

In the lab, the volume was first created with DB_PASSWORD=first-secret. After changing .env to second-secret and running docker compose up -d --force-recreate, the log showed:

PostgreSQL Database directory appears to contain a database; Skipping initialization

The container's environment had the new value, POSTGRES_PASSWORD=second-secret. The database still had the old one. A login with the new password failed with password authentication failed for user "postgres" (SQLSTATE 28P01), and the server log named the pg_hba.conf rule the connection matched:

FATAL:  password authentication failed for user "postgres"
DETAIL:  Connection matched file "/var/lib/postgresql/18/docker/pg_hba.conf" line 128: "host all all all scram-sha-256"

The same rule explains why init scripts seem to be ignored. A file mounted into /docker-entrypoint-initdb.d after the first start never ran, and select count(*) from notes returned relation "notes" does not exist.

Change the password inside the database

The image's pg_hba.conf trusts connections over the local Unix socket, so docker compose exec gets you in without the password. Set the new password with SQL:

docker compose exec db psql -U postgres -c "ALTER ROLE postgres WITH PASSWORD 'second-secret'"

It printed ALTER ROLE. The app logged in with second-secret right away, without a restart, and first-secret stopped working. Keep .env and the database in sync from now on, because the app reads the new value from .env while the database only changes through SQL.

If the data is disposable, delete the volume instead. docker compose down -v removes the project's volumes, and with them all data. On the next up, the log showed running /docker-entrypoint-initdb.d/01-notes.sql, the notes table existed, and the new password worked. The MySQL and MongoDB guides cover the same first-start rule for those images.

Fix `role "root" does not exist` and `role "postgres" does not exist`

The second family of errors comes from the user name, not the password.

psql and pg_isready inside the container

docker compose exec db psql runs as root inside the container. Without -U, psql uses that operating system user as the database user:

psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL:  role "root" does not exist

The top answer on the Stack Overflow question, by richyen, puts it this way: "If you don't specify the PGUSER environment variable, then psql will assume you want to use the current OS user as your database user name." Pass the user, as in psql -U postgres.

The same thing happens in healthchecks. With test: ["CMD", "pg_isready"], the container still showed (healthy), because pg_isready reported the server as up even though the role was rejected. But the server log got a new FATAL: role "root" does not exist line every 5 seconds, one per check. With ["CMD", "pg_isready", "-U", "app", "-d", "app"], the log had 0 FATAL lines over the next 20 seconds.

POSTGRES_USER replaces the postgres role

When you set POSTGRES_USER, the image creates that user as the superuser and does not create postgres. With POSTGRES_USER: app and no POSTGRES_DB, the lab cluster had one role, app (Superuser, Create role, Create DB, Replication, Bypass RLS), and a database also named app, matching the docs: the variable creates "the specified user with superuser power and a database with the same name."

So these failed:

$ docker compose exec db psql -U postgres
... FATAL:  role "postgres" does not exist
$ docker compose exec db psql -U app -d appdb
... FATAL:  database "appdb" does not exist

Over TCP, the error is less helpful. Logging in as postgres from the app with the app password returned password authentication failed for user "postgres", which sends you after the wrong problem. Only the server log told the truth: DETAIL: Role "postgres" does not exist. Check the server log before you reset any password.

Use the user and database you set, in psql, in the healthcheck and in the app's connection string. If an app insists on a postgres role or another database, create them with SQL: CREATE ROLE postgres WITH LOGIN SUPERUSER PASSWORD '...' and createdb -U app appdb both worked in the lab, and the app then logged in to appdb as postgres.

Fix `Database is uninitialized and superuser password is not specified`

This one stops the container on its first start. It exited with code 1 and printed:

Error: Database is uninitialized and superuser password is not specified.
       You must specify POSTGRES_PASSWORD to a non-empty value for the
       superuser. For example, "-e POSTGRES_PASSWORD=password" on "docker run".

The message goes on to offer POSTGRES_HOST_AUTH_METHOD=trust, which lets anyone connect without a password. Don't use that to get past this error. If you did set a password, check how it gets into the container.

Unset .env variables and dollar signs

In the lab, the compose file had POSTGRES_PASSWORD: ${DB_PASSWORD} and there was no .env file next to it. Compose printed a warning and started the container anyway, with an empty password:

level=warning msg="The \"DB_PASSWORD\" variable is not set. Defaulting to a blank string."

A $ inside a password does something similar. Compose treats it as the start of a variable. With POSTGRES_PASSWORD: pa$word42 written straight into compose.yaml, Compose warned that word42 was not set, and the container got POSTGRES_PASSWORD=pa. The cluster was created with the password pa, so pa$word42 failed with password authentication failed and pa worked. The Compose interpolation docs give the fix: "You can use a $$ (double-dollar sign) when your configuration needs a literal dollar sign." With pa$$word42, the container got pa$word42.

Make Compose fail before it starts anything

Replace ${DB_PASSWORD} with ${DB_PASSWORD:?set DB_PASSWORD in .env}. With no .env file, docker compose up -d stopped right away and started nothing:

error while interpolating services.db.environment.POSTGRES_PASSWORD: required variable DB_PASSWORD is missing a value: set DB_PASSWORD in .env

This matters more than it looks. An empty password stops Postgres on the first start, but the pa case above did not stop anything. It created a database with the wrong password, and the variable rule from the first section then kept that password for good.

Fix connection refused and pg_hba errors from other containers

If the password and user are right and the app still can't connect, look at the address, the timing and the connection string.

localhost, published ports and startup order

Inside a container, localhost is that container. An app with @localhost:5432 in its URL got connect ECONNREFUSED ::1:5432, connect ECONNREFUSED 127.0.0.1:5432. Use the Compose service name, such as db, as the host. node-postgres defaults to PGHOST=localhost when you set no host, so always set it.

From the host machine, the container is only reachable if you publish the port. Without ports, psql -h 127.0.0.1 -p 5432 on the host got Connection refused. With ports: - "127.0.0.1:5433:5432", the host connected on port 5433 and read the data. Binding to 127.0.0.1 keeps the port off the host's other network interfaces.

Timing is the other trap. With depends_on: - db and no condition, the app started as soon as the database container did. On a fresh volume with an init script, it failed with connect ECONNREFUSED 172.28.0.2:5432 and exited. During the first start, the entrypoint runs a temporary server with listen_addresses='', so nothing listens on TCP until the init scripts are done. Starting the app again a few seconds later worked. The fix is a healthcheck plus condition: service_healthy, shown in the Compose file below. The Grafana and Prometheus guide and the Redis guide run into the same localhost mistake.

Passwords in URLs and pg_hba.conf entries

Connection strings are URLs, so @, #, / and : in a password break them. With the password p@ss#word/1 pasted into postgres://app:p@ss#word/1@db:5432/app, the parser read the password as p, the host as ss and no database at all. Encode the password first. node -p 'encodeURIComponent("p@ss#word/1")' printed p%40ss%23word%2F1, and the URL with that value logged in. Or skip the URL and pass PGHOST, PGUSER, PGPASSWORD and PGDATABASE as separate variables, as the Compose file below does.

You only see no pg_hba.conf entry if you replaced the image's default pg_hba.conf, which ends with host all all all scram-sha-256 and allows every address with a password. A custom file that only allowed 127.0.0.1/32 over TCP rejected the app container:

no pg_hba.conf entry for host "172.28.0.4", user "postgres", database "postgres", no encryption

Add a line for the Docker network. The pg_hba.conf docs describe samenet as "any address in any subnet that the server is directly connected to", which covers the Compose network. After adding host all all samenet scram-sha-256 and running SELECT pg_reload_conf(), the same login worked without a restart. If you carried a custom file over from an upgrade, the PostgreSQL 17 to 18 upgrade guide covers the other places it can break.

A PostgreSQL Compose file that avoids these errors

This file puts the fixes together. It ran verbatim in the lab. The app service is the small Node.js test client from the lab. Replace its image, command and volume with your own app and keep the environment and depends_on parts.

The compose file

Create .env next to it with a random password. Hex characters need no escaping in Compose or in URLs:

printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env

services:
  db:
    image: postgres:18.6
    restart: unless-stopped
    environment:
      POSTGRES_USER: app
      POSTGRES_DB: app
      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
    volumes:
      - pgdata:/var/lib/postgresql
      - ./initdb:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "app", "-d", "app"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 30s

  app:
    image: node:24.22.2-alpine
    working_dir: /app
    command: node pgtest.mjs
    environment:
      PGHOST: db
      PGUSER: app
      PGDATABASE: app
      PGPASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
    volumes:
      - ./app:/app:ro
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:

The volume is mounted at /var/lib/postgresql, the path that the 18 images expect. Both services read the same DB_PASSWORD, so there is one place to change it. If you change it later, also run the ALTER ROLE command from the first section, or the app gets 28P01 again.

Check that it works

Run docker compose up -d. Compose waited for the database before it started the app:

 Container pgfinal-db-1  Waiting
 Container pgfinal-db-1  Healthy
 Container pgfinal-app-1  Starting
 Container pgfinal-app-1  Started

The app printed OK app app PostgreSQL 18.6 (Debian 18.6-1.pgdg13+2), and the log showed running /docker-entrypoint-initdb.d/01-schema.sql. After docker compose restart db and docker compose run --rm app, the app connected again, and the database log had 0 FATAL lines for the whole run. For a full app stack on this pattern, see the Umami with PostgreSQL guide.

FAQ

Passwords and users

Why does Postgres in Docker say password authentication failed when the password is right?

Either the database still has the password from its first start, or the user doesn't exist. Look at the server log with docker compose logs db. Skipping initialization at startup means your new POSTGRES_PASSWORD was ignored. DETAIL: Role "..." does not exist. means the user name is wrong.

How do I use a new password from .env without removing the volume?

Run docker compose exec db psql -U <user> -c "ALTER ROLE <user> WITH PASSWORD '<new>'". It works over the local socket without the old password and takes effect right away. Then keep the same value in .env for the app.

Why do I get role "root" does not exist?

Something ran psql or pg_isready inside the container without -U, so it used the operating system user root. Add -U with your POSTGRES_USER (and -d with your database) to the command or the healthcheck.

Setup and connections

How do I connect to Postgres in Docker from the host?

Publish the port, for example ports: - "127.0.0.1:5433:5432", then connect to 127.0.0.1 on port 5433 with the user and password from your Compose file. Other containers on the same network use the service name and port 5432 and need no published port.

Why didn't my docker-entrypoint-initdb.d script run?

Init scripts run only when the data directory is empty, the same as the POSTGRES_* variables. If the volume already has a database, the scripts are skipped. Run the SQL by hand with docker compose exec, or delete the volume if the data is disposable.

How do I fix Database is uninitialized and superuser password is not specified?

Give POSTGRES_PASSWORD a non-empty value. Check that your .env file sits next to compose.yaml and defines the variable, and run docker compose config to see the value Compose actually passes. Use ${DB_PASSWORD:?} so a missing value stops Compose with an error.

RabbitMQ in Docker: Fix ACCESS_REFUSED and Connection Refused

DeployLark — Fri, 06 Nov 2026 10:32:09 +0000

You add rabbitmq to a Compose file, point Celery or Spring AMQP at amqp://guest:guest@localhost:5672/, and the client dies with Connection refused. Or the TCP path works and you still get ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN. The broker log may say user 'guest' can only connect via localhost, or invalid credentials, or nothing useful while your new RABBITMQ_DEFAULT_PASS is ignored.

This guide reproduces those failures with rabbitmq:4.4.0-management-alpine and a small Pika 1.3.2 client on the same Compose network, then fixes them. Every error string and log line below comes from that lab run on November 6, 2026. The Stack Overflow question ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN had 370,994 views that day, Connecting to RabbitMQ container with docker-compose had 50,479, and Rabbitmq - Docker connection refused on port 5672 had 35,539.

The short version:

From another container, localhost is that container. Use the Compose service name, for example rabbitmq.
ACCESS_REFUSED with PLAIN is the same client text for wrong passwords and for the guest loopback rule. Read the broker log line under it.
The official Docker image sets loopback_users.guest = false, so guest from a peer container often works. Bare-metal RabbitMQ and a restored loopback config refuse guest from peers.
Set RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS on first boot. Changing them later does nothing if the data volume already exists.
Wait for a real healthcheck before starting the app. depends_on alone is not enough.

Fix Connection refused to port 5672

Start with the map. Match the message you see to the cause and the fix:

Don't connect to localhost from the app container

The lab started with stock RabbitMQ and no custom user:

services:
  rabbitmq:
    image: rabbitmq:4.4.0-management-alpine
    hostname: rabbitmq

A Pika client on the same Compose network played the app. With RMQ_HOST=localhost it never reached RabbitMQ:

client hostname='b1ce59b7a70e'
connecting host='localhost' port=5672 user='guest' vhost='/'
tcp connect to localhost:5672 failed: [Errno 111] Connection refused
FAIL AMQPConnectionError: ConnectionRefusedError(111, 'Connection refused')

Each container has its own loopback interface, so localhost inside the app is the app. RabbitMQ listens in the rabbitmq service. Set the host to rabbitmq (or whatever you named the service), for example amqp://labuser:secret@rabbitmq:5672/. The Redis guide and the MySQL guide show the same mistake for those databases.

From the Docker host itself you also need a published port. Without ports, a host tool cannot reach 5672. Add ports: ["127.0.0.1:5672:5672"] if a process on the host must talk AMQP. Other Compose services do not need that mapping.

Wait until the listener is ready

depends_on: [rabbitmq] only waits for the container process to start. In the lab, an immediate connect right after docker compose up -d still got Connection refused on rabbitmq:5672. After the healthcheck flipped to healthy, the same client opened AMQP and published a message. Use a healthcheck and condition: service_healthy, the pattern also used in the Umami guide with PostgreSQL:

services:
  rabbitmq:
    image: rabbitmq:4.4.0-management-alpine
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
      interval: 5s
      timeout: 10s
      retries: 12
      start_period: 15s
  app:
    image: your-app:tag
    depends_on:
      rabbitmq:
        condition: service_healthy

Fix ACCESS_REFUSED for the guest user

Read the broker log, not only the client text

The client message is almost always:

ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN. For details see the broker logfile.

That one string covers several causes. The broker log names the real one. With a wrong password the lab logged PLAIN login refused: user 'guest' - invalid credentials. With the guest loopback rule restored it logged PLAIN login refused: user 'guest' can only connect via localhost.

Guest loopback on bare metal vs the Docker image

The RabbitMQ access control docs state the product default: "By default, the guest user is prohibited from connecting from remote hosts. It can only connect over a loopback interface (localhost)."

The official Docker image changes that for Compose peers. In rabbitmq:4.4.0-management-alpine, /etc/rabbitmq/conf.d/10-defaults.conf contains this setting (the image file comments it with ##, shown here with #):

# allow access to the guest user from anywhere on the network
loopback_users.guest = false

So a stock image often accepts guest from another container on the Compose network. That surprises people who paste bare-metal advice into a Docker setup, and the reverse also happens: if you restore the product default, guest from a peer fails again.

The lab copied loopback_users.guest = true into conf.d/20-loopback.conf and rebuilt a thin image on top of rabbitmq:4.4.0-management-alpine. From a peer container, guest then failed with ACCESS_REFUSED. The broker said:

PLAIN login refused: user 'guest' can only connect via localhost

The same guest credentials from 127.0.0.1 inside the RabbitMQ network namespace opened AMQP successfully.

Do not "fix" this by setting loopback_users = none in production. Create a non-guest user instead. The docs call remote guest access a danger zone for a reason.

Fix DEFAULT_USER that never changes

Seed a user on first boot

On an empty data directory, the image reads RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS and creates that administrator. The lab used:

services:
  rabbitmq:
    image: rabbitmq:4.4.0-management-alpine
    hostname: rabbitmq
    environment:
      RABBITMQ_DEFAULT_USER: labuser
      RABBITMQ_DEFAULT_PASS: Lab-Pass-4821
    ports:
      - "127.0.0.1:5672:5672"
      - "127.0.0.1:15672:15672"
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
      interval: 5s
      timeout: 10s
      retries: 12
      start_period: 15s
    volumes:
      - rmq-data:/var/lib/rabbitmq

volumes:
  rmq-data:

After the container became healthy, rabbitmqctl list_users showed only labuser with the administrator tag. The Pika client with those credentials published and consumed a durable queue message. guest/guest then returned ACCESS_REFUSED with invalid credentials. The management HTTP API on 127.0.0.1:15672 answered 200 for labuser and reported rabbitmq_version 4.4.0.

A named volume keeps the first password

The image stores users in /var/lib/rabbitmq. If you change RABBITMQ_DEFAULT_PASS in Compose and recreate the container with the same named volume, the env vars do not rewrite the existing user. That is the core of docker-library/rabbitmq#150 (29 comments): people edit the password in .env, restart, and still get ACCESS_REFUSED.

In the lab, the volume kept Lab-Pass-4821. After switching the env to New-Pass-9999, the new password failed:

FAIL ProbableAuthenticationError: ConnectionClosedByBroker: (403) 'ACCESS_REFUSED - Login was refused using authentication mechanism PLAIN. For details see the broker logfile.'

The broker logged PLAIN login refused: user 'labuser' - invalid credentials. The old password still opened AMQP.

To rotate credentials on purpose, change the password with rabbitmqctl change_password, or remove the volume and accept a wipe of queues and users, then boot once with the new env. The PostgreSQL password guide and the MongoDB auth guide hit the same first-boot-vs-volume pattern.

A Compose file that works

Put the service name, a non-guest user, a healthcheck, and a volume together:

services:
  rabbitmq:
    image: rabbitmq:4.4.0-management-alpine
    hostname: rabbitmq
    environment:
      RABBITMQ_DEFAULT_USER: ${RABBITMQ_DEFAULT_USER:?set RABBITMQ_DEFAULT_USER in .env}
      RABBITMQ_DEFAULT_PASS: ${RABBITMQ_DEFAULT_PASS:?set RABBITMQ_DEFAULT_PASS in .env}
    ports:
      - "127.0.0.1:5672:5672"
      - "127.0.0.1:15672:15672"
    healthcheck:
      test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
      interval: 5s
      timeout: 10s
      retries: 12
      start_period: 15s
    volumes:
      - rmq-data:/var/lib/rabbitmq

  app:
    image: your-app:tag
    environment:
      AMQP_URL: amqp://${RABBITMQ_DEFAULT_USER}:${RABBITMQ_DEFAULT_PASS}@rabbitmq:5672/
    depends_on:
      rabbitmq:
        condition: service_healthy

volumes:
  rmq-data:

RABBITMQ_DEFAULT_USER=labuser
RABBITMQ_DEFAULT_PASS=replace-me-with-a-long-secret

Point every client at host rabbitmq, not localhost. Drop the ports block if nothing on the host needs AMQP or the management UI. Keep 127.0.0.1 when you do publish, the same habit as in the Portainer guide when you bind admin ports to the host loopback only.

Check it

$ docker compose up -d
$ docker compose ps
# rabbitmq health: healthy
$ docker compose exec rabbitmq rabbitmqctl list_users
Listing users ...
user    tags
labuser [administrator]
$ curl -sS -u labuser:replace-me-with-a-long-secret http://127.0.0.1:15672/api/overview | head -c 80

If the app still fails, read docker compose logs rabbitmq for the PLAIN login refused line before you change more config.

FAQ

Connection refused

Why does RabbitMQ refuse connections between Docker Compose containers?

Usually the app uses localhost or 127.0.0.1, which is its own container. Use the Compose service name, such as rabbitmq. If the host is already correct, the broker may not be listening yet. Add a rabbitmq-diagnostics -q ping healthcheck and depends_on with condition: service_healthy.

How do I connect to RabbitMQ in Docker from the host machine?

Publish the port, for example ports: ["127.0.0.1:5672:5672"], and connect to 127.0.0.1:5672 with a user that exists in the broker. Without ports, the host gets Connection refused. Other containers on the Compose network do not need a published port.

ACCESS_REFUSED and guest

Why do I get ACCESS_REFUSED with guest and PLAIN from another container?

Check the broker log. If it says user 'guest' can only connect via localhost, the loopback rule is on. Create a non-guest user with RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS instead of reopening guest. If the log says invalid credentials, the password or username is wrong for the data in the volume.

Does the official RabbitMQ Docker image allow guest from other containers?

Yes, by default. rabbitmq:4.4.0-management-alpine ships loopback_users.guest = false in /etc/rabbitmq/conf.d/10-defaults.conf so Compose peers can use guest. That differs from bare-metal RabbitMQ, where guest is localhost-only. Still create a dedicated user for anything beyond a throwaway lab.

Users and volumes

Why does RABBITMQ_DEFAULT_PASS not change my password after a restart?

Those variables seed the default user only when the data directory is empty. A named volume keeps the first user and password. Change the password with rabbitmqctl change_password, or remove the volume and boot once with the new env if you accept wiping broker data.

How do I create a RabbitMQ user for Docker Compose the right way?

Set RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS before the first start with an empty volume, or run rabbitmqctl add_user, set_user_tags, and set_permissions against a running node. Point clients at that user and the service name rabbitmq on port 5672.

S3 NoSuchBucket in Docker: Fix Bucket Not Found Errors

DeployLark — Fri, 06 Nov 2026 03:23:45 +0000

Your app talks to self-hosted S3 storage in Docker, and the upload fails with NoSuchBucket. The message says Bucket not found or The specified bucket does not exist. But the bucket is right there in the admin UI. Or the same call works from the AWS CLI and fails from your Node app.

This guide reproduces those failures in Docker Compose with Garage v2.5.0, a maintained open-source S3 server, and fixes each one. Every Garage and RustFS error below comes from that lab run on November 2, 2026. In several cases the bucket existed the whole time. The server read a different bucket name than the one you meant, because of a typo, the URL style, the endpoint or the access key.

The questions get steady traffic. On Stack Overflow, Code: NoSuchBucket had 78,316 views on November 2, 2026, and docker-compose: how to use minio in- and outside of the docker network had 57,838.

The short version:

Read the bucket name inside the error. Garage prints it, as in Bucket not found: cat.txt. If that isn't your bucket, the request was built wrong.
Set forcePathStyle: true (or the path-style option of your SDK) for self-hosted endpoints. The AWS SDK for JavaScript v3 puts the bucket in the hostname by default.
Set the region to the one the server expects. Garage uses garage unless you change s3_region.
Point the endpoint at the S3 API port (3900 for Garage) with no bucket in the URL.
AccessDenied means the bucket exists but your key can't use it. NoSuchBucket means the server found no bucket under that name for that key.

Fix NoSuchBucket: find the bucket name the server saw

Read the name in the error

The lab created one bucket, photos, and one access key with read and write rights on it. Then it ran aws 2.39.3 in a container on the same Compose network with AWS_ENDPOINT_URL=http://garage:3900 and AWS_DEFAULT_REGION=garage:

Bucket names are case sensitive. Photos is not photos, so Garage answered NoSuchBucket with Bucket not found: Photos. The raw XML body carries the same name in <Message> and <Resource>:

<Error><Code>NoSuchBucket</Code><Message>Bucket not found: pictures</Message><Resource>/pictures</Resource><Region>garage</Region></Error>

The Garage log shows the same thing with the method and path, for example error 404 Not Found, Bucket not found: pictures ... HEAD /pictures. Run docker compose logs garage and compare the path with the bucket you meant.

Other servers word it differently. RustFS 1.0.4 answered a missing bucket with NoSuchBucket: The specified bucket does not exist, the same text MinIO used, and rejected Photos with InvalidBucketName: The specified bucket is not valid. Supabase Storage wraps the error in JSON, {"statusCode":"404","error":"Bucket not found","message":"Bucket not found","code":"NoSuchBucket"}, which the Supabase self-hosting guide ran into before the bucket was created.

Check the bucket with head-bucket

aws s3api head-bucket --bucket pictures returned An error occurred (404) when calling the HeadBucket operation: Not Found and exit code 254. A HEAD response has no body, so you get a bare 404 instead of NoSuchBucket. That makes it a quick existence check in a script. On Garage, docker compose exec garage /garage bucket list shows every bucket name, called a global alias, and every per-key name, called a local alias. More on those below.

Fix Bucket not found caused by virtual-hosted URLs

Start with how the request is built. S3 clients can address a bucket in two ways, and the AWS docs on virtual hosting describe both. Path-style puts the bucket in the path. Virtual-hosted style puts it in the hostname.

Set forcePathStyle for self-hosted endpoints

The lab used a small Node.js script with @aws-sdk/client-s3 3.1161.0 on node:24.22.2-alpine. It set endpoint: "http://garage:3900" and region: "garage" and nothing else. The SDK built http://photos.garage:3900/cat.txt. No DNS record exists for photos.garage, so the call failed before it reached Garage:

Error: getaddrinfo ENOTFOUND photos.garage

The box this ran on resolves unknown names to a proxy, so the lab pointed the client at a CoreDNS 1.15.0 container that answers "no such name" for everything, the way a normal network does. With forcePathStyle: true, the same script fetched http://garage:3900/photos/cat.txt and printed OK hello garage.

The worse case is when photos.garage does resolve, for example through a wildcard DNS record or a proxy that sends every subdomain to Garage. The lab simulated that with a Compose network alias. Garage did not recognize the hostname, so it treated the request as path-style and read the object key as the bucket name:

NoSuchBucket: Bucket not found: cat.txt is the giveaway. cat.txt is a file, not a bucket. An upload failed in a stranger way. Garage read PUT /from-node.txt as a request to create a bucket called from-node.txt and returned InvalidRequest: Bad request: Invalid create bucket XML query. Here is the client config that fixed both:

import { S3Client } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "http://garage:3900",
  region: "garage",
  forcePathStyle: true, // http://garage:3900/<bucket>/<key>
});

Other SDKs have their own path-style option, so check their docs. The AWS CLI 2.39.3 in the lab used path-style on its own with a custom endpoint. Its debug log showed http://garage:3900/photos?list-type=2.... That is why the CLI worked while the Node app failed with the same keys.

Or configure root_domain and wildcard DNS

If an app can't do path-style, give Garage a domain for virtual-hosted requests. The lab config had root_domain = ".s3.garage.localhost" under [s3_api]. With the endpoint set to http://s3.garage.localhost:3900 and a network alias for photos.s3.garage.localhost, the script worked without forcePathStyle. In production that alias is a wildcard DNS record such as *.s3.example.com, plus a wildcard TLS certificate if you serve HTTPS. The Garage configuration reference notes: "Note path-style requests are always enabled, whether or not vhost-style is configured." So path-style keeps working after you add the domain. Garage picks the bucket from the Host header, so a reverse proxy in front has to pass that header through unchanged. The Traefik labels guide covers routing by host name.

Fix the region and the endpoint URL

Match the region to s3_region

Garage only accepts requests signed for its own region. The Garage configuration reference says: "Garage will accept S3 API calls that are targeted to the S3 region defined here. API calls targeted to other regions will fail with a AuthorizationHeaderMalformed error message that redirects the client to the correct region."

With region: "us-east-1", the Node SDK failed with AuthorizationHeaderMalformed: Authorization header malformed, unexpected scope: '20261102/us-east-1/s3/aws4_request', expected: '20261102/garage/s3/aws4_request'. The AWS CLI hid the same mistake. With --region us-east-1 it listed the bucket fine, and its debug log showed why: one request signed for us-east-1, the AuthorizationHeaderMalformed answer, then a retry signed for garage. So set the region in your app to the s3_region value from garage.toml, which is garage in the Garage quick start. RustFS accepted us-east-1 in the lab.

Point the endpoint at the S3 port, without the bucket

Garage listens on several ports. Only 3900 speaks the S3 API. The lab tried the others:

http://garage:3902 (the static website port) returned (404) ... Not Found.
http://garage:3903 (the admin API) returned (400) ... Bad Request.
http://garage:3900/photos, with the bucket inside the endpoint, made the client add the bucket a second time. Garage looked up /photos/photos/cat.txt, and aws s3 ls failed with NoSuchKey: Key not found.
A wrong secret key returned AccessDenied: Forbidden: Invalid signature.

The endpoint is the server address only, such as http://garage:3900. The bucket goes in the bucket parameter. From another container, use the Compose service name. From the host, use the published port. In the lab, --endpoint-url http://127.0.0.1:3900 listed the bucket from the host. localhost inside a container is that container, the same trap the Redis in Docker guide shows. And if you put a TLS proxy in front, match http and https with what the proxy serves. The private registry guide shows what a scheme mismatch looks like.

AccessDenied or NoSuchBucket: check the access key

Grant the key access to the bucket

In Garage, a key sees nothing until you run garage bucket allow for it. The lab created report-key with read access to photos only:

The difference matters. invoices exists, so the key got AccessDenied: Forbidden: Operation is not allowed for this key. A bucket that didn't exist got NoSuchBucket. aws s3 ls only listed photos, the one bucket the key could use. Creating a bucket failed with AccessDenied: Forbidden: Access key GK8a04... is not allowed to create buckets, because the key had no create right. Grant access with:

docker compose exec garage /garage bucket allow --read --write photos --key report-key

The Garage quick start also adds --owner. Run garage key info <key> to see which buckets a key can use.

Local aliases are per key

Garage lets a key give a bucket its own private name, a local alias. The lab ran garage bucket alias --local app-key photos media. For app-key, s3://media listed the files in photos. For report-key, which had read access to the same bucket, s3://media returned NoSuchBucket: Bucket not found: media. If two services share a bucket, use the global alias, or create the same local alias for each key.

MinIO images are gone: a Garage Compose file that works

What happened to minio/minio

Many older tutorials pin minio/minio. On November 2, 2026, the Docker Hub API answered object not found for that repository. docker pull minio/minio:RELEASE.2025-09-07T16-13-09Z failed with pull access denied for minio/minio, repository does not exist, and the same tag on quay.io/minio/minio returned unauthorized: access to the requested resource is not authorized. The MinIO GitHub repository was archived on April 25, 2026, and its README says "The MinIO community edition is now distributed as source code only." StableBuild's write-up dates the Docker Hub removal to around September 12, 2026.

So a fresh docker compose up with a MinIO image now fails before any bucket error can happen. The lab moved to Garage. RustFS 1.0.4 also ran fine, and its error messages are closer to MinIO's. The fixes above apply to both, since they come from the S3 protocol and the client.

compose.yaml, garage.toml and the app

This setup ran verbatim in the lab. It uses the --single-node and --default-bucket flags from the Garage quick start, which create the layout, one access key and one bucket from environment variables:

metadata_dir = "/var/lib/garage/meta"
data_dir = "/var/lib/garage/data"
db_engine = "sqlite"
replication_factor = 1

rpc_bind_addr = "[::]:3901"
rpc_public_addr = "127.0.0.1:3901"

[s3_api]
s3_region = "garage"
api_bind_addr = "[::]:3900"

[admin]
api_bind_addr = "[::]:3903"

services:
  garage:
    image: dxflrs/garage:v2.5.0
    command: ["/garage", "server", "--single-node", "--default-bucket"]
    environment:
      GARAGE_RPC_SECRET: ${GARAGE_RPC_SECRET}
      GARAGE_ADMIN_TOKEN: ${GARAGE_ADMIN_TOKEN}
      GARAGE_DEFAULT_ACCESS_KEY: ${S3_ACCESS_KEY}
      GARAGE_DEFAULT_SECRET_KEY: ${S3_SECRET_KEY}
      GARAGE_DEFAULT_BUCKET: ${S3_BUCKET}
    volumes:
      - ./garage.toml:/etc/garage.toml:ro
      - garage-meta:/var/lib/garage/meta
      - garage-data:/var/lib/garage/data
    ports:
      - "127.0.0.1:3900:3900"
    healthcheck:
      test: ["CMD", "/garage", "status"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    image: node:24.22.2-alpine
    working_dir: /app
    command: ["node", "app.mjs"]
    depends_on:
      garage:
        condition: service_healthy
    environment:
      S3_ENDPOINT: http://garage:3900
      S3_REGION: garage
      S3_BUCKET: ${S3_BUCKET}
      AWS_ACCESS_KEY_ID: ${S3_ACCESS_KEY}
      AWS_SECRET_ACCESS_KEY: ${S3_SECRET_KEY}
    volumes:
      - ./app:/app:ro

volumes:
  garage-meta:
  garage-data:

Fill .env with your own random values. The access key ID starts with GK, as in the quick start:

cat > .env <<EOF
GARAGE_RPC_SECRET=$(openssl rand -hex 32)
GARAGE_ADMIN_TOKEN=$(openssl rand -base64 32)
S3_ACCESS_KEY=GK$(openssl rand -hex 16)
S3_SECRET_KEY=$(openssl rand -hex 32)
S3_BUCKET=uploads
EOF

./app/app.mjs stands in for your real service. It needs npm install @aws-sdk/client-s3@3.1161.0 in ./app first:

import { S3Client, PutObjectCommand, ListObjectsV2Command } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT,   // http://garage:3900
  region: process.env.S3_REGION,       // must match s3_region in garage.toml
  forcePathStyle: true,                // http://garage:3900/<bucket>/<key>
});
const Bucket = process.env.S3_BUCKET;

await s3.send(new PutObjectCommand({ Bucket, Key: "hello.txt", Body: "hello" }));
const { Contents } = await s3.send(new ListObjectsV2Command({ Bucket }));
console.log(`${Bucket}: ${Contents.map((o) => o.Key).join(", ")}`);

Check it

<code>text $ docker compose up -d Container s3final-garage-1 Healthy Container s3final-app-1 Started $ docker compose ps -a --format '{{.Service}} {{.Status}}' app Exited (0) 1 second ago garage Up 12 seconds (healthy) $ docker compose logs --no-log-prefix app uploads: hello.txt $ docker compose restart garage $ docker compose run --rm app uploads: hello.txt </code>

On the first start, Garage logged Created initial layout for single-node configuration, Creating default access key and Creating default bucket uploads. The SDK reads the key from AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY on its own. Changing S3_BUCKET later behaves differently from database images. With S3_BUCKET=assets, Garage created a second bucket, assets, on the next start and kept uploads with its files. The default key kept its rights on uploads, and the app still read it after switching back. Keep the image pinned, here dxflrs/garage:v2.5.0, so a restart never pulls a new release onto your data.

FAQ

Errors

What does NoSuchBucket mean?

The server found no bucket with the name in the request, for the key you used. Check the name in the error message first. If it shows a file name or a word you never used as a bucket, fix the URL style or the endpoint. If it shows your bucket, check the spelling, the case, and whether the bucket was created on this server.

Why does the AWS CLI work but my app gets NoSuchBucket or ENOTFOUND?

The AWS CLI 2.39.3 used path-style URLs with a custom endpoint, and it retried a wrong region on its own. The AWS SDK for JavaScript v3 did neither. Set forcePathStyle: true and the server's region in the app.

What does "The authorization header is malformed" mean with self-hosted S3?

The client signed the request for a different region than the server uses. Garage answered AuthorizationHeaderMalformed with the expected scope in the message. Set the client region to the server's s3_region.

Setup

How do I check if a bucket exists?

Run aws s3api head-bucket --bucket <name>. In the lab, exit code 0 meant the bucket existed and the key could use it. A missing bucket returned (404) ... Not Found and a bucket the key had no rights on returned (403) ... Forbidden, both with exit code 254.

How do I connect to S3 storage inside and outside the Docker network?

Inside the Compose network, use the service name, such as http://garage:3900. From the host, publish the port and use http://127.0.0.1:3900. Use path-style in both cases, so the bucket never ends up in a hostname.

Can I still pull the MinIO Docker image?

Not from Docker Hub. On November 2, 2026, minio/minio no longer existed there, and the Quay copy returned unauthorized. The community edition is source only. Use a maintained server such as Garage or RustFS, or build MinIO from source at your own risk.

Keycloak Behind a Reverse Proxy: Fix HTTPS Required

DeployLark — Thu, 05 Nov 2026 23:28:48 +0000

You open Keycloak in the browser and get a grey page that says We are sorry... HTTPS required. Or you put it behind nginx, and the admin console stays blank, or the login page says Invalid parameter: redirect_uri. Your app then rejects every token with Invalid token issuer. All of these come from the same question: what URL does Keycloak think it lives at?

This guide reproduces each error with quay.io/keycloak/keycloak:26.8.1, nginx:1.31.8 and postgres:18.6 in Docker Compose and fixes it. Every error message below comes from that lab run on November 4, 2026. The lab used the name auth.example.test with a self-signed certificate in place of your real domain.

These errors are common. On Stack Overflow, keycloak Invalid parameter: redirect_uri had 505,136 views on November 4, 2026, and "HTTPS required" while logging in to Keycloak as admin had 136,879.

The short version:

HTTPS required means a client with a public IP address reached Keycloak over plain HTTP. Put a TLS proxy in front. Don't switch the realm to Require SSL: None outside a lab.
Behind a proxy that terminates TLS, set KC_PROXY_HEADERS=xforwarded and make the proxy send X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Port. Without both, Keycloak builds http:// URLs, and you get a blank admin console and Invalid parameter: redirect_uri.
Set KC_HOSTNAME to the full public URL, such as https://auth.example.test. It fixes the token issuer, so apps that talk to http://keycloak:8080 stop failing with Invalid token issuer.
For your own apps, the redirect URI must match the client's Valid redirect URIs exactly, including https, the host and the port.

Fix Keycloak startup errors in production mode

Most Compose examples on the internet use start-dev. When you switch to start, the production mode, the container exits before it serves a single page.

Key material not provided to setup HTTPS

With command: start and only the admin variables set, the container stopped with exit code 2 and this line:

Key material not provided to setup HTTPS. Please configure your keys/certificates, or if HTTPS access is not needed see the `http-enabled` option. If you meant to start the server in development mode, see the `start-dev` command.

Production mode expects its own TLS certificate. When a reverse proxy handles TLS, as in this guide, set KC_HTTP_ENABLED: "true" so Keycloak listens on plain HTTP port 8080 inside the Docker network. The reverse proxy guide requires it for this setup: "If the TLS connection is terminated at the reverse proxy (edge termination), enabling HTTP through the http-enabled setting is required."

hostname is not configured

With HTTP enabled, the next start failed with exit code 1:

ERROR: hostname is not configured; either configure hostname, or set hostname-strict to false

The quick fix you see in many answers is KC_HOSTNAME_STRICT: "false". It works, but it tells Keycloak to build every URL from the request, which causes the next two problems. Set KC_HOSTNAME instead, as shown in the last section. Keycloak also logged a warning that "the server is running in an insecure context" while HTTPS was off, proxy-headers was unset and hostname-strict was false.

Fix "HTTPS required" in Keycloak

This is the error on the grey Keycloak page. In the lab it came from the master realm login page, where the admin console sends you to sign in.

Why Keycloak asks for HTTPS

Every realm has a Require SSL setting. Its default, external, allows plain HTTP only from private addresses. The Keycloak server admin guide describes it: "If you try to access Keycloak without SSL from a non-private IP address, you will get an error."

That explains why it works on your laptop and fails on a VPS. In the lab, Keycloak first ran on the default Compose network, 192.168.0.0/20, and the login page loaded over http://127.0.0.1:8080. Then Keycloak moved to a Docker network in 203.0.113.0/24, a documentation range that counts as public, so it saw requests from 203.0.113.1. The same URL returned HTTP 400 with HTTPS required, and the log named the reason:

type="LOGIN_ERROR", realmName="master", clientId="null", userId="null", ipAddress="203.0.113.1", error="ssl_required"

A VPS reached from the internet is in the same position. Your browser's address is public, so plain HTTP to port 8080 fails.

Serve Keycloak over HTTPS, not Require SSL: None

The fix is HTTPS in front of Keycloak, which the rest of this guide sets up with nginx. If you already use Nginx Proxy Manager or Traefik, use that proxy and copy the header settings below.

Many answers suggest switching the master realm to Require SSL: None. It does work. From inside the container, where localhost is a private address, kcadm.sh changed the setting:

docker compose exec keycloak /opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 --realm master --user admin --password '<admin password>'
docker compose exec keycloak /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE

The login page loaded over plain HTTP from the public range right after. But the admin password and tokens then cross the internet unencrypted. The same guide says None "applies only in development". The lab set it back with -s sslRequired=EXTERNAL, and HTTPS required returned.

Fix a blank admin console and Invalid parameter: redirect_uri behind nginx

Once nginx terminates TLS and forwards plain HTTP to Keycloak, a new set of errors appears. Keycloak no longer sees HTTPS, so it generates http:// links for a site that you reach over https://.

What happens without the forwarded headers

The first nginx config in the lab only passed proxy_set_header Host $host, and Keycloak had KC_HOSTNAME_STRICT=false with no proxy settings. Opening https://auth.example.test/admin/ returned:

Location: http://auth.example.test/admin/master/console/

The OpenID discovery document listed http://auth.example.test/realms/master as the issuer. In Chrome, the admin console stayed blank with a spinner, and the browser console showed why:

Mixed Content: The page at 'https://auth.example.test/admin/master/console/' was loaded over HTTPS, but requested an insecure resource 'http://auth.example.test/resources/master/admin/en'. This request has been blocked; the content must be served over HTTPS.

The admin console's own sign-in failed too. A request with redirect_uri=https://auth.example.test/admin/master/console/ got HTTP 400 and Invalid parameter: redirect_uri, because Keycloak expected the http:// version.

Adding the headers to nginx alone changed nothing. With X-Forwarded-Proto and the others set, the redirect still went to http://, because Keycloak ignores those headers until you enable them. The reverse also failed: with KC_PROXY_HEADERS=xforwarded but the old nginx config, the redirect still pointed to http://. You need both.

Forward the headers and set KC_PROXY_HEADERS

This nginx server block fixed it, together with KC_PROXY_HEADERS: xforwarded on the Keycloak service:

server {
    listen 80;
    server_name auth.example.test;
    return 301 https://$host$request_uri;
}
server {
    listen 443 ssl;
    server_name auth.example.test;
    ssl_certificate     /etc/nginx/certs/auth.crt;
    ssl_certificate_key /etc/nginx/certs/auth.key;

    location / {
        proxy_pass http://keycloak:8080;
        proxy_set_header Host              $host;
        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_set_header X-Forwarded-Port  $server_port;
    }
}

After the change, /admin/ redirected to https://auth.example.test/admin/master/console/, the issuer started with https://, and the admin console loaded with 0 console errors. $server_port is the port nginx listens on inside its container. If you publish nginx on another host port, such as 8443, put that public port in X-Forwarded-Port instead.

Never publish Keycloak's port 8080 next to the proxy once headers are trusted. In the lab, a container on the same network sent X-Forwarded-Host: evil.example straight to keycloak:8080, and the discovery document answered with the issuer https://evil.example/realms/master. The reverse proxy guide warns that clients could "send forged forwarded headers directly to Keycloak" without network restrictions. The next section closes this hole for the host name.

Invalid parameter: redirect_uri in your own apps

The same error appears for your own clients when the redirect URI an app sends doesn't match the client's Valid redirect URIs. The lab client app allowed https://app.example.test/*:

redirect_uri sent	Result
`https://app.example.test/callback`	login form
`https://app.example.test`	login form
`http://app.example.test/callback`	`Invalid parameter: redirect_uri`
`https://app.example.test:8443/callback`	`Invalid parameter: redirect_uri`
`https://www.app.example.test/callback`	`Invalid parameter: redirect_uri`

The scheme, the host and the port all have to match. The Keycloak log shows the URI that was rejected, which is the fastest way to see what your app sent:

type="LOGIN_ERROR", realmName="demo", clientId="app", ... error="invalid_redirect_uri", redirect_uri="https://www.app.example.test/callback"

An http:// URI usually means your app sits behind its own proxy and builds its callback URL from the plain HTTP request. Fix the app's proxy settings or set its public URL, the same way you fixed Keycloak. The Home Assistant and Nextcloud guides show this for two common apps.

Fix "Invalid token issuer" with KC_HOSTNAME

Even with the proxy headers fixed, KC_HOSTNAME_STRICT=false makes Keycloak build every URL from the request, including the iss claim in tokens. Your browser and your app's backend reach it at different addresses, so they disagree.

Why the issuer changes

In the lab, a user logged in through https://auth.example.test, so the access token had iss: https://auth.example.test/realms/demo. An app container then checked that token at http://keycloak:8080, the address it uses inside the Docker network. The userinfo endpoint answered 401 Unauthorized with error="invalid_token", error_description="Token verification failed", and the Keycloak log gave the real reason:

reason="Invalid token issuer. Expected 'http://keycloak:8080/realms/demo'"

The same token worked through the public URL. Keycloak expected the issuer of the address that the request came in on.

Set the full public URL

Set KC_HOSTNAME: https://auth.example.test, the full URL with the scheme. With that in place, the discovery document at http://keycloak:8080 listed https://auth.example.test/realms/demo as the issuer, and the internal userinfo call returned HTTP 200. The forged X-Forwarded-Host: evil.example request from the previous section now got the correct issuer back. The hostname guide gives this as the reason the option exists: "By explicitly setting the hostname option, we avoid a situation where tokens could be issued by a fraudulent issuer."

One catch remains. With only KC_HOSTNAME set, the internal discovery document pointed the token and certs endpoints at https://auth.example.test too, so a backend inside Docker has to reach the public name. Add KC_HOSTNAME_BACKCHANNEL_DYNAMIC: "true". In the lab, the internal document then listed http://keycloak:8080/realms/demo/protocol/openid-connect/token and .../certs, kept the https:// issuer and the https:// login URL, and a token requested internally still carried iss: https://auth.example.test/realms/demo. Browsers that use the public URL saw only https:// endpoints.

A Keycloak Compose file with nginx that avoids these errors

This file puts the fixes together. It ran verbatim in the lab with the nginx config from above saved as nginx/keycloak.conf, and the certificate and key in certs/. Use a real certificate for your domain, for example from your existing proxy.

The compose file

Create .env with two random passwords:

printf 'KC_DB_PASSWORD=%s\nKC_ADMIN_PASSWORD=%s\n' "$(openssl rand -hex 24)" "$(openssl rand -hex 16)" > .env

services:
  postgres:
    image: postgres:18.6
    restart: unless-stopped
    environment:
      POSTGRES_USER: keycloak
      POSTGRES_DB: keycloak
      POSTGRES_PASSWORD: ${KC_DB_PASSWORD:?set KC_DB_PASSWORD in .env}
    volumes:
      - pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "keycloak", "-d", "keycloak"]
      interval: 5s
      timeout: 3s
      retries: 10

  keycloak:
    image: quay.io/keycloak/keycloak:26.8.1
    restart: unless-stopped
    command: start
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: ${KC_DB_PASSWORD:?set KC_DB_PASSWORD in .env}
      KC_HOSTNAME: https://auth.example.test
      KC_HOSTNAME_BACKCHANNEL_DYNAMIC: "true"
      KC_PROXY_HEADERS: xforwarded
      KC_HTTP_ENABLED: "true"
      KC_HEALTH_ENABLED: "true"
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_ADMIN_PASSWORD:?set KC_ADMIN_PASSWORD in .env}
    healthcheck:
      test: ["CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/9000 && printf 'GET /health/ready HTTP/1.1\\r\\nHost: localhost\\r\\nConnection: close\\r\\n\\r\\n' >&3 && grep -q UP <&3"]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 30s
    depends_on:
      postgres:
        condition: service_healthy

  nginx:
    image: nginx:1.31.8
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/keycloak.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      keycloak:
        condition: service_healthy

volumes:
  pgdata:

Keycloak has no published port, so only nginx can reach it. The Keycloak image has no curl, so the healthcheck talks to the management port 9000 with bash's /dev/tcp. Port 9000 stays off the proxy, as the reverse proxy guide recommends. If Postgres refuses the password on a rerun, the Postgres password guide explains why the variables only apply on the first start.

Check that it works

Run docker compose up -d. Compose waited for each service in turn:

 Container kcfinal-postgres-1  Healthy
 Container kcfinal-keycloak-1  Starting
 Container kcfinal-keycloak-1  Started
 Container kcfinal-keycloak-1  Waiting
 Container kcfinal-keycloak-1  Healthy
 Container kcfinal-nginx-1  Starting
 Container kcfinal-nginx-1  Started

Keycloak logged Keycloak 26.8.1 on JVM (powered by Quarkus 3.40.1) started in 2.962s, with no insecure context warning and no errors. http://auth.example.test/admin/ returned a 301 to https://, https://auth.example.test/admin/ redirected to the https:// console, and the admin login through Chrome worked.

The banner at the top is Keycloak's reminder that the bootstrap admin is temporary. Create a permanent admin account and delete the bootstrap one. For an internet-facing server, the reverse proxy guide also recommends that you don't expose /admin/ and /realms/master/ publicly, because "Exposed admin paths lead to an unnecessary attack vector." Your apps only need /realms/, /resources/ and /.well-known/.

FAQ

Errors on the login page

How do I fix "HTTPS required" in Keycloak?

Serve Keycloak over HTTPS, usually through a reverse proxy, and set KC_PROXY_HEADERS and KC_HOSTNAME so Keycloak knows the public URL is https://. The error appears when a client with a public IP address uses plain HTTP while the realm's Require SSL is external.

Should I set Require SSL to None in the master realm?

Only in a throwaway lab. It removes the error, but logins and tokens then travel unencrypted. Keycloak's server admin guide limits None to development. Fix HTTPS instead.

Why does the Keycloak admin console load forever behind a reverse proxy?

Keycloak builds http:// URLs because it doesn't know the proxy uses HTTPS, and the browser blocks them as Mixed Content. Send X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Port from the proxy and set KC_PROXY_HEADERS=xforwarded. The browser console lists the blocked http:// request.

Configuration

What causes "Invalid parameter: redirect_uri" in Keycloak?

The redirect_uri sent by the app doesn't match any Valid redirect URI of the client. Check the scheme, host and port. The Keycloak log shows the rejected value in the invalid_redirect_uri event. For the admin console itself, it means Keycloak computed an http:// URL behind the proxy.

How do I fix "Invalid token issuer" when Keycloak runs in Docker?

Set KC_HOSTNAME to the full public URL so the issuer is the same no matter which address an app uses. Add KC_HOSTNAME_BACKCHANNEL_DYNAMIC=true if your backend should call Keycloak at http://keycloak:8080 inside the Docker network.

Can Keycloak run in production mode with HTTP only?

Yes, behind a proxy that handles HTTPS. Set KC_HTTP_ENABLED=true, KC_PROXY_HEADERS and KC_HOSTNAME, and don't publish port 8080. Without http-enabled, start exits with Key material not provided to setup HTTPS.

Docker Permission Denied on docker.sock: Fix It Without sudo

DeployLark — Thu, 05 Nov 2026 10:55:19 +0000

You type docker ps and get permission denied while trying to connect to the docker API at unix:///var/run/docker.sock. With sudo the same command works. Or the error shows up inside a container that has the socket mounted, and adding the user to the docker group changes nothing.

This guide reproduces each version of the error on Ubuntu 24.04 with Docker Engine 29.9.3 and fixes it. Every command and output below comes from that lab run on November 5, 2026, with a normal user named alice.

You're not alone with this one. On Stack Overflow, How to fix Docker: Permission denied had 1,945,544 views on November 5, 2026, and Got permission denied while trying to connect to the Docker daemon socket had 962,590.

The short version:

Your user can't open /var/run/docker.sock, which is owned by root:docker with mode 660. Run sudo usermod -aG docker $USER, then log out and back in, or run newgrp docker. A shell that was open before usermod keeps failing.
If usermod says the group does not exist, run sudo groupadd docker, add the user, and restart the Docker daemon so it sets the group on the socket.
Inside a container, add the host's numeric group ID: --group-add "$(stat -c %g /var/run/docker.sock)", or group_add in Compose. The group name docker in the image usually has a different number.
Don't chmod 666 the socket. The docker group is root-equivalent, so only add trusted users, and put a socket proxy in front of apps that only read container state.

Why Docker says permission denied on docker.sock

The docker command is only a client. It talks to the Docker daemon, dockerd, through a Unix socket at /var/run/docker.sock. The daemon runs as root. Whoever can open that socket can tell it to do anything.

What the socket permissions mean

On a fresh install, the socket looks like this:

srw-rw---- 1 root docker 0 Nov  5 02:17 /var/run/docker.sock

Only root and members of the docker group can read and write it. In the lab, alice had groups=1001(alice), so the kernel refused the connection before Docker saw the request. sudo docker ps works because root owns the socket.

The two forms of the error

Docker CLI 29.9.3 prints a short message:

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

Older clients print the full API call. Docker CLI 26.1.5 on Debian 13 showed:

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.45/containers/json": dial unix /var/run/docker.sock: connect: permission denied

Both mean the same thing, and docker compose fails the same way, because it uses the same socket.

Fix it on the host with the docker group

The fix in the Docker post-install guide is to add your user to the docker group:

sudo usermod -aG docker $USER

That alone doesn't fix the shell you're typing in. This is the step most people miss.

Start a new session or run newgrp

Linux reads your groups when you log in. A shell that started before usermod keeps the old list. In the lab, alice had a shell open, root ran usermod -aG docker alice, and the old shell still failed:

[old shell] $ id
uid=1001(alice) gid=1001(alice) groups=1001(alice)
[old shell] $ docker ps
permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

newgrp docker started a subshell with the new group, and a fresh login (su - alice, the same as a new SSH session) had it too. Both could run docker ps.

newgrp only changes that one subshell. For every terminal and your desktop session, log out fully and log back in. The Docker guide adds that a virtual machine may need a restart. Check with id that docker is in the list before you try again. Ubuntu created the group with GID 996 here. The number differs from machine to machine.

usermod: group 'docker' does not exist

If the docker group is missing, the daemon has no group to give the socket. The lab removed the group and restarted the daemon to reproduce it. dockerd logged a warning and the socket fell back to root:root:

level=warning msg="could not change group /var/run/docker.sock to docker: group docker not found"
srw-rw---- 1 root root 0 Nov  5 02:18 /var/run/docker.sock

usermod then failed with usermod: group 'docker' does not exist and exit code 6. Create the group first:

sudo groupadd docker
sudo usermod -aG docker $USER
sudo systemctl restart docker

The restart matters. Right after groupadd the socket still belonged to root:root, and docker ps as alice was still denied. Once the daemon came back up it set the socket to root:docker, and docker ps worked.

Why chmod 666 and sudo everywhere are the wrong fix

Many answers suggest sudo chmod 666 /var/run/docker.sock. It does make the error go away, because every user on the machine can now open the socket.

chmod 666 hands root to every account

That is the problem. Any process on the host, including a compromised web app running as www-data, can now start a privileged container. The change doesn't even last. In the lab the socket showed srw-rw-rw- after chmod 666, and after a daemon restart it was back to srw-rw---- root docker. You end up with an insecure fix that disappears at the next daemon restart, so the error comes back.

The docker group is root too

Adding a user to the docker group is the supported fix, but it gives the same power in a controlled way. The Docker guide is blunt about it: "The docker group grants root-level privileges to the user." The Docker security docs explain why. A container can mount the host's / directory and change the host filesystem without any restriction.

So treat docker group membership like sudo access. Add the accounts you'd trust with root, and nobody else. If you want Docker without root on the host at all, look at rootless mode, where each user runs their own daemon.

Fix permission denied inside a container

The error often appears in containers that mount the socket: CI agents, Jenkins, Portainer, Traefik, dashboards. As long as the container runs as root it works. Once the image switches to a normal user, it fails.

The group name inside the image doesn't match

The kernel checks numeric IDs, not names. In the lab, the socket on the host belonged to GID 1002. A container running as user 1000 saw this:

$ docker run --rm --user 1000:1000 -v /var/run/docker.sock:/var/run/docker.sock docker:29.9.3-cli sh -c 'ls -ln /var/run/docker.sock && getent group docker'
srw-rw----    1 0        1002             0 Nov  5 02:18 /var/run/docker.sock
docker:x:2375:

The docker:29.9.3-cli image has its own docker group with GID 2375. So --group-add docker adds group 2375, which doesn't own the socket, and docker ps still fails. That explains the Stack Overflow question where group permissions seem correct (347,311 views). Pass the host's number instead:

docker run --rm --user 1000:1000 \
  --group-add "$(stat -c %g /var/run/docker.sock)" \
  -v /var/run/docker.sock:/var/run/docker.sock \
  docker:29.9.3-cli sh -c 'id && docker ps'

This printed uid=1000 gid=1000 groups=1000,1002 and the container list.

Set group_add in Docker Compose

In Compose, the same fix is group_add. Read the number from an environment variable, so the file works on hosts with different GIDs:

services:
  ci-agent:
    image: docker:29.9.3-cli
    user: "1000:1000"
    group_add:
      - "${DOCKER_GID:?set DOCKER_GID to the GID of /var/run/docker.sock}"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: sleep infinity

Then write the value into .env next to the file:

echo "DOCKER_GID=$(stat -c %g /var/run/docker.sock)" > .env
docker compose up -d

Without .env, Compose stopped right away with required variable DOCKER_GID is missing a value, which beats a container that starts and then fails. With it, id inside ci-agent showed groups=1000,1002 and docker ps listed the containers.

Give containers less than the full socket

A container with the socket has root on your host, so group_add doesn't make it safer. It only lets a non-root process use that power. Mounting the socket with :ro doesn't limit the API either. Many apps, like Homepage or Uptime Kuma, only need to list containers. A socket proxy covers that case. Its README puts the risk plainly: "Giving access to your Docker socket could mean giving root access to your host, or even to your whole swarm".

Run docker-socket-proxy with read-only access

This Compose file puts tecnativa/docker-socket-proxy:v0.5.0 on an internal network. The app container runs as user 1000, has no socket mount and no group tricks, and talks to the proxy over TCP:

services:
  socket-proxy:
    image: tecnativa/docker-socket-proxy:v0.5.0
    environment:
      CONTAINERS: 1
      POST: 0
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - socket

  client:
    image: docker:29.9.3-cli
    user: "1000:1000"
    environment:
      DOCKER_HOST: tcp://socket-proxy:2375
    command: sleep infinity
    networks:
      - socket

networks:
  socket:
    internal: true

CONTAINERS: 1 allows the container endpoints, and POST: 0 allows only GET and HEAD requests. Don't publish port 2375 to the host.

What a 403 from the proxy means

From the client, docker ps listed both containers. Everything else was refused:

$ docker compose exec client docker run --rm docker:29.9.3-cli true
docker: Error response from daemon: <html><body><h1>403 Forbidden</h1>
Request forbidden by administrative rules.
</body></html>

docker images failed the same way, because IMAGES was not enabled, and so did docker stop, because it's a POST. The proxy log shows each blocked call, such as "POST /v1.56/containers/create HTTP/1.1" with status 403. When an app behind the proxy fails with this error, find the API section in its log and enable only that variable.

Errors that look like permission denied but aren't

Two other messages show up in the same searches. They need different fixes.

failed to connect to the docker API, is the daemon running

With the daemon stopped, Docker 29.9.3 printed one long line. It starts with failed to connect to the docker API at unix:///var/run/docker.sock and ends like this:

check if the path is correct and if the daemon is running: dial unix /var/run/docker.sock: connect: no such file or directory

Older clients say Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?, a question with 3.3 million views. The key part is no such file or directory. The socket isn't there, so start the daemon with sudo systemctl start docker and check sudo systemctl status docker if it won't stay up.

A leftover DOCKER_HOST gives the same error with a different path. In the lab, DOCKER_HOST=unix:///run/user/1001/docker.sock, a rootless socket that didn't exist, made docker ps fail even though the system daemon was running. docker context ls warned that the variable overrides the active context. unset DOCKER_HOST fixed it.

WARNING: Error loading config file

If you ran sudo docker login or other sudo docker commands before, ~/.docker may belong to root. In the lab, docker ps as alice still worked but printed:

WARNING: Error loading config file: open /home/alice/.docker/config.json: permission denied

Docker ignores your config, including registry logins, until you take the folder back:

sudo chown -R "$USER":"$USER" "$HOME/.docker"

The warning was gone on the next run. For more permission errors, the Grafana and Prometheus volume guide covers bind mount ownership, which is a different problem from the socket.

FAQ

Running Docker without sudo

How do I run Docker commands without sudo?

Add your user to the docker group with sudo usermod -aG docker $USER, then log out and back in or run newgrp docker. Check with id that docker appears in your groups. If you'd rather not give your account root-equivalent access, use rootless mode instead.

Why does docker work with sudo but not without it?

The socket is owned by root:docker with mode 660. Root can always open it, so sudo docker works. Your user can only open it as a member of the docker group in the current session.

I added my user to the docker group. Why do I still get permission denied?

Your current shell still has the old group list. Open a new login session or run newgrp docker. If id shows the group and it still fails, check ls -l /var/run/docker.sock. A socket owned by root:root means the daemon started before the group existed, so restart it.

Security and containers

Is chmod 666 on docker.sock safe?

No. It lets every account and service on the host control Docker, which means root on the host. It also resets when the daemon restarts, so it doesn't even fix the problem for long.

Is adding a user to the docker group a security risk?

Yes, in the same way as giving that user sudo. The Docker docs state that the group grants root-level privileges. Only add trusted users, or use rootless mode.

How do I fix docker.sock permission denied in a container?

Run the container with the socket's numeric group: --group-add "$(stat -c %g /var/run/docker.sock)", or group_add in Compose. A group name like docker resolves inside the image and usually has the wrong number. If the app only reads container state, give it a socket proxy instead of the socket.

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

DEV Community: DeployLark

Elasticsearch in Docker: Fix vm.max_map_count Too Low

Table of contents

Fix vm.max_map_count bootstrap exit 78

Confirm the host value and the exact log line

Raise it on the Docker host, then persist it

single-node can WARN and still start

Fix Connection refused to localhost:9200

Don't connect to localhost from the app container

Wait until the HTTP port is ready

Fix 401 missing authentication credentials

Working Compose checklist

FAQ

What does vm.max_map_count control?

Why does the container exit with code 78?

Does discovery.type=single-node remove the need for sysctl?

Can I set vm.max_map_count inside the Elasticsearch container?

Why does my app get connection refused on localhost:9200?

How do I set the elastic user password in Compose?

Redis in Docker: Fix Connection Refused, NOAUTH and MISCONF

Fix Connection refused from another container

Don't connect to localhost from the app container

Check bind in a mounted redis.conf

Fix DENIED Redis is running in protected mode

Why the plain image has no protected mode

Set a password instead of turning protected mode off

Fix NOAUTH and a password that never applied

Pass the password with --requirepass

Use an ACL user when your app wants a username

Fix MISCONF and append-only Permission denied

Why saves to /data fail

Fix ownership, don't switch off the check

A Redis Compose file that avoids these errors

compose.yaml and .env

Check it

FAQ

Connection errors

Why does Redis refuse connections between Docker Compose containers?

How do I connect to Redis in Docker from the host machine?

How do I fix DENIED Redis is running in protected mode in Docker?

Password and persistence errors

How do I set a Redis password with an environment variable in docker-compose?

How do I use a Redis username with a password in docker-compose?

How do I fix MISCONF Redis is configured to save RDB snapshots in Docker?

MongoDB in Docker: Fix Authentication Failed and Init Scripts

Fix Authentication failed with MONGO_INITDB_ROOT_USERNAME

Connect to the service name, not localhost

Add authSource=admin for the root user

Fix a password that changed in .env but not in MongoDB

Why MONGO_INITDB_ROOT_PASSWORD is ignored on restart

Change the password with mongosh

Fix docker-entrypoint-initdb.d scripts that don't run

Create the app user in the right database

Run a new script on an existing volume

Fix MongoParseError for passwords with special characters

Percent-encode the password in the connection string

Connect from the host through a published port

A MongoDB Compose file that avoids these errors

compose.yaml, .env and the secret file

Check it

FAQ

Login errors

Why does MongoDB in Docker say Authentication failed when the password is right?

What is the default username and password for the MongoDB Docker image?

How do I connect to MongoDB in Docker from the host?

Setup and init scripts

Why are my docker-entrypoint-initdb.d scripts not running?

How do I create a database and user for a MongoDB container on startup?

How do I change the MongoDB root password in Docker?

PostgreSQL in Docker: Fix Password Authentication Failed

Fix password authentication failed after changing POSTGRES_PASSWORD

Why the new password never applied

Change the password inside the database

Fix role "root" does not exist and role "postgres" does not exist

psql and pg_isready inside the container

POSTGRES_USER replaces the postgres role

Fix Database is uninitialized and superuser password is not specified

Unset .env variables and dollar signs

Make Compose fail before it starts anything

Fix connection refused and pg_hba errors from other containers

Fix `Connection refused` from another container

Check `bind` in a mounted redis.conf

Fix `DENIED Redis is running in protected mode`

Pass the password with `--requirepass`

How do I fix `DENIED Redis is running in protected mode` in Docker?

How do I fix `MISCONF Redis is configured to save RDB snapshots` in Docker?

Fix `password authentication failed` after changing POSTGRES_PASSWORD

Fix `role "root" does not exist` and `role "postgres" does not exist`

Fix `Database is uninitialized and superuser password is not specified`