Skip to main content

Deploy Docker Apps

warning

Using Docker requires Kit Plan or above.

Docker in DOM Cloud is powered by Docker rootless mode. Enabling docker features is implicitly allows running 24/7 (doesn't have to actually using docker). Because of how powerful and resouce consuming this is only available starting with Kit plan.

Docker is available only in some servers as they offer the most computing resources we currently offer

When this feature enabled, these things applied:

  • assign /etc/subuid + /etc/subgid to allow docker using sub uids for assigning containers.
  • assign /var/lib/systemd/linger to allow backround processes not get killed when SSH session terminates.
  • registering dockerd as user-scoped systemd daemon by dockerd-rootless-setuptool.sh and set it to run at startup.

Enable docker with putting this to deployment script:

features:
- docker

Getting Started

The deployment script below activates docker capabilities and set up a docker-compose.yml file from services script.

# Requires Kit plan or higher!
source: clear
features:
- docker
services:
hello_world:
# https://github.com/cernoel/docker-hello-world
image: cernoel/hello-world:main
restart: always
ports:
- 8080:8000

The services subpath is equal to services declared in docker compose file. In fact, you can simply copy paste any docker compose file from internet to our deployment script! The port mapping will be linked automatically to our NGINX system. After deployment, you can examine the final docker-compose.yml in the ~/public_html:

cat ~/public_html/docker-compose.yml
services:
hello_world:
image: cernoel/hello-world:main
restart: always
ports:
- target: 8000
host_ip: 127.151.60.204
protocol: tcp
published: "8080"

docker compose down and docker compose up will be automatically everytime a deployment script is called with services: prop. Note that you cannot declare volumes: and networks: using deployment script. See With Existing Docker Compose for solution.

What? why host_ip is 127.x.x.x?

DOM Cloud is a shared hosting environment. To avoid clashing with other users your web instance will be assigned one IP in loopback port 127.0.0.0/8 randomly. The IP will be persisted and proxy_pass will be configured automatically.

nginx.conf
server {
location / {
proxy_pass http://127.151.60.204:8080;
}
}

How does it know if port 8080 is the web gateway? Because we designed it that way. You can only put one ports entry in the whole compose script and it's only for your web gateway. Do not expose any other port even if it's for easy database access. Only access your internal container data via docker exec.

With Existing Docker Compose

What if you already have docker-compose.yml file, perhaps from a GitHub repo?

The example below setup Plausible self-hosting with their depedencies.

source: https://github.com/plausible/hosting
features: docker
services: docker-compose.yml # docker compose always ran after commands
commands:
- echo BASE_URL=https://$DOMAIN > plausible-conf.env
- echo SECRET_KEY_BASE=$(openssl rand -base64 48) >> plausible-conf.env
- echo TOTP_VAULT_KEY=$(openssl rand -base64 32) >> plausible-conf.env

You can configure your containers using docker commands in SSH. To reconfigure composer file cleanly just like running services: via deployment script without leaving SSH you can run:

docker compose -f ~/public_html/docker-compose.yml down --remove-orphans
docker compose -f ~/public_html/docker-compose.yml up --build --detach

Healthcheck

While your app and it services runs 24/7, sometimes your app can crash on itself. Use proxfix NOHUP mode to watch docker on every request.

nginx:
root: public_html/public
passenger:
enabled: on
app_start_command: proxfix docker compose up --no-recreate -d
env_var_list:
- NOHUP=1
- TARGET=127.X.X.X:8080

Note TARGET envar value is where docker binds IP and port to. To know what is this value, refer to proxy_pass value before NGINX set.

Managing systemd daemon

Your docker instance is registered as user-scoped systemd service. You can call these systemd commands to diagnose docker problems

  • systemctl status docker --user
  • systemctl start docker --user

Troubleshooting

502 Bad Gateway

This could means your docker container is unable to run. Please check docker ps and docker logs.

If it running normally, please check if NGINX and docker compose running the same proxy_pass. Try deploying service: docker-compose.yml again.

exec format error in docker logs

This means the container is not available in system architecture. Remember, our servers is arm64 (ARM) not amd64 (Intel), not every image containers have this platform arch. Check it with Docker Hub.

If you confirm that the image containers is amd64 only, please move the server to x64 variant, that's SGA/NYC/AMS server.