CroZone
Release wireHermes Agent v0.23.3  ·  Stable channel patchImmich v3.4.2  ·  Library monitoring fixes
Guides

Run your first service with Docker Compose

Serve a page from a folder on your computer. Replace the container and prove the page survives.

CroZone · Published Nov 20, 2026
In this article

Prepare an empty project

Use a Linux shell, macOS terminal or WSL with Docker Engine and the Compose plugin running. Create a new directory for this exercise. The page on disk is the durable part. Nginx inside the container is replaceable.

mkdir -p compose-lab/site
cd compose-lab
printf '%s\n' 'CroZone lab' > site/index.html
docker compose version

Describe one service

Save the following as compose.yaml beside the site folder. The port binds to loopback, so the test is available on this host. The read-only mount lets Nginx serve the page without writing to your files.

services:
  web:
    image: nginx:alpine
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro

Start it and verify persistence

Validate the configuration, start the service and request the page. Replace the container and request it again. Both requests should return CroZone lab. If port 8080 is occupied, choose an unused host port and use it in curl too.

docker compose config --quiet
docker compose up -d
curl -fsS http://127.0.0.1:8080/
docker compose up -d --force-recreate
curl -fsS http://127.0.0.1:8080/

Stop and maintain it

Run docker compose down in the exercise directory. Your HTML remains in site/. For a service you keep, record the deployed image digest and test updates with a copy of your data. The alpine tag in this example can move.

Read the Compose file from the outside in

Think of each line as a boundary. The image supplies Nginx and its dependencies. The port declaration connects port 8080 on your machine to port 80 inside the container. The volume connects a directory you own to a directory Nginx reads. If you can name which boundary failed, the logs are much easier to interpret. A successful request with the wrong page usually points to content or mounting. A connection refusal usually points to a stopped container, a wrong port or a process that has yet to listen.

Make a prediction before the second run. Change site/index.html to a different sentence and refresh the URL without rebuilding. The new sentence is visible because this example uses a bind mount. If you renamed the Compose service, use its new name in diagnostic commands. Practice that distinction now, while there is one service and no database to recover.

A repeatable diagnostic sequence

Run docker compose ps -a from the same directory as compose.yaml. A missing row usually means the project never created a container. An exited row sends you to docker compose logs --tail=50 web. A running row tells you the process exists. Then use curl -i against the exact host address and port to see the HTTP response. Review docker compose config if the effective port or mount differs from your file. Resolve the port conflict or path issue first, then rerun the request that failed.

When you add an application and database, test readiness independently. A database container can be running while it is still initializing. Compose can wait for a dependency's health check when you configure service_healthy. Treat that as startup ordering. Keep retry behavior in the application for a database restart later in the day. Before changing an image used with persistent data, write down its current version and take a backup the application can restore.

Primary sources

Docker · Compose quickstart · Docker · Compose startup order

Read next   Local or cloud? Follow the work.

Search CroZone