typeai/zombie-nginx repository overview

⁠NGINX template for Zombie

An Alpine-based Docker container with mainline nginx, configuration generator, and automatic TLS.

⁠Usage

Assuming you have an application server in a container called webapp, that you want to serve, add in your docker-compose.yml:

webapp-nginx:
  image: typeai/zombie-nginx
  restart: always
  depends_on:
    - webapp
  volumes:
    - "/path/to/webapp-nginx.yml:/etc/appconf/nginx.yml:ro"
    - "/path/to/certificates/:/etc/nginx/certs"
    - "your-static-files:/var/www/webapp-static:ro"
  environment:
    - "[email protected]"
  ports:
    - "0.0.0.0:80:80"
    - "0.0.0.0:443:443"

With your webapp-nginx.yml looking like this:

servers:
  webapp:
    server_name: my-webapp.example.com
    upstream: uwsgi://webapp:12345
    static_files: /var/www/webapp-static
    tls: auto

If you have your-static-files Docker volume with static files for your web application, and a uWSGI instance (or something else talking the uwsgi protocol) listening on port 12345 in the webapp container, this setup will feed a nice nginx.conf to nginx, and server your application via HTTPS with certificate obtained from Let's Encrypt.

⁠nginx.yml options

Each entry in the servers section represents a separate virtual host. You can create multiple virtual hosts.

• check_host_header: optional, bool, default yes; whether to close connection on invalid HTTP_HOST

• server_name: required, string; domain name where your site lives, can be a list of domains separated with space

• static_files: optional, string or mapping or array of mappings; maps a location on the virtual host to a mounted volume with static files

  • static_files.location: required, string: location to serve the files at
  • static_files.path: required, string: path where the static files are mounted
  • static_files.spa: optional, string: if specified, file to be served for requests not matching any existing static file, e.g. index.html

  if a string is given, it is interpreted to be static_files.path, with static_files.location set to `/static. You can provide an array of mappings to specify multiple static files mounts.

• tls: required, no, auto or mapping or array of mappings; tells nginx where to find your TLS certificates, to get them automatically via Let's Encrypt, or to serve unencrypted HTTP

  • tls.certificate: required, string: the path to a full-chain certificate file
  • tls.key: required, string: the path to a private key file, matching the certificate
  • tls.root_chain: required once per virtual host, string: the path to a root chain file for use with OCSP stapling

  the paths are relative to /etc/nginx/certs (or /path/to/certificates if you follow the example above). You can provide an array of mappings in this format to specify multiple certificates.

• upstream: optional, string or mapping; defines an upstream server to forward requests to

  • upstream.url: required, string: upstream server's URL with protocol, e.g. uwsgi://some-host:12345. Supported protocols are uwsgi and http
  • upstream.name: optional, string: name used to identify this upstream server inside nginx config. Must be unique across all virtual hosts. If not given, one will be generated automatically
  • upstream.location: required, string: location to attach the upstream at

  if a string is given, it is interpreted to be upstream.url, with upstream.location set to /, and upstream.name $server_name-upstream

⁠Setting nginx options directly

To add or override an nginx option directly in the generated nginx.conf file, add desired settings in the http_raw_options, server_raw_options, or upstream_raw_options array.

http_raw_options:
  - keepalive_timeout 10
servers:
  webapp:
    server_name: my-webapp.example.com
    server_raw_options:
      - client_max_body_size 10M
    upstream:
      name: webapp-upstream
      url:  uwsgi://webapp:12345
      location: /
      upstream_raw_options:
        - add_header "Access-Control-Allow-Methods" "GET, POST, OPTIONS"

⁠Known issues

The project was only tested with a few specific setups, and certainly not with every possible combination of settings.

⁠Contributing

Of course, pull requests are welcome. Keep in mind though that ease of use and as little configuration as possible are among main goals of this project.