What is Docker (One-Sentence Version)#

Docker lets you run services directly using pre-packaged “images,” so you don’t have to install dependencies one by one on your system.

You don’t need to manually install Python, Go, Node, configure environment variables, or deal with version conflicts. Everything’s already in the image.

docker-compose.yml is just a configuration file that tells Docker:

• Which image to pull
• Which ports to use
• Which directories to mount
• Which environment variables to set
• Whether to automatically restart if it crashes

Installation#

Install Docker on Ubuntu / Debian:

1
curl -fsSL https://get.docker.com | sh

This one-liner script installs Docker Engine and Docker Compose (Compose is now a Docker subcommand, no need to install docker-compose separately).

Check after installation:

1
docker --version
2
docker compose version

If you don’t want to run Docker with sudo:

1
sudo usermod -aG docker $USER

Then log out and log back in. If it still doesn’t work, restart the server.

Your First Compose File#

Let’s look at the simplest example:

1
services:
2
  whoami:
3
    image: traefik/whoami
4
    container_name: whoami
5
    restart: unless-stopped
6
    ports:
7
      - "127.0.0.1:8080:80"

Line by line translation:

Save this snippet as docker-compose.yml (or compose.yml, either name works), then run it in the same directory:

1
docker compose up -d

-d means run in the background.

Check:

1
curl http://127.0.0.1:8080/

If you see a response, it means it’s running.

Common Commands#

I’ve listed the most common ones here:

1
# Start (in background)
2
docker compose up -d
3

4
# View logs
5
docker compose logs -f
6

7
# View logs (last 100 lines only)
8
docker compose logs --tail=100
9

10
# Stop
11
docker compose down
12

13
# Restart
14
docker compose restart
15

16
# View status
17
docker compose ps
18

19
# Enter container (for troubleshooting)
20
docker compose exec whoami sh

All commands must be executed in the directory where docker-compose.yml is located.

Understanding Real Compose Files#

Let’s take Vaultwarden as an example:

1
services:
2
  vaultwarden:
3
    image: vaultwarden/server:latest
4
    container_name: vaultwarden
5
    restart: unless-stopped
6
    environment:
7
      DOMAIN: "https://vault.example.com"
8
      SIGNUPS_ALLOWED: "false"
9
    volumes:
10
      - ./vw-data:/data
11
    ports:
12
      - "127.0.0.1:8080:80"

New things that appeared:

1
./vw-data:/data
2
  ↑              ↑
3
  Host directory Container path

1
"127.0.0.1:8080:80"
2
  ↑           ↑    ↑
3
  Listen address Host port  Container port

Using .env Files for Sensitive Information#

Don’t write passwords, tokens, or domains directly into docker-compose.yml and then push it to GitHub.

Create a .env file in the same directory:

1
VAULTWARDEN_DOMAIN=https://vault.example.com
2
ADMIN_TOKEN=一个很长很复杂的随机字符串

Then reference it in your Compose file:

1
environment:
2
  DOMAIN: "${VAULTWARDEN_DOMAIN}"
3
  ADMIN_TOKEN: "${ADMIN_TOKEN}"

Add the .env file to .gitignore so it doesn’t get committed to the repository.

Updating Services#

To update a service:

1
cd /srv/stacks/vaultwarden
2

3
# First, back up your data
4
tar -czf backup-$(date +%F).tar.gz vw-data
5

6
# Pull the new image
7
docker compose pull
8

9
# Restart with the new image
10
docker compose up -d
11

12
# Check logs to confirm it's working
13
docker compose logs --tail=50

Always back up before updating. If something goes wrong, you can still roll back.

Deleting Services#

If you no longer want a service:

1
# Stop and delete containers
2
docker compose down
3

4
# If you're sure you don't need the data, delete the directory
5
rm -rf /srv/stacks/那个服务

docker compose down only deletes containers, not volume data.

If you want to completely clean up, including volumes:

1
docker compose down -v

But this will delete data. Only use it when you’re sure you don’t need it.

Cleaning Up Disk Space#

Over time, Docker accumulates many old images. A 2C2G disk isn’t huge, so clean it up occasionally:

1
# See how much space Docker is using
2
docker system df
3

4
# Clean up unused images, containers, networks
5
docker system prune
6

7
# Also clean up unused volumes (be careful, this deletes data from orphaned volumes)
8
docker system prune --volumes

prune only cleans up unused items; running services are unaffected. But think carefully before using --volumes.

My Directory Structure#

I usually organize things like this:

1
/srv/stacks/
2
├── vaultwarden/
3
│   ├── docker-compose.yml
4
│   ├── .env
5
│   └── vw-data/
6
├── ntfy/
7
│   ├── docker-compose.yml
8
│   ├── .env
9
│   ├── cache/
10
│   ├── data/
11
│   └── etc/
12
├── gatus/
13
│   ├── docker-compose.yml
14
│   └── config/
15
└── fast-note-sync/
16
    ├── docker-compose.yml
17
    ├── .env
18
    └── storage/

Each service gets its own directory. Just cd into it and run docker compose up -d. Data and configurations are all within their own directories, making backups easy.

Common Issues#

Port Conflicts

Two services cannot use the same host port. If Vaultwarden uses 8080, ntfy will need to use a different one, like 8090.

Permission Issues

Some images run with non-root users inside the container, and incorrect permissions on mounted directories can prevent writing. In such cases, check the owner and permissions of the host directory.

Forgetting -d

If you run docker compose up without -d, the service will stop when you close the terminal. Remember to add -d.

compose v1 vs v2

Older tutorials might show docker-compose up (with a hyphen) which is v1. Nowadays, docker compose up (with a space) is v2. Newly installed systems will use v2, so if you see an old tutorial with a hyphen, just replace it with a space.

That’s Enough (for now)#

By now, you should be able to:

• Install Docker
• Understand Compose files
• Start, stop, update, and delete services
• Manage data and configurations
• Clean up disk space

For every self-hosted service article going forward, I’ll just give you a docker-compose.yml, and you’ll be able to get it running.

No need to understand all Docker concepts from the start. Just get it working, and as you use it more, you’ll naturally want to learn more.