npmplus-docker-sync

🤔 What does it do?

You run apps in Docker and use Nginx Proxy Manager (NPM) to make them reachable under nice domains with HTTPS. Normally, every new app means opening the NPM UI, clicking through a form, picking a certificate — and remembering to delete the host when the app is gone.

npmplus-docker-sync does that for you. You describe the domain right next to the app, and NPM follows automatically.

services:
  whoami:
    image: traefik/whoami
    networks: [npm]
    labels:
      npm.proxy.domains: "whoami.example.com"   # ← that's it

A few seconds after docker compose up, NPM has a proxy host whoami.example.com — pointing at the right container and port, with the matching certificate attached and HTTPS enforced.

If you know Traefik's labels: it's that workflow, but for Nginx Proxy Manager — you keep NPM and its UI exactly as they are.

✨ Highlights

• 🏷️ One label is enough — port, certificate and HTTPS are figured out automatically
• 🧩 All four NPM types — proxy hosts, redirections, TCP/UDP streams and 404 hosts
• 🔐 Certificates pick themselves — the best matching one, exact before wildcard
• 🎯 No more 502 Bad Gateway — uses the container's IP on the network NPM can actually reach
• 🛡️ Hard to break — never touches hosts you made by hand, and refuses suspicious mass deletions
• ⚡ Fast and quiet — reacts in seconds, and 20 containers starting at once cause one update
• 🤝 Drop-in for Redth/npm-docker-sync — its labels work unchanged
• 🔒 Secure by default — talks to Docker through a read-only socket proxy, runs as non-root in a ~8 MB scratch image
• 📊 Observable — health checks, a JSON status page and Prometheus metrics built in

🚀 Quick start

You need: Docker with Compose. Ready-made stacks for NPM and NPMplus live in deploy/ — from a two-container try-out to a hardened setup with CrowdSec:

1. Pick a stack

git clone https://github.com/VentumPhoenix/npmplus-docker-sync.git
cd npmplus-docker-sync/deploy/npmplus/2-standard

2. Fill in .env

cp .env.example .env    # domain of the admin UI, e-mail, password

3. Start it

docker compose up -d
docker compose logs -f npmplus-docker-sync

4. Label your apps — as in the example above, or start deploy/example-app. Done! 🎉

[!TIP] Adding it to an NPM that already has hosts? existing-npm starts with DRY_RUN=true: the tool only logs what it would change. Check the log, then set it to false.

docker run -d --name npmplus-docker-sync \
  --network npm \
  -e DOCKER_HOST=tcp://docker-socket-proxy:2375 \
  -e NPM_URL=http://npm:81 \
  -e NPM_IDENTITY=admin@example.com \
  -e NPM_SECRET=changeme \
  -e NPM_NETWORK=npm \
  ghcr.io/ventumphoenix/npmplus-docker-sync:latest

make build     # static binary ./npmplus-docker-sync
make test      # race-enabled unit tests
make check     # fmt + vet + lint + test

📖 Examples

Copy what you need into the labels: of your container.

A web app with HTTPS

npm.proxy.domains: "app.example.com"

…on a specific port, with several domains

npm.proxy.domains: "app.example.com, www.app.example.com"
npm.proxy.port: "8080"

…behind a login (Authelia, Authentik, …) and an access list (login: NPMplus only)

npm.proxy.domains: "kuma.example.com"
npm.proxy.auth_request: "authelia"
npm.proxy.access_list: "Intern"

Redirect an old domain

npm.redirect.domains: "old-app.example.com"
npm.redirect.forward_domain: "app.example.com"

Expose a database as a TCP stream

npm.stream.incoming_port: "5432"

Show a 404 page for a parked domain

npm.404.domains: "parked.example.com"

Several things from one container — just number them:

npm.proxy.domains: "app.example.com"          # 0: the web UI
npm.1.proxy.domains: "metrics.example.com"    # 1: a second port
npm.1.proxy.port: "9090"
npm.2.stream.incoming_port: "5432"            # 2: the database

Leave a container alone

npm.enable: "false"

📚 Every label — with what it does, its default and aliases — is listed in docs/FIELDS.md. The rules behind them are in docs/LABELS.md.

npm.<kind>.<field>              one resource
npm.<index>.<kind>.<field>      several resources (npm.<kind>.<index>.<field> works too)
npm.<field>                     shorthand for npm.proxy.<field>
npm.enable=false                ignore this container

npm.proxy.certificate: "auto"                # the default
npm.proxy.certificate: "12"                  # a fixed id
npm.proxy.certificate: "*.home.example.com"  # whatever covers this domain
npm.proxy.certificate: "name:My wildcard"    # by name
npm.proxy.certificate: "new"                 # request a Let's Encrypt one
npm.proxy.certificate: "none"                # plain HTTP

# on npmplus-docker-sync: HTTPS everywhere ...
NPM_PROXY_SSL_FORCE: "true"

# ... except on this container
npm.proxy.ssl.force: "false"

npm.proxy.group: "Production"

npmplus-docker-sync validate              # check the labels of running containers
docker compose config --format json > stack.json
npmplus-docker-sync validate stack.json   # check a stack before it starts
npmplus-docker-sync sync                  # one sync, then exit

🛡️ Is it safe?

Short answer: it is built to never destroy something you care about.

How it recognizes its own hosts: each one gets a comment line at the top of its Advanced config in NPM — # npmplus-docker-sync: managed from Docker labels, do not edit or remove this line | …. nginx ignores it, this tool relies on it: leave it there. A host without it counts as hand-made.

[!IMPORTANT] Update this tool before NPMplus. The next NPMplus release clears the place where versions up to v1.0.0-beta.9 recorded their hosts; v1.0.0-beta.10 adds the line above to every host on its first run. Details

[!CAUTION] Before your first real run: if this tool ever created a host for something you still need — like the NPM admin UI itself — make sure that container still has its npm.* labels. Run once with DRY_RUN=true and check the log for would delete lines.

Docker access is read-only. The recommended setup goes through a docker-socket-proxy that only allows reading containers and events, so even a compromised sync container cannot start, stop or change anything. The container runs as non-root from an empty scratch image with a read-only filesystem, and the NPM password never appears in logs.

More: every deletion rule · threat model

⚙️ Configuration

Most setups only need these:

Any variable can be read from a file by adding _FILE (Docker secrets). All variables, with aliases and tips: docs/CONFIGURATION.md.

NPM or NPMplus? Both work, detected automatically. The tool reads which fields the server accepts from the server itself, so a new NPM or NPMplus release rarely needs an update here. NPMplus-only settings (HTTP/3, CrowdSec, groups, forward auth, …) are simply left out against NPM and reported once.

[!TIP] Pin your NPM/NPMplus image to a version tag rather than :latest.

🔍 How it works

flowchart LR
    D[🐳 Docker<br/>container events] --> L[Read labels]
    L --> W[Wait for the burst<br/>to settle · 3s]
    W --> C{Compare with NPM}
    C -->|new| A[Create host]
    C -->|changed| U[Update host]
    C -->|unchanged| S[Do nothing]
    C -->|container gone| R[Remove own host<br/>with safety checks]

1. On startup it compares all labelled containers with everything in NPM and fixes the differences — so downtime never leaves things out of sync.
2. Then it listens for containers starting and stopping, and syncs again within seconds.
3. Every 5 minutes it does a full check anyway, and every minute it looks for new certificates.
4. Unchanged hosts cost nothing — no API write happens unless something actually changed.

Why the container IP? NPM must reach your app, and container names only work if NPM resolves Docker's internal DNS — the usual cause of 502 Bad Gateway. So the upstream is the container's IP in the network NPM shares (NPM_NETWORK). How it is chosen · Architecture

📊 Monitoring

With HEALTH_ADDR=:8080:

The image has a built-in Docker HEALTHCHECK, so docker ps shows its health and other services can use depends_on: { condition: service_healthy }.

🩺 Troubleshooting

curl -s -X POST http://npm:81/api/tokens \
  -H 'Content-Type: application/json' \
  -d '{"identity":"admin@example.com","secret":"changeme"}'

🔄 Coming from Redth/npm-docker-sync?

Your labels and environment variables work unchanged. Both tools can even run against the same NPM without deleting each other's hosts. To take over the hosts Redth's tool created, set MIGRATE_FROM_REDTH=true — see docs/MIGRATION.md.

📚 Documentation

🗺️ Roadmap

1.0.0 ✅ — labels, variables and the ownership marker are stable (what that means).

Next — in 1.x releases, without breaking changes:

• The next NPMplus release in the test matrix (its development branch is tested every night already)
• Upstream modes: container name, or host IP with published ports
• Waiting for a container to be healthy before publishing it (NPM_WAIT_HEALTHY)
• Docker Swarm service labels
• NPMplus mTLS client certificates and certificate requests for streams

See the changelog for what changed, and COMPATIBILITY.md for what stays stable.

🤝 Contributing

Bug reports, missing labels and pull requests are welcome — see CONTRIBUTING.md. If this tool saves you some clicks, a ⭐ helps others find it.

🙏 Acknowledgements

Built on Nginx Proxy Manager by jc21, NPMplus by ZoeyVid and docker-socket-proxy by Tecnativa. Inspired by Traefik's label-driven workflow and by Redth/npm-docker-sync. Not affiliated with or endorsed by any of these projects.

📄 License

MIT