Deploy Docker Apps
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 bydockerd-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
:
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.
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.