Understanding build commands and init commands

3 min read Updated 1 day ago

Understanding build commands and init commands

When deploying applications, you can run commands at two different stages: during the image build process and when 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:

  • Build commands run during image creation with no access to environment variables or external services
  • These commands run once when building your application image
  • The results are included in the image and reused for all deployments
  • 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

Do NOT use these commands:

  • php artisan migrate - Requires database access (use init commands instead)
  • php artisan config:cache - Will cache empty environment variables during build, causing runtime failures
  • Any commands that depend on environment variables or external services

Why? Build commands execute before environment variables are available. Running php artisan config:cache during the build will cache empty or incorrect values.

Init commands

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

When to use init 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 commands:

  • php artisan migrate --force
  • php artisan config:cache
  • php artisan route:cache

Important notes about init commands:

  • These commands run every time your application starts or restarts
  • They have full access to your environment variables, secrets, and external services (database, cache, etc.)
  • All commands must complete successfully before your application starts
  • Commands execute sequentially and stop on the first failure
  • They run with the same user permissions as your application

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 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 commands:

  • php artisan migrate --force
  • php artisan config:cache

Performance considerations

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