Guide

Production & Deployment

Prepare environment values, let Lemonade use its production config cache, and deploy only the artifacts the runtime actually needs.

Production mode starts with the environment

Production behavior is primarily driven by APP_ENV, APP_DEBUG, and application values such as APP_BASE_URL. development and testing load configuration directly from source. production, prod, and other non-development environments behave as production-like runtimes and can use the compiled config cache.

example.php
APP_ENV=production
APP_DEBUG=0
APP_BASE_URL=https://example.com

How the compiled config cache works

YAML files and resolved environment values remain the source of truth. In production-like mode, ConfigLoader first tries ApplicationConfigCache::loadIfFresh(). If the cache is missing, stale, or a tracked source changed, the framework reloads configuration and writes a fresh cache automatically. Separate config:cache and config:clear commands are not currently needed.

example.php
production HTTP request or CLI command
-> ConfigLoader::loadApplication(...)
-> ApplicationConfigCache::loadIfFresh(...)
-> on cache miss: load source config and write a fresh compiled cache

Writable runtime directories

A deployed application needs write access under storage/ for the compiled config cache, logs, sessions, and uploads when those features are enabled. Keep generated files under storage/, do not commit them, and do not treat them as source of truth.

example.php
storage/cache/framework/config/
storage/logs/
storage/sessions/
storage/uploads/

A practical Lemonade deployment checklist

  • Before deployment: prepare environment values and secrets, deploy the YAML configuration, and build an optimized Composer autoloader.
  • During deployment: publish the code and verify writable directories under storage/.
  • After deployment: let the first production HTTP request or CLI command create the config cache, verify logging, and run vendor/bin/lemonade workers or scheduled commands only when the application actually uses them.
  • See Infrastructure for runtime storage details and Errors & Debugging for diagnostics.
example.php
composer install --no-dev --optimize-autoloader
vendor/bin/lemonade about

# Optional when the app uses queue workers
vendor/bin/lemonade queue:install
vendor/bin/lemonade queue:work default database