Skip to content
This page was translated with AI and may contain inaccuracies. Help improve it on GitHub.

Migrate from nginx or Nginx Proxy Manager ​

Existing nginx sites can be imported into Gately as listeners and sites. You verify them next to nginx, switch over, and if something goes wrong you go back to nginx. Configs generated by Nginx Proxy Manager (NPM) import the same way, including proxy hosts, redirection hosts, access lists and forced HTTPS.

When to use this, and what you need ​

  • You run nginx as a reverse proxy, static server or HTTP-to-HTTPS redirect and want Gately's Web Services to take over.
  • You can run nginx -T on the nginx host, and Gately can reach the sites' backends.
  • nginx and Gately cannot listen on the same port at the same time, so you test on another port first and swap ports as the last step.
  • Certificates are not part of the import. Issue new ones with Gately (see Wildcard certificate and DDNS), or let Gately read the certificate files nginx uses now.

What you end up with ​

  • Each listen port becomes a Gately listener and each server block a site. Common directives such as proxy_pass, root, return, location, allow / deny and add_header are converted. Imported listeners and sites start out disabled.
  • You can go back at any time: disable the Gately listener and start nginx again.

Steps: plain nginx ​

1. Export the config ​

Run this on the nginx host and keep the full output:

bash
nginx -T > nginx-T.txt
# when nginx runs in Docker
docker exec nginx nginx -T > nginx-T.txt

The output of nginx -T contains every included file, and Gately expands includes the way nginx does.

2. Preview and import ​

  1. Open "Web → Web Services" and click "Import nginx" in the page header.

  2. Paste the contents of nginx-T.txt into the box, or click "Read from file".

  3. Click "Preview". The preview groups sites by listening port and lists each site's type, backend or directory, source file and line, and anything that needs attention: directives that use variables, domains without a certificate, and the reason a site cannot be converted.

    Import preview: four sites are ready, certificates still to add

  4. Leave "Enable right after import" unticked and click "Import N sites". Listeners are named "nginx :port" and marked "Imported from nginx config"; both listeners and sites are disabled. Importing again is safe, existing domains are skipped.

Converted directives include proxy_pass (with upstream weights, backups and balancing policy), root / alias static directories, return redirects and fixed content, add_header, proxy_set_header, gzip, allow / deny, per-location backends and access control, auth_request (becomes forward auth), auth_basic (becomes basic auth with shared users, which you must fill in), and listen ... proxy_protocol and quic. TCP/UDP forwarding in stream is set up under Port Forwarding. The full list is in Web Services · Import nginx config.

3. Prepare certificates ​

The preview lists the certificate files nginx uses. You have two options:

  • Issue new certificates under "SSL Certificates", preferably a DNS-01 wildcard certificate.
  • Keep using nginx's files: "Add certificate", source "Read from file", and enter the certificate and private key paths. Gately checks the files regularly and reloads them, which suits setups where certbot keeps renewing. When Gately runs in Docker, mount the certificate directory into the container.

4. Verify on another port first ​

While nginx still holds 80 and 443, make Gately listen elsewhere:

  1. On the Web Services page find the "nginx :443" listener, click "Edit listener", change the port to 8443, turn on "Enable" and save.
  2. Click "Sort & batch" in the page header, tick the sites to test, click "Enable" in the toolbar, then "Done sorting".
  3. Reach Gately's port with curl and an explicit domain; no DNS change is needed:
bash
curl -I --resolve nas.example.com:8443:127.0.0.1 https://nas.example.com:8443/

Check each site's page, login, WebSocket and uploads or downloads. Adjust differences in the site's settings, for example tick "Skip backend certificate verification" for a backend with a self-signed certificate, and leave "Use backend address as Host" off when the backend needs the original Host.

5. Switch over ​

  1. Stop nginx (systemctl stop nginx or docker stop nginx) to free 80 and 443.
  2. Change the Gately "nginx :443" listener port back to 443 and turn on the "nginx :80" listener.
  3. Open the live domains and confirm.
  4. Decide about uninstalling nginx only after everything checks out.

Roll back ​

Turn the Gately listeners off and start nginx again (systemctl start nginx). Gately keeps the configuration, so you can fix the problem and switch again. Config history can also restore settings from before a change.

Switching site by site, without downtime ​

With many sites you may not want to move them all at once. Let Gately own 443 and hand the domains you have not moved yet to nginx:

  1. Make nginx listen on local ports only and accept the PROXY protocol so visitors' real IPs survive. Change every listen 443 ssl; to listen 127.0.0.1:8443 ssl proxy_protocol; and port 80 likewise to listen 127.0.0.1:8080;. Add this in http or in each server:

    nginx
    set_real_ip_from 127.0.0.1;
    real_ip_header proxy_protocol;

    Then reload nginx.

  2. Import the config in Gately (step 2) and keep the "nginx :443" listener on port 443.

  3. On that listener click "Set default site": type "Reverse proxy", backend https://127.0.0.1:8443, tick "Skip backend certificate verification", "Send PROXY v2 to the backend" and "Use the visited domain as SNI", then save. Every domain with no matching Gately site lands here and nginx keeps serving it.

  4. Turn the listener on. From then on, enable one Gately site at a time as you move each domain. Enabled sites are served by Gately and the rest by nginx.

  5. If a site misbehaves, disable it. It goes back to nginx and no other domain is affected.

Steps: Nginx Proxy Manager ​

NPM generates plain nginx config, so it imports the same way; only nginx -T has to run inside the NPM container.

  1. Export the config on the NPM host (replace npm with the name of the NPM container; docker ps lists it):

    bash
    docker exec npm nginx -T > npm-nginx-T.txt

    You can also copy just the contents of nginx/proxy_host/*.conf, nginx/redirection_host/*.conf and nginx/dead_host/*.conf from NPM's data volume; the NPM snippets they include are filled in automatically.

  2. Paste it into "Import nginx" and preview. NPM's own default page, 443 fallback and admin interface (port 81) do not show up in the preview.

  3. Certificates: the preview names the certificate files inside the NPM container; handle them as in "3. Prepare certificates" above. With "Read from file", use the location of NPM's data volume on the host, for example ./letsencrypt/live/npm-1/fullchain.pem, and mount that directory into the container first when Gately runs in Docker.

  4. After the import, add the access list users again (see the table). Verification, switch-over and rollback are exactly as above.

What each NPM setting becomes:

In NPMAfter import
Proxy Host Scheme / Forward Hostname / PortThe backend address of a reverse proxy site, for example http://192.168.1.10:5000; https backends are not verified, as in NPM
Custom LocationsPer-path backends; a path in the Forward Hostname becomes "Strip path prefix"
Websockets Support, HTTP/2 SupportNothing to set; Gately supports both automatically
Force SSLThe site of the same name on port 80 redirects to https://{host} with the path kept
HSTS Enabled / HSTS SubdomainsThe Strict-Transport-Security response header
Cache AssetsSite cache: CSS, JS, images, fonts and other static assets are cached for 30 minutes, other paths are not cached
Block Common ExploitsNot imported; the preview mentions it once. If you want it, choose a WAF instance on the site's Security tab and start in detect-only mode
Access List IP rulesThe site's IP allowlist or blocklist
Access List usernames and passwordsBasic auth with shared users; NPM's password file is not read, so add the users again in Gately. Nobody gets through until you do
Access List Satisfy AnyOnly the authentication is imported and listed IPs have to sign in too (Gately cannot exempt IPs from authentication); the preview lists those IPs
Redirection HostA redirect site with the same status code and "Keep path" setting
404 HostA fixed-content site returning 404
Default Site (404, 444, redirect)The default site of the port 80 listener
StreamsNot imported; configure them in Port Forwarding
SSL certificates (Let's Encrypt or custom)Not imported; see step 3

What still does not convert: directives in custom nginx configuration under Advanced that have no Gately equivalent are listed under "Directives not converted" in the preview or produce a warning; regex location blocks, variables set inside if, and Lua do not convert either. Review those sites after the import and adjust them by hand where needed.

Verify ​

  • After the preview passes, test every site's status code and content with curl --resolve.
  • After the switch, open the sites and check that the browser shows a valid certificate and that WebSocket applications such as Jellyfin or Home Assistant work.
  • Site cards show request and error counts, and site statistics show visitor IPs and the status code distribution.
  • Once the imported listeners and sites are enabled, the run log shows https listener :443 (N sites).

Troubleshooting ​

The preview says "Not imported" because there is nothing to convert. The backend uses variables whose value cannot be determined statically (for example set inside if or taken from a map with several entries), or the site uses regex location blocks or Lua. Create it by hand with the table above.

The listener fails to start because the port is in use. nginx still holds it. Stop nginx, or put the Gately listener on another port.

The import warns about a missing certificate. Certificates are not imported; follow step 3. NPM keeps its certificates under letsencrypt/live/npm-N/ or data/custom_ssl/npm-N/ in its data volume, where N is NPM's internal certificate number.

A site returns 502 after enabling. The backend address is unreachable from where Gately runs (with Docker use --network host or a routable address), or the backend is https with a self-signed certificate: tick "Skip backend certificate verification".

The application does not see the visitor's real IP. The site option "Add X-Forwarded-*" is on by default; the application has to trust Gately's address as a proxy. In the site-by-site approach nginx needs real_ip_header proxy_protocol as shown above.

Released under the Apache-2.0 license.