Skip to content

Custom Nginx Configuration

Appliku automatically generates an Nginx configuration for each application, handling SSL termination, reverse proxying, and domain routing. You can override this with a custom configuration directly from the dashboard.

Enabling Custom Nginx Configuration

  1. Go to your application's Settings > Nginx tab
  2. Enable Use Custom Nginx Configuration
  3. The editor appears, pre-populated with the full Nginx configuration currently generated for your application

The pre-populated config includes your current proxy pass settings, upstream definitions, volume mounts, and domain configuration — giving you a complete starting point.

Warning

Once custom config is enabled, new volumes you add to the application will not be automatically reflected in the Nginx config. You must update the configuration manually whenever you add or change volumes.

Editing the Configuration

The configuration editor shows your full Nginx config. Edit it to add your customizations, then click Save and Apply, Save and Deploy or Save:

  • Save and Apply stores the configuration and writes it at once for all domains of the application, with no build. nginx tests it first, and Appliku keeps the old configuration on an error. It is available for servers with dockerized nginx and for clusters.
  • Save and Deploy stores the configuration and queues a deployment, which writes it for all domains of the application.
  • Save stores the configuration. It does not change nginx.

See Save, Save and Apply, and Save and Deploy for the details.

Note

The Reload button on the Server > Nginx tab does not apply a saved custom config. It only makes nginx read the files that are already on the server.

Managed Directives

A handful of directives are owned by Appliku and cannot appear in your custom config. They are rendered by the platform at the server-block level and would conflict with anything you add:

  • listen
  • server_name
  • ssl_certificate, ssl_certificate_key
  • access_log, error_log
  • resolver
  • http2 (managed by the HTTP Protocol selector on the Nginx tab; see Nginx Settings)

Saving a custom config that contains any of these top-level directives returns a validation error. The pre-populated starting template that the editor loads on first enable already has them stripped out, so you only need to worry about them if you paste config from elsewhere.

Controlling Auto-Update Behavior

The Update Nginx Configuration on Deploy checkbox (also in the Nginx tab, for applications on a standalone server) controls whether Appliku regenerates the Nginx config on each deployment.

  • Enabled (default) — Appliku regenerates the config on every deploy, keeping it in sync with your domain and process settings
  • Disabled — your custom config is preserved across deployments; domain and volume changes will not be automatically reflected

When using a custom config, you typically want to keep Update Nginx Configuration on Deploy enabled so that managed sections (SSL, upstream definitions) stay current, while your custom directives in the editable area are preserved.

Common Customizations

Increase Upload Size Limit

The default client_max_body_size may be too small for applications that handle large file uploads:

client_max_body_size 100M;

Increase Proxy Timeouts

For long-running requests (e.g., report generation, file processing):

proxy_read_timeout 300s;
proxy_connect_timeout 300s;
proxy_send_timeout 300s;

Add Custom Headers

Add security or caching headers:

add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;

Enable Gzip Compression

Compress responses to reduce bandwidth usage:

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
gzip_min_length 1000;

Checking for Config Errors

On Save, Appliku checks the syntax of the custom config and refuses the managed directives. This check does not run nginx -t, so it does not prove that nginx can load the configuration. A config can pass the check and still fail in nginx, for example because of an unknown directive or a wrong value.

Save and Apply runs nginx -t before it changes a file. If the test fails, nothing changes: nginx keeps the old configuration, and the result under the buttons shows the file and the nginx -t output. Fix the custom config and click Save and Apply again. If the failed file is not a file of this application, a team owner or admin can use Server > Nginx > Repair nginx.

A deployment (Save and Deploy, and every deployment on a server with host nginx) writes the files and reloads nginx without this test. If nginx refuses the config, the reload fails, and nginx keeps running with the configuration that it had loaded before. The refused file stays on the server, so later reloads of that nginx can also fail until you fix it.

To find the error after a deployment, a team owner or admin can:

  1. Go to Server > Nginx tab (on a cluster, the load balancer server)
  2. Check the Config validity status and the error log

If you are not an owner or admin, ask one of them to check. Fix the custom config, then click Save and Apply (or Save and Deploy on a server with host nginx).

Reverting to the Auto-Generated Configuration

To go back to the fully managed Nginx configuration:

  1. Disable Use Custom Nginx Configuration in Application Settings > Nginx tab
  2. Ensure Update Nginx Configuration on Deploy is enabled
  3. Click Save and Deploy

Appliku will regenerate the Nginx configuration from scratch based on your current application settings.