Understanding build commands and init container commands

3 min read Updated 3 days ago

Understanding build commands and init container commands

When deploying applications, you can run commands at two different stages: during the image build process and before your application starts. Understanding when to use each type ensures your application deploys correctly and efficiently.

Build commands

Build commands run during the Docker image creation process. These commands become part of your application image and their results are cached. Use build commands for tasks that prepare your application code and dependencies.

When to use build commands:

  • Installing application dependencies (composer install, npm install)

  • Building frontend assets (npm run build, npm run production)

  • Compiling code or generating optimized files

  • Any task that produces files needed by your application

Examples of build commands:

  • composer install --no-dev --optimize-autoloader

  • npm ci

  • npm run build

  • php artisan horizon:publish

  • php artisan telescope:publish

Important notes about build commands:

  • Do not run any commands that depend on external application services such as your database.

  • These commands run once when building your application image

  • The results are included in the image and reused for all deployments

  • Do not use php artisan config:cache or php artisan migrate here - these are handled automatically

  • Commands run in the order you specify them

  • If you use npm commands, make sure to select a Node.js version in your application settings

Init container commands

Init container commands run every time your application starts, before the main application container begins. Use these for tasks that need fresh data or must run with the latest environment configuration.

When to use init container commands:

  • Database migrations (php artisan migrate --force)

  • Database seeding for staging environments (php artisan db:seed)

  • Cache warming that depends on environment variables

  • One-time setup tasks that need current configuration

Examples of init container commands:

  • php artisan migrate --force

Important notes about init container commands:

  • These commands run every time your application starts or restarts

  • They have access to your environment variables and secrets

  • All commands must complete successfully before your application starts

  • Commands are combined with && so they stop on the first failure

  • They run with the same user permissions as your application (www-data)

Quick decision guide

Use build commands when:

  • Installing packages or dependencies

  • Compiling assets or code

  • The output should be included in the image

  • The task doesn't depend on runtime configuration

Use init container commands when:

  • Running database migrations

  • Tasks that need current environment variables

  • One-time setup that must happen on each deployment

  • Tasks that modify the runtime environment

Common patterns

Laravel application

Build commands:

  • composer install --no-dev --optimize-autoloader

  • npm ci

  • npm run build

Init container commands:

  • php artisan migrate --force

Performance considerations

Build commands increase image build time but don't affect application startup. Init container commands run on every deployment and can delay application availability. Keep init container commands minimal and fast for the best deployment experience.