Custom proxy overview

A custom proxy is a reverse proxy that you configure and operate outside Coolify. It accepts requests for your domains and forwards them to your application and service containers, while Coolify continues to build, deploy, and manage those resources.

This option can be useful if you already operate a reverse proxy or have routing requirements that need a separate setup. You manage the domain routes, TLS certificates, Docker network connections, and proxy maintenance that Coolify normally handles through its Traefik or Caddy integration.

Use the integrated proxy unless you need a custom setup

Traefik is the default and recommended proxy for most installations. Selecting Custom (None) does not integrate another proxy with Coolify. Domain and proxy settings in Coolify do not configure your external proxy.

Switching interrupts every route served by the current proxy. Prepare the replacement and a way to restore the previous proxy before stopping it.

What changes

Coolify-managed feature	With a custom proxy	Workaround
Routes from resource domains and ports	Setting a domain on UI and API does not create a route in your proxy.	Maintain hostname, path, and internal target-port mappings yourself, or implement discovery for your proxy.
Automatic HTTPS and wildcard certificates	Coolify does not obtain or renew certificates for your proxy.	Use the proxy's certificate support or an external ACME client. Schedule renewals and reload certificates after renewal.
HTTP redirects, default redirects, and unknown-host handling	The integrated proxy's behavior no longer applies.	Configure HTTP-to-HTTPS redirects, canonical domains, and a default virtual host in your custom proxy.
Basic authentication, middleware, and proxy response headers	Coolify does not configure authentication, middleware, or response headers for your custom proxy.	Configure authentication, forwarded headers, compression, and required response headers in your custom proxy.
Preview deployment URLs	A preview deployment does not automatically get an external route.	Create a separate route and target for each preview, or automate discovery and cleanup.
Docker network connections	Coolify does not automatically attach your custom proxy to resource networks.	Add a shared network to the Compose files for your custom proxy and the resources it needs to reach, or connect your custom proxy to the resource networks created by Coolify.
Proxy startup, restart, configuration, and logs in Coolify	Coolify does not operate your custom proxy; you must manage it externally.	Start and restart your custom proxy, validate and reload its configuration, and view its logs outside Coolify.
Integrated traffic analytics	Dashboard traffic analytics only works with Traefik or Caddy.	Set up analytics externally using the metrics provided by your custom proxy.
Routing to the Coolify dashboard and realtime services	Coolify does not generate these routes for your custom proxy.	Add routes for the dashboard, realtime updates, and web terminal to your custom proxy. See the firewall guide for required ports and realtime migration for paths.

Application builds, deployments, storage, environment variables, and container health checks still belong to Coolify. A healthy container does not confirm that its external route works; verify both.

Prepare your custom proxy

Write down the domains, application ports, path rules, WebSocket connections, redirects, authentication settings, and certificates used by your current proxy. Include preview deployments and the Coolify dashboard if you access them through the proxy.

Keep your custom proxy's Compose file, configuration, and certificates in a separate directory on the server, such as /data/custom-proxy. Configure your custom proxy to start automatically after a server reboot. Make sure you can restart it from the server terminal if the Coolify dashboard is unavailable.

Test your custom proxy before switching traffic to it. Use a test server or ports that are not already in use so your current proxy can keep running during testing.

Connect the proxy to resources

Your custom proxy can reach applications through a shared Docker network or through ports mapped to the server. A shared network lets containers on the same server communicate without publishing application ports.

If you use port mappings, configure your custom proxy to connect to the server's address and the mapped port. Keep track of the ports already used by your applications: two applications cannot bind the same port on the same server address.

Protect mapped ports

Mapped ports can expose your applications directly, allowing clients to bypass your custom proxy. Without proper firewall rules, those applications may be accessible to anyone. Restrict access to the clients that need those ports, including your custom proxy, and follow the firewall guide for rules that work with Docker-published ports.

For a connection through Docker networks, choose your resource type below.

Applications that do not use Docker Compose and one-click databases use the coolify network by default. If you configured the resource to use a different Docker network, connect your custom proxy to that network instead.

Connect your custom proxy to the same network by adding it to your proxy's Compose file:

services:
  proxy:
    # Keep your proxy image, ports, volumes, and other settings here.
    networks:
      - coolify

networks:
  coolify:
    external: true

After starting or recreating your proxy with this configuration, use the application's internal container name or network alias and internal port as the route target. For a one-click database, Coolify shows the connection details in its Internal URL.

Most databases use TCP protocols rather than HTTP. Proxying a database connection requires support for its protocol in your custom proxy.

Container names and redeploys

Application container names can change on each deployment. Service container names are generally stable, but their IP addresses can still change. Consistent container name can stabilize an application's name; it does not preserve its IP or make deployment uninterrupted.

Use stable aliases where possible, and configure your proxy to resolve target names again when their addresses change. Check that it can start while an application is offline and recover when the application returns. For an example, see how nginx finds application containers after a redeploy.

Switch to Custom (None)

Keep a recovery path

Back up /data/coolify/proxy, which contains the current proxy configuration and persistent data, including certificates and custom configuration files. Keep an SSH session active during the switch.

If you self-host Coolify, open the dashboard directly at http://<Server-IP>:8000 before stopping the proxy, and use that address during the switch. Stopping the proxy disables dashboard access through your domain if that domain uses the proxy you are stopping. Confirm that direct access works before continuing.

On a self-hosted instance, selecting Custom (None) does not remove the default published dashboard and realtime ports: 8000, 6001, and 6002. Custom Compose overrides may change those bindings. Review access separately after your new routes work.

Stop the integrated proxy

Open Servers > your server > Proxy and select Stop Proxy. Wait for Proxy Exited. Confirm that the old proxy has released the host ports the replacement will use.

Select Custom

Select Switch Proxy, confirm the warning, then choose Custom. Coolify stores this selection as NONE and leaves proxy configuration and operation to you.

Start the replacement

Apply the intended host-port bindings and start the external proxy using its own deployment procedure. Check its logs, configuration validation, certificates, and network connections.

Verify routes and recovery

Test your application routes, redirects, WebSockets, authentication, large requests, and certificate renewal. Redeploy an application and confirm the proxy finds its new address.

If you proxy the Coolify instance, verify login, live deployment updates, and the web terminal. See realtime migration for the UI and realtime targets.

Maintain the setup

Keep route configuration, certificates, renewal jobs, and backups independent of the applications they expose. Test a proxy restart and recovery after an invalid configuration change. Make sure certificate renewal still runs when any management dashboard is unavailable.

Remove a route before deleting its resource. If you attached the proxy directly to a resource's UUID network, disconnect it when the route is removed. Docker cannot remove a network while another container remains attached, so the network can remain after resource deletion.

To return to an integrated proxy, stop the external proxy and release its host ports first. Select Traefik or Caddy in Coolify, restore the relevant configuration, and follow the proxy switching procedure. Verify that running resources have the correct labels and that every route works again.

For a worked example of the decisions and problems involved, read ShadowArcanist's nginx migration case study.

On this page