Configure Service networking
Every Service has a resource-specific Docker network for the components in its Compose definition. Coolify also creates a shared Docker network named coolify on each connected server.
By default, Service components use only their resource-specific network. Enable Connect To Predefined Network when they must also join the predefined Docker network selected for the Service. On a standard installation, that network is coolify.
Understand the two Service networks
| Network | Purpose |
|---|---|
| Service network | A private network created for one Service stack. Its name is based on the Service UUID. Components in the stack use it automatically. |
| Coolify network | The shared, attachable network named coolify that Coolify creates on the server. Applications, standalone Databases, the Coolify Proxy, and Services that enable Connect To Predefined Network can use it. |
The coolify network lets separate Coolify resources on the same server communicate without publishing host ports. It does not extend to another server.
The default destination uses the Docker network named coolify. If an administrator creates another destination and selects it for the Service, Connect To Predefined Network attaches the Service components to that selected network instead. The setting attaches one predefined network; it does not connect the Service to every destination or Docker network on the server.
Choose the connection target
Components in one Compose definition communicate over the Service network. Use the Compose services: key as the hostname and the port where the dependency listens inside its container:
services:
api:
image: example/api:1.0
environment:
DATABASE_URL: postgresql://app:password@database:5432/app
database:
image: postgres:17In this example, api connects to database:5432. It must not use localhost, a public domain, or a published host port. Inside api, localhost refers to the api container itself.
You do not need ports: or a domain for this private connection. A Compose depends_on entry can control startup order, but the calling component must still tolerate the dependency taking time to become ready.
Verify the connection
After changing networking configuration:
- Save the setting or Compose definition, then restart or deploy the Service.
- Review Show Deployable Compose and confirm each component has the intended networks and ports.
- Open Terminal on the calling component and resolve the intended internal hostname using a tool available in that image.
- Connect to the dependency's internal port and verify an application-level response, not only DNS resolution.
- For a domain, make an HTTPS request from an external client and confirm it reaches the intended component.
- For a published port, test from an allowed client and confirm the port is blocked from networks that should not reach it.
If private communication fails, first confirm that both containers run on the same server and share at least one Docker network. Matching project or environment names do not create network connectivity.
Networking boundaries
- A project or environment organizes resources; it is not a network boundary.
- Coolify creates a separate
coolifynetwork on each connected server. - A Service uses its resource-specific network even when another resource has the same project or environment.
- Connect To Predefined Network joins the Service to its one predefined destination network, normally
coolify. - Docker service names resolve only on networks shared by the relevant containers.
- Domains provide routed application access; they do not merge Docker networks.
- Published ports expose server interfaces and require firewall and protocol security.