{"id":13558757,"url":"https://github.com/tozd/docker-nginx-proxy","last_synced_at":"2025-07-20T12:05:39.380Z","repository":{"id":32636330,"uuid":"36222538","full_name":"tozd/docker-nginx-proxy","owner":"tozd","description":"Dockerized nginx reverse proxy. Read-only mirror of https://gitlab.com/tozd/docker/nginx-proxy","archived":false,"fork":false,"pushed_at":"2025-06-03T08:42:04.000Z","size":123,"stargazers_count":42,"open_issues_count":8,"forks_count":10,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-06-03T19:25:07.548Z","etag":null,"topics":["docker","docker-image","letsencrypt","nginx","reverse-proxy","ssl"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tozd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["plast8","mitar"]}},"created_at":"2015-05-25T09:36:22.000Z","updated_at":"2025-06-03T08:42:06.000Z","dependencies_parsed_at":"2023-10-14T20:03:53.597Z","dependency_job_id":"210176d1-ea53-4fdf-baca-c5a5fc8aedd0","html_url":"https://github.com/tozd/docker-nginx-proxy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tozd/docker-nginx-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tozd%2Fdocker-nginx-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tozd%2Fdocker-nginx-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tozd%2Fdocker-nginx-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tozd%2Fdocker-nginx-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tozd","download_url":"https://codeload.github.com/tozd/docker-nginx-proxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tozd%2Fdocker-nginx-proxy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266120229,"owners_count":23879278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-image","letsencrypt","nginx","reverse-proxy","ssl"],"created_at":"2024-08-01T12:05:08.325Z","updated_at":"2025-07-20T12:05:39.365Z","avatar_url":"https://github.com/tozd.png","language":"Shell","funding_links":["https://github.com/sponsors/plast8","https://github.com/sponsors/mitar"],"categories":["Shell","docker"],"sub_categories":[],"readme":"# tozd/nginx-proxy\n\n\u003chttps://gitlab.com/tozd/docker/nginx-proxy\u003e\n\nAvailable as:\n\n- [`tozd/nginx-proxy`](https://hub.docker.com/r/tozd/nginx-proxy)\n- [`registry.gitlab.com/tozd/docker/nginx-proxy`](https://gitlab.com/tozd/docker/nginx-proxy/container_registry)\n\n## Image inheritance\n\n[`tozd/base`](https://gitlab.com/tozd/docker/base) ← [`tozd/dinit`](https://gitlab.com/tozd/docker/dinit) ← [`tozd/nginx`](https://gitlab.com/tozd/docker/nginx) ← [`tozd/nginx-mailer`](https://gitlab.com/tozd/docker/nginx-mailer) ← [`tozd/nginx-cron`](https://gitlab.com/tozd/docker/nginx-cron) ← `tozd/nginx-proxy`\n\n## Tags\n\n- `ubuntu-xenial`\n- `ubuntu-bionic`\n- `ubuntu-focal`\n- `ubuntu-jammy`\n- `ubuntu-noble`\n\n## Volumes\n\n- `/var/log/dnsmasq`: Log files for an internal lightweight DNS resolver when one is not provided by Docker and when `LOG_TO_STDOUT` is not set to `1`.\n- `/var/log/dockergen`: Log files for docker-gen when `LOG_TO_STDOUT` is not set to `1`.\n- `/var/log/letsencrypt`: (Debug) log files for Let's encrypt service.\n- `/ssl`: Volume with SSL keys for hosts, together with any optional extra configuration for them. All Let's encrypt generated keys together with Let's encrypt authentication keys are stored here as well. Persist this volume to not lose state.\n\n## Variables\n\n- `DOCKER_HOST`: Where to connect to access Docker daemon to monitor for new containers. Default is `/var/run/docker.sock` inside the container.\n- `LETSENCRYPT_EMAIL`: If set, enables automatic generation of SSL keys using [Let's encrypt](https://letsencrypt.org/) service. By setting it you agree to [Let’s Encrypt Subscriber Agreement](https://letsencrypt.org/repository/).\n- `LETSENCRYPT_ARGS`: Any additional arguments you might want to pass to Let's encrypt's certbot.\n- `LOG_TO_STDOUT`: If set to `1` output logs to stdout (retrievable using `docker logs`) instead of log volumes.\n\n## Description\n\nImage providing a reverse-proxy using [Nginx](http://nginx.org) HTTP server with support for HTTPS virtual hosts.\n\nYou can use this image as it is, or you can extend it and add configuration files for your virtual hosts.\n\nWhen `LOG_TO_STDOUT` is set to `1`, Docker image logs output to stdout and stderr. All stdout output is JSON.\n\n## Automatic configuration\n\nThis image uses [docker-gen](https://github.com/jwilder/docker-gen) to dynamically generate Nginx configuration files\nfor containers exposing HTTP virtual hosts. This works automatically even across container restarts. You configure\nvirtual host by configuring environment variables on containers for which you want to provide a reverse proxy:\n\n- `VIRTUAL_HOST` – a comma separated list of virtual hosts provided by the container\n- `VIRTUAL_URL` – a comma separated list of URL paths provided by the container; they will be mapped to the HTTP\n  root (`/`) of the container\n- `VIRTUAL_ALIAS` – a comma separated list of URL paths provided by the container, they will be mapped to the same\n  HTTP path of the container\n- `VIRTUAL_PORT` – if container exposes more than one port, or you do not want to use the default port `80`, you can\n  configure a custom port to which a reverse proxy should connect on the container\n- `VIRTUAL_NETWORK` – if container is connected to more than one network, this variable can be used to select which\n  network should be used (by default, the first network is used, but the order is not guaranteed)\n- `VIRTUAL_LETSENCRYPT` – if set, this image will automatically generate and enable a SSL key for the virtual host\n  using [Let's encrypt](https://letsencrypt.org/) service, if [Let's encrypt feature is enabled](#lets-encrypt)\n\nWhen running a Docker image with your HTTP content, you can specify environment variables.\n\nThis will make the reverse proxy resolve `http://example.com/` into the `example` container:\n\n```bash\ndocker run --name example ... --env VIRTUAL_HOST=example.com --env VIRTUAL_URL=/ ...\n```\n\nThis will make the reverse proxy resolve `http://example.com/foo` into the `example1` container, but\nThis will make the reverse proxy resolve `http://example.com/bar` into the `example2` container.\n\n```bash\ndocker run --name example1 ... --env VIRTUAL_HOST=example.com --env VIRTUAL_URL=/foo ...\ndocker run --name example2 ... --env VIRTUAL_HOST=example.com --env VIRTUAL_URL=/bar ...\n```\n\nMultiple containers can provide content for the same host and URL paths – Nginx will balance load across all of them.\n\nA difference between `VIRTUAL_URL` and `VIRTUAL_ALIAS` is that `VIRTUAL_URL` maps all outside paths to the internal HTTP root\n(`/`) of the container. This is useful when your container provides static content under the root and you want to\nexpose it elsewhere to the outside. But the downside is that the internal references between resources, if a container\nassumes content is under `/`, might not work correctly. For example, a HTML tag `\u003cimg src=\"/foobar.png\" /\u003e`, which\nwould from the perspective of the container, from the outside might resolve to something completely else, or not resolve\nat all. This is why it is often better to serve content in containers under the same path as outside, and use\n`VIRTUAL_ALIAS` to map them 1:1. But this means that the container has to be configured accordingly as well.\n\n### HTTPS\n\nIf you want to use HTTPS for a virtual host, you should mount a `/ssl` volume into the container and provide\nSSL key for a virtual host.\n\nFor host `example.com` you should provide `/ssl/example.com.key` and `/ssl/example.com.crt`\nfiles. Certificate file should contain the full chain needed to validate the certificate.\nIf those two files exist, the image will automatically configure the virtual host to use HTTPS and redirect any\nnon-HTTPS traffic to HTTPS.\n\nIf you want any extra configuration for non-HTTPS traffic, you can provide `/ssl/example.com_nonssl.conf` file which\nwill be included for the non-HTTPS configuration. Similarly, for extra configuration for the HTTPS site, provide\n`/ssl/example.com_ssl.conf` file. Of course, filenames should match the hostname of your virtual host.\n\n### Let's encrypt\n\nIf you want to enable support for automatic generation of SSL keys using [Let's encrypt](https://letsencrypt.org/)\nservice, and you agree to [Let’s Encrypt Subscriber Agreement](https://letsencrypt.org/repository/), then you\ncan set `LETSENCRYPT_EMAIL` environment variable to your e-mail address when running this image to enable it. From then\non any container having `VIRTUAL_LETSENCRYPT` environment variable set will get a SSL certificate automatically\ngenerated and enabled, and periodically renewed.\n\nAll generated keys together with Let's encrypt authentication keys are stored under `/ssl` volume.\n\nYou should probably configure [`MAILTO` environment variable](https://gitlab.com/tozd/docker/nginx-cron) to your e-mail\naddress to receive reports from th daily cron job, and regularly check logs in `/var/log/letsencrypt` and\n`/var/log/dockergen` volumes to see if there are any issues with key generation and renewal.\nFor e-mail sending to work you have to configure at least [`REMOTES` environment variable](https://gitlab.com/tozd/docker/nginx-mailer)\nas well.\n\nYou can list in `/ssl/letsencrypt.manual.list` file additional domains you want the container to obtain SSL keys.\n\n## Dynamic resolving of containers\n\nIf extending the image, you can put sites configuration files under `/etc/nginx/sites-enabled/` to add custom sites.\n\nAlternatively, you can mount a volume into `/etc/nginx/sites-volume/` directory and provide sites there.\n\nTo support static configuration files for containers which have dynamic IP addresses, this image configures\n([when not provided by Docker](https://docs.docker.com/engine/userguide/networking/configure-dns/))\nNginx with an internal lightweight DNS resolver which dynamically resolves container hostnames into IPs.\nHere is an example of site configuration using DNS resolving:\n\n```\nserver {\n    listen 80;\n    server_name example.com;\n\n    # We want to resolve container IPs dynamically, so we use a variable to make\n    # Nginx resolve it again and again and not only at the start (so that it works\n    # if containers change their IPs).\n\n    location / {\n        set $example example;\n        proxy_pass http://$example:3000;\n    }\n}\n```\n\nThis assumes that you have a container with hostname `example`:\n\n```bash\ndocker run --name example --hostname example ...\n```\n\nBy default, because of caching it can take up to 5 seconds for Nginx to start resolving a virtual host to a new\ncontainer IP address after a change.\n\n## GitHub mirror\n\nThere is also a [read-only GitHub mirror available](https://github.com/tozd/docker-nginx-proxy),\nif you need to fork the project there.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftozd%2Fdocker-nginx-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftozd%2Fdocker-nginx-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftozd%2Fdocker-nginx-proxy/lists"}