How to use Docker Compose deployments with HCS.

Docker Compose

A guide on how to use Docker Compose deployments with HCS.

If you are using Docker Compose based deployments, you need to understand how Docker Compose works with HCS.

In all cases the Docker Compose (docker-compose.y[a]ml) file is the single source of truth.

Defining environment variables

You have the following compose file:

version: "3.8"

services:
  db:
    image: adminer
    environment:
      TEST: ${TEST}

And you define TEST and ANOTHERTEST environment variables inside HCS, only TEST will be used, as HCS cannot determine where to add ANOTHERTEST environment variable.

So if you want to use ANOTHERTEST environment variable, you need to add it to the compose file.

version: "3.8"

services:
  db:
    image: adminer
    environment:
      TEST: ${TEST}
      ANOTHERTEST: ${ANOTHERTEST}

Raw Docker Compose Deployment

You can set with docker compose build pack to deploy your compose file directly without most of HCS magic. It is called Raw Compose Deployment.

What is still set?

HCS will still add the following labels (if they are not set) to your application:

labels:
  - HCS.managed=true
  - HCS.applicationId=5
  - HCS.type=application

What to set?

To use HCS Proxy (Traefik), you need to set the following labels to your application:

labels:
  - traefik.enable=true
  - "traefik.http.routers.<unique_router_name>.rule=Host(`HCS.io`) && PathPrefix(`/`)"
  - traefik.http.routers.<unique_router_name>.entryPoints=http

Connect to Predefined Networks

By default, each compose stack is deployed to a separate network, with the name of your resource uuid. This will allow to each service in your stack to communicate with each other.

But in some cases, you would like to communicate with other resources in your account. For example, you would like to connect your application to a database, which is deployed in another stack.

To do this you need to enable Connect to Predefined Network option on your Service Stack page, but this will make the internal Docker DNS not work as expected.

Here is an example. You have a stack with a postgres database and a laravel application. HCS will rename your postgres stack to postgres-<uuid> and your laravel stack to laravel-<uuid> to prevent name collisions

If you set Connect to Predefined Network option on your laravel stack, your laravel application will be able to connect to your postgres database, but you need to use the postgres-<uuid> as your DB_HOST environment variable.