{"id":24708361,"url":"https://github.com/surface-security/nginx","last_synced_at":"2026-04-18T17:04:59.876Z","repository":{"id":114546656,"uuid":"473506094","full_name":"surface-security/nginx","owner":"surface-security","description":"Nginx with Go templates support (instead of envsubst)","archived":false,"fork":false,"pushed_at":"2023-02-15T18:47:15.000Z","size":14,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-22T06:14:14.447Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/surface-security.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":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-24T07:49:44.000Z","updated_at":"2022-03-24T15:22:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"bd27ea07-8278-4346-9d09-05e4c43be2e8","html_url":"https://github.com/surface-security/nginx","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/surface-security/nginx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surface-security%2Fnginx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surface-security%2Fnginx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surface-security%2Fnginx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surface-security%2Fnginx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/surface-security","download_url":"https://codeload.github.com/surface-security/nginx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/surface-security%2Fnginx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31976806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T16:27:12.723Z","status":"ssl_error","status_checked_at":"2026-04-18T16:27:11.140Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2025-01-27T06:31:39.194Z","updated_at":"2026-04-18T17:04:59.859Z","avatar_url":"https://github.com/surface-security.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nginx with go templates\n\nnginx finally introduced support for templates in their [docker image](https://hub.docker.com/_/nginx) in the tag 1.18.\n\nBut these templates use [envsubst](https://www.man7.org/linux/man-pages/man1/envsubst.1.html) which is nice but there are no flow controls, just variable replacement.\n\nThis image does nothing else but to replace `envsubst` call with [confgen](https://github.com/fopina/confgen) allowing more powerful templating with [Go templates](https://pkg.go.dev/text/template#hdr-Actions)\n\n## Usage\n\nUsage is all the same as official nginx image: same directories, same enviornment variables, same ways to pass templates. But the expected templates are Go templates instead of envsubst.\n\nThe exposed tags in the templates are the ones in [confgen](https://github.com/fopina/confgen).\n\nconfgen does provide a build only supporting `env` (with a smaller binary) and a build using [sprig](http://masterminds.github.io/sprig/) with many more tags/functions (and a larger binary).\n\nBuilds are available for:\n* nginx mainline image\n* nginx alpine image\n\nAnd these are combined with confgen with and without sprig, for those that only need `env` (plus flow control) and rather save a couple of megabytes.\n\nFor instance, `nginx:1.19.1` official image is rebuilt into:\n* `ghcr.io/surface-security/nginx:1.19.1`\n* `ghcr.io/surface-security/nginx:1.19.1-nosprig`\n* `ghcr.io/surface-security/nginx:1.19` (if latest 1.19)\n* `ghcr.io/surface-security/nginx:1.19-nosprig` (if latest 1.19)\n\nAnd `nginx:1.19.1-alpine` into:\n* `ghcr.io/surface-security/nginx:1.19.1-alpine`\n* `ghcr.io/surface-security/nginx:1.19.1-nosprig-alpine`\n* `ghcr.io/surface-security/nginx:1.19-alpine` (if latest 1.19)\n* `ghcr.io/surface-security/nginx:1.19-nosprig-alpine` (if latest 1.19)\n\n### Debugging templates\n\nWhen the generated .conf file has errors, nginx will report the line numbers in the templated file (not the template).\n\nAs nginx container will die when there are errors, you have three options for quickly looking at the templating results:\n* Download [confgen](https://github.com/fopina/confgen) to your machine and run `confgen TEMPLATE_FILE`\n* Use this docker image calling config: `docker run -v TEMPLATE:/my.template ghcr.io/surface-security/nginx:1.19-alpine confgen /my.template`\n* Start the container with `-e NGINX_TEMPLATE_DEBUG=1` and the startup script will dump the generated files in the logs/stdout\n\n\n### Examples\n\nQuick example where Go templating flow controls are useful (versus simpler envsubst):\n* configuration that will lock content based on server_name if one is defined else allow anything\n\nTemplate:\n\n```\n{{ if ne (\"ALLOWED_HOSTS\"|env) \"\" }}\nserver {\n  listen 8080 default_server;\n  return 444;\n}\n{{ end }}\n\nserver {\n  listen 8080 deferred;\n\n  {{ if ne (\"ALLOWED_HOSTS\"|env) \"\" }}\n  server_name {{ \"ALLOWED_HOSTS\" | env | replace \",\" \" \" }};\n  {{ end }}\n\n  location / {\n    # ... rest of the config\n  }\n}\n```\n\n```\n$ docker run -v $(pwd)/example.template:/my.template:ro ghcr.io/surface-security/nginx:1.19 confgen /my.template\nserver {\n  listen 8080 deferred;\n\n\n\n  location / {\n    # ... rest of the config\n  }\n}\n```\n\n```\n$ docker run -v $(pwd)/example.template:/my.template:ro -e ALLOWED_HOSTS=my.example.com,example.com ghcr.io/surface-security/nginx:1.19-alpine confgen /my.template\nserver {\n  listen 8080 default_server;\n  return 444;\n}\n\n\nserver {\n  listen 8080 deferred;\n\n\n  server_name my.example.com example.com;\n\n\n  location / {\n    # ... rest of the config\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurface-security%2Fnginx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsurface-security%2Fnginx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsurface-security%2Fnginx/lists"}