{"id":19175853,"url":"https://github.com/handcraftedbits/docker-nginx-host","last_synced_at":"2025-08-30T05:10:59.481Z","repository":{"id":95812067,"uuid":"63829423","full_name":"handcraftedbits/docker-nginx-host","owner":"handcraftedbits","description":"A Docker container used to easily create a secure NGINX server that is capable of hosting one or more Docker-based \"units\" of functionality, such as static content or web applications","archived":false,"fork":false,"pushed_at":"2017-03-21T20:36:16.000Z","size":22,"stargazers_count":7,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-07T19:11:28.937Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/handcraftedbits.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2016-07-21T02:15:16.000Z","updated_at":"2022-06-02T22:30:32.000Z","dependencies_parsed_at":"2023-04-30T12:01:50.704Z","dependency_job_id":null,"html_url":"https://github.com/handcraftedbits/docker-nginx-host","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/handcraftedbits/docker-nginx-host","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fdocker-nginx-host","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fdocker-nginx-host/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fdocker-nginx-host/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fdocker-nginx-host/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/handcraftedbits","download_url":"https://codeload.github.com/handcraftedbits/docker-nginx-host/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/handcraftedbits%2Fdocker-nginx-host/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272805572,"owners_count":24995916,"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","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-09T10:25:50.179Z","updated_at":"2025-08-30T05:10:59.460Z","avatar_url":"https://github.com/handcraftedbits.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NGINX Host [![Docker Pulls](https://img.shields.io/docker/pulls/handcraftedbits/nginx-host.svg?maxAge=2592000)](https://hub.docker.com/r/handcraftedbits/nginx-host)\n\nA [Docker](https://www.docker.com) container used to easily create a secure [NGINX](http://nginx.org) server that is\ncapable of hosting one or more Docker-based \"units\" of functionality, such as static content or web applications.\n\n# Features\n\n* NGINX 1.10.3\n* Designed to make creating an HTTPS server simple -- simply pick the parts you need.\n* Default SSL settings score an **A+** grade on [SSL Labs](https://www.ssllabs.com/ssltest/) when including custom\n  [Diffie-Hellman parameters](https://scotthelme.co.uk/squeezing-a-little-more-out-of-your-qualys-score/).\n* Designed to be used with [Let's Encrypt](https://letsencrypt.org) certificates.\n  * Certificates are automatically renewed.\n* Default header settings score a **B** grade on [securityheaders.io](https://securityheaders.io).\n  * Score can be improved with the addition of\n    [Content Security Policy](https://www.owasp.org/index.php/Content_Security_Policy) headers and\n    [HTTP Public Key Pinning](https://developer.mozilla.org/en-US/docs/Web/Security/Public_Key_Pinning).\n\n# Available Units\n\nThe following units are available -- simply pick and choose which ones you want to sit behind your NGINX server:\n\n| Unit                                                                                              | Description                                                                                                                                                                                                                             |\n| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| [bamboo](https://github.com/handcraftedbits/docker-nginx-unit-bamboo)                             | The [Atlassian Bamboo](https://www.atlassian.com/software/bamboo) continuous integration server.                                                                                                                                        |\n| [bitbucket](https://github.com/handcraftedbits/docker-nginx-unit-bitbucket)                       | The [Atlassian Bitbucket Server](https://www.atlassian.com/software/bitbucket/server) collaborative Git server.                                                                                                                         |\n| [confluence](https://github.com/handcraftedbits/docker-nginx-unit-confluence)                     | The [Atlassian Confluence](https://www.atlassian.com/software/confluence) team collaboration server.                                                                                                                                    |\n| [go-import-redirector](https://github.com/handcraftedbits/docker-nginx-unit-go-import-redirector) | A unit based off of [rsc/go-import-redirector](https://github.com/rsc/go-import-redirector), which simplifies the hosting of [Go](https://golang.org) [custom remote import paths](https://golang.org/cmd/go/#hdr-Remote_import_paths). |\n| [hugo](https://github.com/handcraftedbits/docker-nginx-unit-hugo)                                 | The [Hugo](https://gohugo.io) static site generator, designed for sites whose source code is hosted on GitHub.  Includes the ability to regenerate the site whenever you push a commit.                                                 |\n| [hugo-extras](https://github.com/handcraftedbits/docker-nginx-unit-hugo-extras)                   | An enhanced version of the Hugo unit which contains extra tools.                                                                                                                                                                        |\n| [jira](https://github.com/handcraftedbits/docker-nginx-unit-jira)                                 | The [Atlassian JIRA](https://www.atlassian.com/software/jira) software development tool.                                                                                                                                                |\n| [static](https://github.com/handcraftedbits/docker-nginx-unit-static)                             | A unit that hosts simple static content.                                                                                                                                                                                                |\n| [webhook](https://github.com/handcraftedbits/docker-nginx-unit-webhook)                           | A unit based off of [adnanh/webhook](https://github.com/adnanh/webhook), which allows you to execute arbitrary commands whenever a particular URL is accessed.                                                                          |\n\n# Usage\n\n## Prerequisites\n\n### Docker\n\n* Docker 1.13 or newer\n* Docker Compose 1.10.0 or newer\n  * `docker-compose.yml` must declare version `2.1` or later\n\n### SSL Certificates\n\nYou must obtain SSL certificates from Let's Encrypt by following the\n[getting started guide](https://letsencrypt.org/getting-started/).  Don't worry about writing a renewal script -- this\nDocker container handles that for you.\n\n#### A Note on Certificate Directory Names and Units\n\nKeep in mind that Let's Encrypt certificates are registered in terms of single hostnames and the directory structure\nit creates will reflect that.  For example, if you create a certificate for `mysite.com`, Let's Encrypt will create a\ndirectory named `/etc/letsencrypt/live/mysite.com`.  As long as the units you use are configured to be served from\nthat same host (via `NGINX_UNIT_HOSTS` environment variable), there will be no problem.\n\nHowever, you can configure units to be served from multiple discrete hosts, via wildcard, etc.  Consider a unit that is\nserved from `*.mysite.com` and `othersite.com` by setting the environment variable\n`NGINX_UNIT_HOSTS=*.mysite.com,othersite.com`.  NGINX Host will attempt to look for the certificate in the directory\n`/etc/letsencrypt/live/*.mysite.com,othersite.com`.  Since no such directory exists (after all, you registered your\ncertificate against `mysite.com`), NGINX Host won't be able to find your certificate.  To fix this, you need to create\na symbolic link in your local `/etc/letsencrypt` directory from `*.mysite.com,othersite.com` to `mysite.com`.\n\n### Custom Diffie-Hellman parameters\n\nThough not required, it is strongly recommended that you create custom Diffie-Hellman parameters for added security.\nIf you're unsure how to do this, please follow\n[this guide](https://scotthelme.co.uk/squeezing-a-little-more-out-of-your-qualys-score/).\n\n## Configuration\n\nIt is highly recommended that you use Docker orchestration software such as\n[Docker Compose](https://www.docker.com/products/docker-compose) as any NGINX Host setup you are likely to use will\ninvolve several Docker containers.  This guide will assume that you are using Docker Compose.\n\nTo begin, let's create a `docker-compose.yml` file that contains the bare minimum set of services and volumes required:\n\n```yaml\nversion: \"2.1\"\n\nvolumes:\n  data:\n\nservices:\n  host:\n    image: handcraftedbits/nginx-host\n    ports:\n      - \"443:443\"\n    volumes:\n      - data:/opt/container/shared\n      - /etc/letsencrypt:/etc/letsencrypt\n      - /home/me/dhparam.pem:/etc/ssl/dhparam.pem\n```\n\nThe `host` service creates an instance of NGINX Host, listening on port `443`.  If you wish, you can also listen on\nport `80` and NGINX Host will automatically redirect HTTP requests to HTTPS.\n\nNext, we mount the following volumes:\n\n* `data`: a volume used to share information between NGINX Host and its units.  This volume must always be mounted to\n  `/opt/container/shared`.\n* `/etc/letsencrypt`: the location of your Let's Encrypt certificates and renewal information.  Typically this will be\n  located in the `/etc/letsencrypt` directory on your local system.\n* `/etc/ssl/dhparam.pem`: the file containing your custom Diffie-Hellman parameters.  Note that this volume does not\n  have to be mounted, but it is highly recommended to do so in the interest of increased security.\n\n## Adding Units\n\nThe configuration we created in the previous section will start an NGINX server but is not particularly useful as it\nhosts nothing.  To fix that, let's add some static content by adding the `static` unit (shown here as the `mysite`\nservice):\n\n```yaml\nversion: \"2.1\"\n\nvolumes:\n  data:\n\nservices:\n  mysite:\n    image: handcraftedbits/nginx-unit-static\n    environment:\n      - NGINX_UNIT_HOSTS=mysite.com\n      - NGINX_URL_PREFIX=/\n    volumes:\n      - data:/opt/container/shared\n      - /home/me/mysite:/opt/container/www-static\n\n  proxy:\n    image: handcraftedbits/nginx-host\n    links:\n      - mysite\n    ports:\n      - \"443:443\"\n    volumes:\n      - data:/opt/container/shared\n      - /etc/letsencrypt:/etc/letsencrypt\n      - /home/me/dhparam.pem:/etc/ssl/dhparam.pem\n```\n\nThe `NGINX_UNIT_HOSTS` environment variable specifies that we will be listening for requests to `mysite.com` and the\n`NGINX_URL_PREFIX` environment variable specifies that all static content will be available under `/`.  Finally, we\nmount the local directory `/home/me/mysite` as the root of our static content (for more information on configuring the\n`static` unit, refer to the [documentation](https://github.com/handcraftedbits/docker-nginx-unit-static)).\n\nNote that we must add a link in the `proxy` service to each unit that NGINX Host will host.  In this case, we add a link\nto the `mysite` service.\n\nThere's more to NGINX Host than just static content though -- there are [several units](#available-units) you can mix\nand match to create your ideal server.  Consult the appropriate unit documentation for more information.\n\n## Additional NGINX Configuration\n\nAdditional configuration at the virtual host level (i.e., within a `server` block) can be added by mounting a file\ncontaining additional NGINX directives via the location `/etc/nginx/extra/${hosts}.extra.conf`.  For example, if you\nhave a unit hosted on `*.mysite.com` and `othersite.com` with additional NGINX directives located in the file\n`/home/me/myextra.conf`, you would add the volume\n`/home/me/myextra.com:/etc/nginx/extra/*.mysite.com,othersite.com.extra.conf` to the `docker run` command used to run\nthe NGINX Host container.\n\nYou can also add additional configuration at a higher level (in this case, within the `http` block) by mounting a file\ncontaining additional NGINX directives via the location `/etc/nginx/extra.conf`.  For example, if you have additional\nNGINX directives located in the file `/home/me/nginxextra.conf`, you would add the volume\n`/home/me/nginxextra.conf:/etc/nginx/extra.conf` to the `docker run` command used to run the NGINX host container.\n\n## Running NGINX Host\n\nAssuming you are using Docker Compose, simply run `docker-compose up` in the same directory as your\n`docker-compose.yml` file.  Otherwise, you will need to start each container with `docker run` or a suitable\nalternative, making sure to add the appropriate environment variables and volume references.\n\n# Reference\n\n## Environment Variables\n\n### Units\n\nThe following environment variables are required by all units (please consult unit documentation for any additional\nenvironment variables that may be required):\n\n#### `NGINX_UNIT_HOSTS`\n\nA comma-delimited list used to specify which virtual server or virtual servers will host the unit.  In terms of NGINX\nconfiguration, this environment variable is used for the\n[`server_name`](http://nginx.org/en/docs/http/server_names.html) directive and follows the same syntax, with the\nexception that the values are comma-delimited.\n\n**Required**\n\n#### `NGINX_URL_PREFIX`\n\nThe URL prefix to use.  Combined with the `NGINX_UNIT_HOSTS` environment variable, this determines the full URL used to\naccess the unit.  For example, using `NGINX_UNIT_HOSTS=mysite.com` and `NGINX_URL_PREFIX=/site` would cause unit\ncontent to be served via the URL `https://mysite.com/site`.\n\n**Required**\n\n### NGINX\n\nThe following environment variables are used to configure the NGINX server used by NGINX Host:\n\n#### `NGINX_GZIP`\n\nUsed to set the value of the NGINX [`gzip`](http://nginx.org/en/docs/ngx_http_gzip_module.html#gzip) directive.\n\n**Default value**: `on`\n\n#### `NGINX_HEADERS_REMOVE`\n\nA comma-delimited list used to specify which header or headers will be removed from all responses.  This is generally\nused for security purposes by removing headers that identify the server.\n\n**Default value**: `Server,X-Powered-By`\n\n#### `NGINX_KEEPALIVE_TIMEOUT`\n\nUsed to set the value of the NGINX\n[`keepalive_timeout`](http://nginx.org/en/docs/ngx_http_core_module.html#keepalive_timeout) directive.\n\n**Default value**: `65`\n\n#### `NGINX_PROXY_READ_TIMEOUT`\n\nUsed to set the value of the NGINX\n[`proxy_read_timeout`](http://nginx.org/en/docs/ngx_http_proxy_module.html#proxy_read_timeout) directive.\n\n**Default value**: `120s`\n\n#### `NGINX_RESOLVER`\n\nUsed to set the value of the NGINX [`resolver`](http://nginx.org/en/docs/ngx_http_core_module.html#resolver) directive.\n\n**Default value**: `8.8.8.8 8.8.4.4`\n\n#### `NGINX_TYPES_HASH_MAX_SIZE`\n\nUsed to set the value of the NGINX\n[`types_hash_max_size`](http://nginx.org/en/docs/ngx_http_core_module.html#types_hash_max_size) directive.\n\n**Default value**: `2048`\n\n#### `NGINX_UNIT_WAIT`\n\nUsed to set the time, in seconds, that NGINX Host will wait for units to launch.  The value only needs to be changed if\na particular unit takes an excessively long time to launch.\n\n**Default value**: `2`\n\n#### `NGINX_WORKER_CONNECTIONS`\n\nUsed to set the value of the NGINX\n[`worker_connections`](http://nginx.org/en/docs/ngx_core_module.html#worker_connections) directive.\n\n**Default value**: `768`\n\n#### `NGINX_WORKER_PROCESSES`\n\nUsed to set the value of the NGINX\n[`worker_processes`](http://nginx.org/en/docs/ngx_core_module.html#worker_processes) directive.\n\n**Default value**: `auto`\n\n#### `NGINX_WWW_REDIRECT_HOSTS`\n\nA comma-delimited list used to specify which host(s) will have a `www` to non-`www` redirect added automatically.  This\nis useful if you want to force the use of \"naked\" (non-`www`) domains.  Note that you cannot use wildcards for this\nenvironment variable.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhandcraftedbits%2Fdocker-nginx-host","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhandcraftedbits%2Fdocker-nginx-host","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhandcraftedbits%2Fdocker-nginx-host/lists"}