Sidecar container pattern in Docker - Commands & Configuration

Introduction

Sometimes an application needs extra helper tasks like logging or data syncing. The sidecar container pattern solves this by running a small helper container alongside the main app in the same pod or environment, sharing resources but keeping tasks separate.

When you want to add logging or monitoring to an app without changing its code

When you need to sync files or data between the app and external storage

When you want to add a proxy or security layer alongside your main app

When you want to keep helper tasks isolated but tightly coupled with the main app

When you want to update or restart the helper without affecting the main app

Config File - docker-compose.yml

docker-compose.yml

version: '3.8'
services:
  app:
    image: nginx:1.23
    ports:
      - "8080:80"
    volumes:
      - app-data:/usr/share/nginx/html
  sidecar:
    image: busybox
    command: ["sh", "-c", "while true; do echo 'Sidecar running' >> /data/log.txt; sleep 5; done"]
    volumes:
      - app-data:/data
volumes:
  app-data:

This docker-compose file defines two services: app and sidecar.

The app service runs an Nginx web server exposing port 8080 and uses a shared volume app-data for its web files.

The sidecar service runs a lightweight BusyBox container that writes a message to a log file every 5 seconds inside the shared volume app-data. This simulates a helper task running alongside the main app.

The shared volume app-data allows both containers to access the same files, enabling cooperation without mixing their processes.

Commands

This command starts both the main app and the sidecar containers in the background, creating the shared volume and linking them as defined in the docker-compose.yml file.

Terminal

docker-compose up -d

Expected Output

Creating network "default" with the default driver

Creating volume "app-data" with default driver

Creating sidecarpattern_app_1 ... done

Creating sidecarpattern_sidecar_1 ... done

→

-d - Run containers in detached mode (in the background)

This command lists the running containers started by docker-compose, showing their status and ports.

Terminal

docker-compose ps

Expected Output

    Name                     Command               State           Ports         

--------------------------------------------------------------------------------

sidecarpattern_app_1     nginx -g 'daemon off;'    Up      0.0.0.0:8080->80/tcp

sidecarpattern_sidecar_1 sh -c while true; do ec... Up      

This command reads the log file created by the sidecar container inside the shared volume to verify the sidecar is running and writing data.

Terminal

docker exec sidecarpattern_sidecar_1 cat /data/log.txt

Expected Output

Sidecar running

Sidecar running

Sidecar running

Sidecar running

Sidecar running

This command stops and removes the containers and network created by docker-compose, cleaning up the environment.

Terminal

docker-compose down

Expected Output

Stopping sidecarpattern_sidecar_1 ... done

Stopping sidecarpattern_app_1 ... done

Removing sidecarpattern_sidecar_1 ... done

Removing sidecarpattern_app_1 ... done

Removing network default

Key Concept

If you remember nothing else from this pattern, remember: a sidecar container runs alongside your main app to add helper tasks without changing the app itself.

Common Mistakes

Not sharing a volume between the main app and sidecar containers

Without a shared volume, the containers cannot exchange files or data, so the sidecar cannot assist the main app effectively.

Define a shared volume in the docker-compose file and mount it in both containers at appropriate paths.

Running the sidecar container with a command that exits immediately

If the sidecar container stops right after starting, it won't provide continuous helper functionality.

Use a command that keeps the sidecar container running, like a loop or a long-running process.

Summary

Use docker-compose to run a main app container and a sidecar container together.

Share a volume between containers to allow data exchange and cooperation.

Keep the sidecar container running with a continuous command to provide helper tasks.