5 · Wire .env templates

TL;DR

Objective — replace the vendor’s single .env with a three-environment template set (local / staging / production), preserving the original first, and generate a unique APP_KEY for local.

User part + done-when

👤 User part — when customizing each template, you supply the real secret values (the DB credentials you created in Prerequisites, mail/Stripe keys) from your password manager. The agent lays down the templates and runs key:generate; only a person should paste live secrets in.

Done when the vendor env is backed up, all three templates exist, local is active with a unique APP_KEY, staging/production set APP_DEBUG=false, and no real .env is staged.  ·  ⏱ ~20 min  ·  🔀 (🤖 templates, 👤 secret values).

Background

The vendor ships a .env (or .env.example). You’re about to replace it with a three-environment template set — but first preserve the original, because it often documents required keys you’d otherwise miss.

Default path: 1Password .env.tpl

If you use the recommended Option A in Project constitution §5, skip this page’s vault template files and commit root .env.tpl / .env.<env>.tpl files with op://<Project>/<Environment>/<KEY> references (bootstrap .gitignore must include !.env.tpl). Render with op inject -i .env.tpl -o .env — do not also maintain .env.local/.staging/.production in the vault.

For the first local-only build, one root .env.tpl that points at a Local item is enough. Add .env.staging.tpl / .env.production.tpl only when those environments are real. Keep alternate-environment op:// examples out of comments: op inject scans commented lines too, so a commented production reference can still break a local render.

flowchart LR
  V["vendor .env /<br/>.env.example"] -->|back up| Vault["project vault<br/>(gitignored)"]
  Vault --> T["lay down<br/>.env.local / .staging / .production"]
  T --> A["cp .env.local .env"]
  A --> K["php artisan key:generate"]

Steps

1. Back up the vendor env

Preserve the originals in the gitignored vault — your record of what the author expected.

1. Copy the vendor env into the vault.

   mkdir -p Admin-Local/1-Project/2-ProjectVault
   [ -f .env ] && cp .env Admin-Local/1-Project/2-ProjectVault/.env.vendor-original
   cp .env.example Admin-Local/1-Project/2-ProjectVault/.env.vendor-example
   # Expected: vendor .env (if present) and .env.example copied into the vault

   • ✅ The vendor’s original env files are preserved in Admin-Local/1-Project/2-ProjectVault/.

2. Lay down per-environment templates

Create one template per environment in the vault. Keep real secrets out of git — only .env.example is ever tracked.

Who does this

🔀 User + Agent — the agent creates the three template files; 👤 User fills each with the real per-environment secrets (DB creds, mail, payment keys) from the password manager.

1. Create the three templates from .env.example.

   cp .env.example Admin-Local/1-Project/2-ProjectVault/.env.local
   cp .env.example Admin-Local/1-Project/2-ProjectVault/.env.staging
   cp .env.example Admin-Local/1-Project/2-ProjectVault/.env.production
   # Expected: three .env.<environment> files created in the vault

   • ✅ .env.local, .env.staging, .env.production exist in the vault.

2. Customize each — at minimum APP_NAME, APP_ENV, APP_DEBUG, APP_URL, and the DB_* credentials created in Prerequisites.

   • ✅ Each template carries this project’s values, with secrets pasted only into the gitignored variants.

No .env.example shipped?

If the vendor shipped no .env.example, create a minimal one before the cp commands above — every template is copied from it:

[ -f .env.example ] || cat > .env.example << 'EOF'
APP_NAME=Laravel
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_TIMEZONE=UTC
APP_URL=http://localhost

LOG_CHANNEL=stack
LOG_LEVEL=debug

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=

CACHE_STORE=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync

MAIL_MAILER=log
MAIL_FROM_ADDRESS="noreply@example.com"
MAIL_FROM_NAME="${APP_NAME}"
EOF
# Expected: .env.example exists with standard Laravel variables (empty APP_KEY/secrets)

Keep APP_KEY and all secret values empty here — .env.example is the only env file ever tracked.

Only .env.example is tracked

The .gitignore from the previous page ignores .env and .env.* except .env.example. Confirm real secrets live only in the gitignored variants, and that .env.example carries keys with empty/placeholder values.

If .env was already tracked, untrack and rotate

If a real .env was ever committed, do not just add it to .gitignore and move on. Remove it from the index with git rm --cached .env, commit the removal, rotate every secret that appeared in that file, and decide whether the repository history must be purged before sharing the repo. .env.tpl may stay committed because it contains references only; .env and .env.* with values do not.

3. Activate local & generate the key

1. Activate the local env and generate its key.

   cp Admin-Local/1-Project/2-ProjectVault/.env.local .env
   php artisan key:generate
   # Expected: INFO  Application key set successfully.

   • ✅ grep "^APP_KEY=base64:" .env returns a key line.

Every environment gets its own APP_KEY

Never share an APP_KEY across environments. Generate a unique key per environment; a leaked production key compromises every encrypted value and signed cookie.

4. Per-environment values (reference)

The same keys take different values per environment. The ones that matter most:

Variable	Local	Staging	Production
APP_ENV	local	staging	production
APP_DEBUG	true	false	false
APP_URL	https://app.test	https://staging.x.com	https://x.com
APP_KEY	unique	unique	unique
LOG_LEVEL	debug	info	error
MAIL_MAILER	log	smtp	smtp
SESSION_SECURE_COOKIE	false	true	true

APP_DEBUG=false is mandatory off-local

On staging and production, APP_DEBUG=true leaks stack traces, env values, and connection strings to anyone who triggers an error. It must be false everywhere except local.

Checklist

Do not mark this step done until every box below is checked.

• 🤖 Vendor env backed up — .env / .env.example copied to the vault.
• 🔀 Templates created — .env.local / .env.staging / .env.production exist in the vault.
• 🤖 Local active + keyed — .env active and a unique APP_KEY generated (grep "^APP_KEY=base64:" .env).
• 👤 Off-local debug off — staging + production templates set APP_DEBUG=false.
• 🤖 No secrets staged — git status shows no real .env files staged.

→Next step

Commit & freeze the vendor