# 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.

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](create-an-app-from-a-compose-file.md)) 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

**Console**
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.

**CLI**
```sh
dcloud deploy apps update app-id \
  --compose-routes '{"service":"api","port":8080,"pathPrefix":"/api"}'
dcloud deploy apps deploy app-id
```

**API**
```http
PATCH /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601
{ "composeRoutes": [{ "service": "api", "port": 8080, "ownHostname": true, "pathPrefix": "/api", "stripPrefix": false }] }
```

`composeRoutes` is the whole list: send every further service you want published; `[]` publishes
only the main one.

**Terraform**
```hcl
resource "dcloud_app" "shop" {
  # …
  compose_service = "web"
  compose_port    = 3000
  compose_routes = [
    { service = "api", port = 8080, own_hostname = true, path_prefix = "/api", strip_prefix = false },
  ]
}
```

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.

**Console**
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**.

**CLI**
```sh
dcloud deploy domains add app-id --domain api.example.com --service api
dcloud deploy domains update app-id <domain-id> --service web
```

**API**
```http
POST /deploy/api/apps/3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601/domains
{ "domain": "api.example.com", "service": "api" }
```

**Terraform**
```hcl
resource "dcloud_app_domain" "api" {
  app_id  = dcloud_app.shop.id
  domain  = "api.example.com"
  service = "api"
}
```

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.

## Related

- [Compose files](compose-files.md)
- [Add a custom domain](add-a-custom-domain.md)
