HTTP and Domain

Use http-server to run nginx. Use domain to generate nginx config for host names and routes.

HTTP Server

type: http-server
http_port: 80
https_port: false
access_log:
  max_size_mb: 200
  max_files: 1

Fields:

Field	Required	Default	Purpose
image	No	docker.io/library/nginx:stable	nginx image.
http_port	No	80	Host port mapped to container port 80.
https_port	No	false	Host port mapped to container port 443. Use false or omit it to disable HTTPS.
access_log.max_size_mb	No	200	Access log rotation threshold in MiB.
access_log.max_files	No	1	Number of archived access log files to keep.

Domain

type: domain
server: nginx
hosts: ["example.com", "www.example.com"]
routes:
  - kind: reverse_proxy
    location: /
    target: ${api:url}

Fields:

Field	Required	Purpose
server	Yes	The http-server unit that serves this domain.
hosts	Yes	Host names for the nginx server_name.
proxy	No	Trusted proxy settings for real client IPs.
custom_config	No	Raw nginx config inserted inside the server block.
routes	No	Routes served under this domain. See Routes.

Routes

Routes describe how nginx handles requests inside a domain.

Common fields:

Field	Required	Purpose
kind	Yes	Route type. Supported values are reverse_proxy, uwsgi, fastcgi, serve_files, redirect, and return.
location	Yes	nginx location path or regex. Regex locations must be wrapped in single quotes, for example location: '~ \.php$'.

Reverse proxy to an app

routes:
  - kind: reverse_proxy
    location: /
    target: ${api:url}

Pass requests to a uWSGI server

routes:
  - kind: uwsgi
    location: /
    target: ${django:socket}

Pass requests to a FastCGI server

routes:
  - kind: fastcgi
    location: /
    target: ${phpfpm:socket}

Use target for a FastCGI upstream such as unix:/run/php-fpm.sock or 127.0.0.1:9000. References like ${phpfpm:socket} are supported.

Serve files

Serve files exported from a static or app unit:

routes:
  - kind: serve_files
    location: /static
    root: ${django:export}

Serve a single-page app:

routes:
  - kind: serve_files
    location: /
    root: ${site:export}
    spa: true

Redirect requests

routes:
  - kind: redirect
    location: /old
    target: https://example.com$request_uri

Redirects use HTTP 302 by default. Set permanent: true to use HTTP 301:

routes:
  - kind: redirect
    location: /moved
    target: https://example.com/new
    permanent: true

target is passed to nginx as a literal value. It does not resolve ${unit:key} references.

Return a status code

routes:
  - kind: return
    location: /health
    status: 204

Return a status code with a body:

routes:
  - kind: return
    location: /gone
    status: 410
    body: gone

body is optional and is returned as a literal string.

Trusted proxy settings

Use this when nginx is behind a proxy and you need the real client IP.

Cloudflare:

proxy:
  type: cloudflare

Fastly:

proxy:
  type: fastly

Custom:

proxy:
  type: custom
  header: X-Forwarded-For
  proxies:
    - 192.0.2.10

Custom nginx config

custom_config is inserted inside the generated server block.

custom_config: |
  client_max_body_size 50m;
  add_header X-Frame-Options DENY always;

Keep this short. Use it for settings that dpl does not model yet. dpl inserts this value as raw nginx config and does not validate it.

Routes also accept custom_config, allowing dpl to inject route-specific settings directly into the generated location blocks.

routes:
  - kind: fastcgi
    location: '~ \.php$'
    target: ${phpfpm:socket}
    custom_config: |
      fastcgi_index index.php;
      fastcgi_param SCRIPT_FILENAME $document_root/$fastcgi_script_name;

Log

Nginx’s logs are written to the http-server state directory <base>/state/<unit>/log/:

• runtime.log is an error log in CRI k8s-file format.
• access.log is an access log in JSONL format.

Optional config for access log:

type: http-server
access_log:
  max_size_mb: 200
  max_files: 1