{"id":13858990,"url":"https://github.com/nginx-le/nginx-le","last_synced_at":"2025-07-14T01:32:36.643Z","repository":{"id":44442364,"uuid":"62781305","full_name":"nginx-le/nginx-le","owner":"nginx-le","description":"Nginx with automatic let's encrypt (docker image)","archived":false,"fork":false,"pushed_at":"2024-09-07T17:53:33.000Z","size":91,"stargazers_count":636,"open_issues_count":0,"forks_count":118,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-09-07T19:05:46.763Z","etag":null,"topics":["automation","docker","letsencrypt","nginx","proxy","ssl-certificates"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nginx-le.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["umputun"]}},"created_at":"2016-07-07T06:37:29.000Z","updated_at":"2024-09-05T06:30:48.000Z","dependencies_parsed_at":"2024-06-02T21:57:30.106Z","dependency_job_id":"6cc11933-abb1-4f3e-b830-12b4ac2592ce","html_url":"https://github.com/nginx-le/nginx-le","commit_stats":null,"previous_names":["umputun/nginx-le"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx-le%2Fnginx-le","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx-le%2Fnginx-le/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx-le%2Fnginx-le/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nginx-le%2Fnginx-le/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nginx-le","download_url":"https://codeload.github.com/nginx-le/nginx-le/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225938744,"owners_count":17548544,"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":["automation","docker","letsencrypt","nginx","proxy","ssl-certificates"],"created_at":"2024-08-05T03:02:28.720Z","updated_at":"2024-11-22T17:30:36.116Z","avatar_url":"https://github.com/nginx-le.png","language":"Shell","funding_links":["https://github.com/sponsors/umputun"],"categories":["Shell"],"sub_categories":[],"readme":"# NGINX-LE - Nginx web and proxy with automatic let's encrypt [![Docker Automated build](https://img.shields.io/docker/automated/jrottenberg/ffmpeg.svg)](https://hub.docker.com/r/umputun/nginx-le/) \n\nSimple nginx image (alpine based) with integrated [Let's Encrypt](https://letsencrypt.org) support.\n\n## How to use\n\n- get [docker-compose.yml](https://github.com/umputun/nginx-le/blob/master/docker-compose.yml) and change things:\n  - set timezone to your local, for example `TZ=UTC`. For more timezone values check `/usr/share/zoneinfo` directory\n  - set `LETSENCRYPT=true` if you want an automatic certificate install and renewal\n  - `LE_EMAIL` should be your email and `LE_FQDN` for domain\n  - for multiple FQDNs you can pass comma-separated list, like `LE_FQDN=aaa.example.com,bbb.example.com`\n  - alternatively set `LETSENCRYPT` to `false` and pass your own cert in `SSL_CERT`, key in `SSL_KEY` and `SSL_CHAIN_CERT`\n  - `LE_ADDITIONAL_OPTIONS` can be set to anything you want to append to certbot, for example `LE_ADDITIONAL_OPTIONS=--preferred-chain \"ISRG Root X1\" --debug`.\n  - use provided `etc/service-example.conf` to make your own `etc/service.conf`. Keep ssl directives as is:\n    ```nginx\n    ssl_certificate SSL_CERT;\n    ssl_certificate_key SSL_KEY;\n    ssl_trusted_certificate SSL_CHAIN_CERT;\n    ```\n- make sure `volumes` in docker-compose.yml changed to your service config\n- you can map multiple custom config files to in compose using `service*.conf` filename pattern, \n  see `service2.conf` in [docker-compose.yml](https://github.com/nginx-le/nginx-le/blob/master/docker-compose.yml)\n  file for reference\n\n  Alternatively, mount directory with `*.conf` files into `/etc/nginx/conf.d-le` directory inside\n  the container to have them all copied at once.\n- `stream*.conf` files are picked up into `/etc/nginx/stream.d/` directory and included into `stream`\n  section of the Nginx configuration, see `stream2.conf` in `docker-compose.yml` file for reference.\n  \n  Alternatively, mount directory with `*.conf` files into `/etc/nginx/conf.d-le` directory inside\n  the container to have them all copied at once.\n- pull image - `docker-compose pull`\n- if you don't want a pre-built image, make you own. `docker-compose build` will do it\n- start it `docker-compose up`\n\n### Configuration files variables replacement\n\nOn start of the container all following text matches in custom configuration files you mounted will be replaced,\nvariable with dollar sign (`$`, like `$LE_FQDN`) will be taken from environment, please see next table for their list.\n\n| Matching pattern | Value | nginx usage | Description |\n| ---------------- | ----- | ----------- | ----------- |\n| SSL_CERT       | `/etc/nginx/ssl/$SSL_CERT`       | `ssl_certificate` | Public SSL certificate, sent to client |\n| SSL_KEY        | `/etc/nginx/ssl/$SSL_KEY`        | `ssl_certificate_key` | SSL private key, not sent to client |\n| SSL_CHAIN_CERT | `/etc/nginx/ssl/$SSL_CHAIN_CERT` | `ssl_trusted_certificate` | Trusted SSL certificates, not sent to client |\n| LE_FQDN        | `$LE_FQDN` | `server_name` | List of domains, useful for configuration with single `server` block |\n\n### Environment variables list\n\n| Variable | Default value | Description |\n| -------- | ------------- | ----------- |\n| SSL_CERT       | `le-key.pem` | certbot `privkey.pem` new filename     |\n| SSL_KEY        | `le-crt.pem` | certbot `fullchain.pem` new filename   |\n| SSL_CHAIN_CERT | `le-chain-crt.pem` | certbot `chain.pem` new filename |\n| LETSENCRYPT | `false` | Enables Let's Encrypt certificate retrieval and renewal |\n| LE_FQDN     | | comma-separated list of domains for Let's Encrypt certificate, required if `LETSENCRYPT` is `true` |\n| LE_EMAIL    | | comma-separated list of emails for Let's Encrypt certificate, required if `LETSENCRYPT` is `true` |\n| LE_ADDITIONAL_OPTIONS | | Additional options to be appended to certbot command |\n| TZ          | | Timezone, if set will be written to container's `/etc/timezone` |\n\n### `envsubst` templates\n\nIf you need to use any other environment variables you could mount your configuration as `/etc/nginx/templates/yourservice.conf.template` and `envsubsts` would be executed on that file. More info could be found [here](https://github.com/docker-library/docs/tree/master/nginx#using-environment-variables-in-nginx-configuration-new-in-119)\n\n## Some implementation details\n\n**Important:** provided [nginx.conf](https://github.com/umputun/nginx-le/blob/master/conf/nginx.conf) handles \nhttp-\u003ehttps redirect automatically, no need to add it into your custom `service.conf`. In case if you need a custom server on\nhttp (:80) port, make sure you [handle](https://github.com/umputun/nginx-le/blob/master/conf/nginx.conf#L62) `/.well-known/` \npath needed with `root` set for LE challenge: `location /.well-known/ {root /usr/share/nginx/html;}`\n\n- image uses alpine's `certbot` package.\n- `script/entrypoint.sh` requests LE certificate and will refresh every 10 days in case if certificate is close to expiration (30day)\n- `script/le.sh` gets SSL\n- nginx-le on [docker-hub](https://hub.docker.com/r/umputun/nginx-le/)\n- **A+** overall rating on [ssllabs](https://www.ssllabs.com/ssltest/index.html)\n\n![ssllabs](https://github.com/umputun/nginx-le/blob/master/rating.png)\n\n## Alternatives\n\n- [Reproxy](https://reproxy.io) simple edge HTTP(s) server / reverse proxy supporting various providers.\n- [Træfik](https://traefik.io) HTTP reverse proxy and load balancer. Supports Let's Encrypt directly.\n- [Caddy](https://caddyserver.com) supports Let's Encrypt directly.\n- [leproxy](https://github.com/artyom/leproxy) small and nice (stand alone) https reverse proxy with automatic Letsencrypt\n- [bunch of others](https://github.com/search?utf8=✓\u0026q=nginx+lets+encrypt)\n\n## Examples\n\n- [Reverse proxy](https://github.com/umputun/nginx-le/tree/master/example/webrtc) for WebRTC solutions,\n  where you need multiple ports on one domain to reach different services behind your `nginx-le` container.\n\n## Manual certificate renewal (`*.example.com`, DNS challenge)\n\n\u003cdetails\u003e\n\u003csummary\u003ewildcard certificate renewal\u003c/summary\u003e\n\n\nIn your `docker-compose.yml` disable automatic Let's Encrypt certificate creation/renewal.\n```yaml\n    environment:\n      - LETSENCRYPT=true\n```\n\n```shell\n# after starting nginx-le connect to it\ndocker exec -it nginx sh\n\n# change `*.example.com` to your domain name\ncertbot certonly \\\n    --manual \\\n    --manual-public-ip-logging-ok \\\n    --preferred-challenges=dns \\\n    --email \"${LE_EMAIL}\" \\\n    --agree-tos \\\n    -d \"*.example.com\"\n\n# it will ask you to create/update TXT DNS record\n# depending on your DNS provider it can take some time\n# you can check if DNS is already updated using dig utility\ndig txt _acme-challenge.example.com\n\n# copy certificates for nginx-le to use them\ncp -fv /etc/letsencrypt/live/example.com/privkey.pem /etc/nginx/ssl/le-key.pem\ncp -fv /etc/letsencrypt/live/example.com/fullchain.pem /etc/nginx/ssl/le-crt.pem\ncp -fv /etc/letsencrypt/live/example.com/chain.pem /etc/nginx/ssl/le-chain-crt.pem\n\n# use the same procedure for renewal\n```\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnginx-le%2Fnginx-le","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnginx-le%2Fnginx-le","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnginx-le%2Fnginx-le/lists"}