Init container pattern in Docker - Commands & Configuration

Introduction

Sometimes your main application needs some setup before it starts. The init container pattern lets you run a small helper container first to prepare things, like loading data or waiting for a service, before your main app runs.

When your app needs to wait for a database to be ready before starting.

When you want to load configuration files or secrets before the main app runs.

When you need to run a script to prepare data or environment before the main container.

When you want to ensure network services are reachable before launching your app.

When you want to separate setup logic from the main application for clarity and reuse.

Config File - docker-compose.yml

docker-compose.yml

version: '3.8'
services:
  init-helper:
    image: busybox
    command: ['sh', '-c', 'echo Preparing environment; sleep 5; echo Done']
  my-app:
    image: nginx:1.23
    depends_on:
      - init-helper
    command: ['nginx', '-g', 'daemon off;']

This docker-compose.yml file defines two services. The init-helper runs first and does a simple setup task (here simulated by sleep and echo). The my-app service depends on init-helper, so it waits until the init-helper container starts before starting. This ensures the environment is ready before the main app runs.

Commands

Start the init-helper container in detached mode to run the setup tasks before the main app.

Terminal

docker-compose up -d init-helper

Expected Output

Creating network "default" with the default driver

Creating volume "default" with default driver

Creating init-helper ... done

→

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

Start the main application container. It waits for init-helper to start because of the depends_on setting.

Terminal

docker-compose up -d my-app

Expected Output

Creating my-app ... done

→

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

Check the status of both containers to confirm init-helper finished and my-app is running.

Terminal

docker-compose ps

Expected Output

    Name                   Command               State           Ports

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

default_init-helper_1   sh -c echo Preparing env ...   Exit 0



default_my-app_1        nginx -g daemon off;          Up      80/tcp

View the logs of the init-helper container to see the setup steps it performed.

Terminal

docker-compose logs init-helper

Expected Output

init-helper_1  | Preparing environment

init-helper_1  | Done

Key Concept

If you remember nothing else from this pattern, remember: run a small setup container first to prepare the environment before your main app starts.

Common Mistakes

Not using depends_on to link the init container and main container

The main container may start before the init container finishes, causing failures if setup is incomplete.

Use depends_on in docker-compose to ensure the main container waits for the init container to start.

Running init container and main container together without waiting

Setup tasks may not complete before the main app starts, leading to errors or missing data.

Start the init container first, wait for it to finish, then start the main container.

Summary

Define an init container service that runs setup commands before the main app.

Use depends_on in docker-compose to make the main app wait for the init container.

Start the init container first, then the main app, and verify their status with docker-compose commands.