nginx-proxy/docker-gen

★ 4,625GoAudience · ops devopsComplexity · 3/5Setup · moderate

Mindmap

mindmap
  root((docker-gen))
    What it does
      Watches Docker containers
      Regenerates config files
      Signals services to reload
    Common uses
      nginx reverse proxy
      Log rotation
      Service discovery
    Template system
      Go template syntax
      Container metadata
      Env vars and ports
    Run modes
      On host directly
      Inside app container
      Separate container

mindmap root((docker-gen)) What it does Watches Docker containers Regenerates config files Signals services to reload Common uses nginx reverse proxy Log rotation Service discovery Template system Go template syntax Container metadata Env vars and ports Run modes On host directly Inside app container Separate container

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Auto-generate and reload an nginx reverse proxy config whenever a new container starts with a VIRTUAL_HOST environment variable

USE CASE 2

Keep log rotation config up to date as containers are added or removed without manual edits

USE CASE 3

Tech stack

GoDockernginx

Getting it running

Difficulty · moderate Time to first run · 30min

Requires access to the Docker socket, run docker-gen as a separate container to avoid exposing the socket to public-facing services.

License not described in the explanation.

In plain English

docker-gen is a Go program that watches your Docker containers and automatically generates text files whenever containers start, stop, or change. You provide a template file written with Go's template syntax, and docker-gen fills it in with live data about your running containers: their names, IP addresses, exposed ports, environment variables, and more. The most common use is generating a reverse proxy configuration. For example, when you start a new web application in a Docker container with an environment variable like VIRTUAL_HOST=example.com, docker-gen can detect that container, rebuild an nginx configuration file that includes that host name, and signal nginx to reload, all without any manual editing. This is how the popular nginx-proxy project works under the hood. Other built-in templates cover centralized logging (sending container log output to fluentd or logstash), log rotation (automatically rotating the JSON log files Docker creates for each container), and service discovery (registering containers with external systems like etcd so other services can find them). There are three ways to run docker-gen: directly on the server, bundled inside the same container as the application it configures, or as a separate standalone container that shares a volume with another container. The separate-container approach is common when you want to keep the Docker socket (which grants broad system access) away from a publicly exposed service. The command accepts a template file and an optional output destination. A -watch flag keeps it running and regenerates files whenever container state changes. The -notify option lets you specify a command or signal to send to a container after each regeneration, which is how nginx gets told to reload its configuration.

Copy-paste prompts

Prompt 1

Using docker-gen, write a Go template that generates an nginx server block for each running container that has a VIRTUAL_HOST environment variable set, then signals nginx to reload.

Prompt 2

I want docker-gen to run as a separate container alongside nginx. Show me the docker-compose.yml that mounts the Docker socket, shares a volume for the generated config, and signals nginx after each regeneration.

Prompt 3

Write a docker-gen template that generates a Fluentd log forwarding config for all running containers, using each container's name as the log tag.

Prompt 4

I have docker-gen watching containers and regenerating a config file with -watch. How do I use the -notify flag to send a HUP signal to nginx inside a different container after each config update?

Open on GitHub → Explain another repo

← nginx-proxy on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.