Install Docker Engine and Docker Compose
Install Docker Engine and Docker Compose from the official repository on Debian or Ubuntu: users, logs, ports, updates, backups and best practices.
On this page
This guide explains how to install Docker Engine and the Docker Compose plugin from Docker's official repository, then how to prepare your server for production use: user permissions, log rotation, port exposure, updates and backups.
Order a Server
To host your containers, HostMyServers offers several options:
Prerequisites
- A 64-bit server running Debian 12/13 or Ubuntu 22.04/24.04
- SSH access with
rootor asudouser
Ports: Docker does not need any incoming port. Only open the ports of the applications you publish, and never expose the Docker API (2375 or 2376) to the Internet: accessing it is equivalent to controlling the server.
Step 1: remove conflicting packages
Docker packages provided by the distribution can conflict with the official packages:
sudo apt update
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc 2>/dev/null | cut -f1)Any images and volumes in /var/lib/docker are not deleted by this command.
Step 2: add the official repository
These commands work for both Debian and Ubuntu, because they read the system from /etc/os-release:
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
. /etc/os-release
sudo curl -fsSL "https://download.docker.com/linux/$ID/gpg" -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/$ID
Suites: ${UBUNTU_CODENAME:-$VERSION_CODENAME}
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt updateStep 3: install Docker
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker containerdStep 4: verify the installation
sudo systemctl status docker
docker --version
docker compose version
sudo docker run --rm hello-worldThe message Hello from Docker! confirms that the engine can download an image and start a container.
Step 5: allow a user
To run Docker without sudo, add your user to the docker group, then log out and log back in:
sudo usermod -aG docker $USERThen check:
docker run --rm hello-worldStep 6: configure logs and the daemon
By default, the json-file driver does not limit the size of logs, which can end up filling the disk. Create /etc/docker/daemon.json:
sudo nano /etc/docker/daemon.json{
"log-driver": "local",
"log-opts": {
"max-size": "10m",
"max-file": "3"
},
"live-restore": true
}| Option | Effect |
|---|---|
log-driver: local |
Compact log format, with rotation |
max-size, max-file |
Up to 3 files of 10 MB per container |
live-restore |
Containers keep running if the daemon stops |
Validate the file, then restart Docker. This restart interrupts running containers: preferably do it before deploying your applications.
sudo dockerd --validate --config-file=/etc/docker/daemon.json
sudo systemctl restart docker
docker info --format '{{.LoggingDriver}} {{.LiveRestoreEnabled}}'The log driver only applies to new containers. Recreate existing containers to benefit from it, for example with docker compose up -d --force-recreate.
Step 7: control published ports
If a reverse proxy runs on the server, publish your applications on the local address only:
ports:
- "127.0.0.1:8080:80"You can also make the local address the default behavior by adding these keys to /etc/docker/daemon.json:
{
"ip": "127.0.0.1",
"default-network-opts": {
"bridge": {
"com.docker.network.bridge.host_binding_ipv4": "127.0.0.1"
}
}
}Merge them with the file from step 6, validate it, then restart Docker. A port meant to be public will then have to be specified explicitly, for example "0.0.0.0:443:443".
Step 8: start a first Compose project
Create a folder for the project:
sudo mkdir -p /opt/myapp
sudo chown "$USER": /opt/myapp
cd /opt/myapp
nano compose.yamlservices:
web:
image: nginx:1.30-alpine
restart: unless-stopped
ports:
- "127.0.0.1:8080:80"
volumes:
- web-data:/usr/share/nginx/html
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1/"]
interval: 30s
timeout: 5s
retries: 3
volumes:
web-data:Start, then check:
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=20 web
curl -I http://127.0.0.1:8080To publish this application over HTTPS, place a reverse proxy in front of it. You can start from the guide Install Nginx and PHP-FPM and the Let's Encrypt guide.
Useful commands
| Command | Description |
|---|---|
docker ps -a |
List containers |
docker compose logs -f |
Follow the project logs |
docker compose restart |
Restart the services |
docker compose down |
Stop and remove containers, keeping volumes |
docker system df |
Show disk space used |
Updates
Docker Engine
sudo apt update
sudo apt install --only-upgrade docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
docker --versionlive-restore only covers patch updates. For a major version, plan for an interruption of your containers and read Docker's release notes.
Application images
Change the tag in compose.yaml if you pin it, then:
cd /opt/myapp
docker compose pull
docker compose up -d
docker image pruneBackup
At a minimum, back up your Compose files, your .env files and your volumes. Volumes are located in /var/lib/docker/volumes, but it is better to archive them through a temporary container. The actual volume name is obtained with docker volume ls:
cd /opt/myapp
mkdir -p backups
docker compose stop web
docker run --rm -v myapp_web-data:/data:ro -v "$PWD/backups":/backup alpine:3 tar czf /backup/web-data.tar.gz -C /data .
docker compose start webTo restore the archive into a volume:
docker compose stop web
docker run --rm -v myapp_web-data:/data -v "$PWD/backups":/backup:ro alpine:3 tar xzf /backup/web-data.tar.gz -C /data
docker compose start webFor a database, prefer an export with the engine's own tool (mariadb-dump, pg_dump, etc.). Then copy your backups off the server.
Production best practices
- Pin a specific image version rather than
latest - Set
restart: unless-stoppedand ahealthcheckfor your services - Publish as few ports as possible, and locally behind a reverse proxy when possible
- Keep your secrets in a protected
.envfile (chmod 600 .env), out of Git - Do not use
privileged: trueand do not mount/var/run/docker.sockunless necessary - Monitor disk space with
docker system df - Regularly test restoring your backups
Troubleshooting
permission denied on /var/run/docker.sock
Your user is not yet recognized in the docker group. Check with id, then reconnect over SSH.
Conflicting values set for option Signed-By
An old Docker repository configuration remains, often /etc/apt/sources.list.d/docker.list. After checking its contents, delete it:
sudo rm /etc/apt/sources.list.d/docker.list
sudo apt updateCannot connect to the Docker daemon
sudo systemctl status docker
sudo journalctl -u docker -n 50 --no-pager
sudo dockerd --validate --config-file=/etc/docker/daemon.jsonA syntax error in daemon.json prevents the service from starting.
port is already allocated or address already in use
Another container or service is using this port. Identify it with sudo ss -ltnp | grep ':8080 ' and docker ps, then change the server-side port.
no space left on device
df -h
docker system df
docker image prune
docker builder pruneOnly use docker volume prune after checking that the volumes concerned no longer contain useful data.
toomanyrequests during a download
The Docker Hub download limit has been reached. Wait, or log in to your account with docker login.
docker-compose: command not found
The current plugin is used with a space: docker compose.
A port remains accessible despite UFW
This is the normal behavior of ports published by Docker. Publish the port on 127.0.0.1 or apply the restrictions from the guide Configure UFW.