Publish several services of a compose app

Make more than one service of a compose file reachable, each on a hostname of its own and, if you like, under a path of the app's main hostname.

Last updated 19 November 2026View as Markdown

A compose app always publishes one service, its main one, on the app's hostname. You can publish further services of the same file. Each one answers:

  • on a hostname of its own, <service>-<app>.<org>.apps.<domain>, with its own certificate;
  • on custom domains you assign to it;
  • and, if you give it a path, under that path of the app's main hostnames (/api → api).

Every other service stays on the app's private network, reachable from the others by its service name. Replace app-id with the app's id.

Prerequisites

  • A compose app (see Create an app from a compose file) and permission for deploy:UpdateApp; in the console, also deploy:DescribeApp to open the app; to assign domains, deploy:ManageDomain; to apply the change, deploy:DeployApp.
  • The service in the compose file, listening on the port you publish. When the service declares expose: ports, the published port must be one of them.

Publish a service

  1. Open the app, then choose the Runtime tab.
  2. Under Published services, choose Publish a service.
  3. Enter the Service and its Port. Leave Own hostname on to get <service>-<app>.<org>.apps.<domain>; enter a Path on the main hostnames such as /api to route that path too. Turn on Remove the path before forwarding if the service expects /users rather than /api/users.
  4. Choose Publish, then deploy the app.

The service's container publishes its port from the next deployment on. Until then the hostname and path are configured but not routed. Changing a hostname or a path later needs no deployment.

The request is refused (400) when:

  • the service is the main one, is listed twice, or is not in the compose file;
  • the port is not one the service declares under expose:;
  • two services share a path, or one path lies under another (/api and /api/v2);
  • the service name cannot start a hostname (it holds _ or .) and Own hostname is on;
  • the generated hostname <service>-<app> is the name of another app in your organization, is already the hostname of another app's service, or is longer than 63 characters;
  • more than 8 further services are listed, or the app is not a compose app.

Assign a custom domain to a service

A custom domain serves the main service unless you assign it to another one.

  1. On the Domains tab, choose Add a domain, enter the hostname and pick the Service.
  2. To move an existing domain, open its row menu and choose Serve another service.

Moving a domain applies on the machine's next poll, within a minute; nothing is redeployed. A domain whose service is no longer published serves the main service again.

How requests are routed

On the app's machine, Caddy checks each request in this order:

  1. a path of a published service on the app's main hostnames, the longest path first;
  2. a published service's own hostnames and the domains assigned to it;
  3. everything else on the main hostnames: the main service.

Each published service also gets the app's environment, like the main one.

A service's own hostname is a different origin from the app's main hostname: a browser applies CORS between them and does not share cookies set for one with the other. When the web front end calls the API from the browser with cookies, publish the API on a path of the main hostname instead. A generated hostname is reserved: creating an app with the slug <service>-<app> is refused (409) while that service answers on it.

Did this page help you?