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.

Steps at a glance:

1. Back up the vendor env — Preserve the originals in the gitignored vault — your record of what the author expected.
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.
3. Activate local & generate the key — copy the local env into place and generate APP_KEY, so the app boots locally with secrets kept out of git.
4. Per-environment values (reference) — The same keys take different values per environment. The ones that matter most:.
5. Final verification — Run after all templates exist and local is active.

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, the environment templates from Zaj-PROJECT.md exist, local is active with a unique APP_KEY, remote environments 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 one template per environment row in Zaj-PROJECT.md — 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 -f -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.<env-key>.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.

Credential items already exist

Phase 2 Prerequisites §3 seeds Local, Staging, and Production 1Password items before this page runs. When a real password arrives, update the existing field; do not create a new item here:

PROJECT_VAULT="[PROJECT]"
op item edit "Local" --vault "$PROJECT_VAULT" \
  "DB_PASSWORD[password]=<PASTE_LOCAL_PASSWORD_OR_EMPTY_LOCAL_VALUE>" >/dev/null
op item get "Local" --vault "$PROJECT_VAULT" --fields label=DB_DATABASE
# Expected: edit exits 0; verification prints only the non-secret database name

If a resumed/legacy project is missing an item, return to Prerequisites §3 and run the idempotent seed block first. Do not revive the old single Databases item with dotted fields.

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-Vault
   [ -f .env ] && cp .env Admin-Local/1-Project/2-Vault/.env.vendor-original
   cp .env.example Admin-Local/1-Project/2-Vault/.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-Vault/.

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 common templates from .env.example.

   cp .env.example Admin-Local/1-Project/2-Vault/.env.local
   cp .env.example Admin-Local/1-Project/2-Vault/.env.staging
   cp .env.example Admin-Local/1-Project/2-Vault/.env.production
   # For additional Zaj-PROJECT.md rows, copy one file per env key:
   # cp .env.example Admin-Local/1-Project/2-Vault/.env.qa
   # cp .env.example Admin-Local/1-Project/2-Vault/.env.client-demo
   # Expected: .env.<environment-key> files created in the vault

   • ✅ .env.local, .env.production, and one .env.<env-key> for each real non-production row exist in the vault.

2. Customize each template with runnable sed blocks — paste real secrets from the password manager; never commit filled vault files.

   Local (Admin-Local/1-Project/2-Vault/.env.local):

   sed -i '' \
     -e 's/^APP_NAME=.*/APP_NAME="[PROJECT]"/' \
     -e 's/^APP_ENV=.*/APP_ENV=local/' \
     -e 's/^APP_DEBUG=.*/APP_DEBUG=true/' \
     -e 's|^APP_URL=.*|APP_URL=https://[project].test|' \
     -e 's/^DB_DATABASE=.*/DB_DATABASE=[project]_local_db/' \
     -e 's/^DB_USERNAME=.*/DB_USERNAME=[project]_local_user/' \
     -e 's/^DB_PASSWORD=.*/DB_PASSWORD=<FROM_SEEDED_LOCAL_ITEM_OR_VAULT>/' \
     Admin-Local/1-Project/2-Vault/.env.local
   # Expected: grep APP_ENV=local and APP_DEBUG=true in .env.local

   Non-production target (example env key: staging; use the real key and URL from Zaj-PROJECT.md):

   ENV_KEY="staging"
   NON_PROD_URL="https://nonprod.example.com"
   sed -i '' \
     -e "s/^APP_NAME=.*/APP_NAME=\"[PROJECT] ${ENV_KEY}\"/" \
     -e "s/^APP_ENV=.*/APP_ENV=${ENV_KEY}/" \
     -e 's/^APP_DEBUG=.*/APP_DEBUG=false/' \
     -e "s|^APP_URL=.*|APP_URL=${NON_PROD_URL}|" \
     -e "s/^DB_DATABASE=.*/DB_DATABASE=[project]_${ENV_KEY}_db/" \
     -e "s/^DB_USERNAME=.*/DB_USERNAME=[project]_${ENV_KEY}_user/" \
     -e 's/^DB_PASSWORD=.*/DB_PASSWORD=<FROM_SEEDED_ENV_ITEM_OR_VAULT>/' \
     -e 's/^SESSION_SECURE_COOKIE=.*/SESSION_SECURE_COOKIE=true/' \
     "Admin-Local/1-Project/2-Vault/.env.${ENV_KEY}"
   # Expected: APP_DEBUG=false and SESSION_SECURE_COOKIE=true

   Production:

   sed -i '' \
     -e 's/^APP_NAME=.*/APP_NAME="[PROJECT]"/' \
     -e 's/^APP_ENV=.*/APP_ENV=production/' \
     -e 's/^APP_DEBUG=.*/APP_DEBUG=false/' \
     -e 's|^APP_URL=.*|APP_URL=https://[DOMAIN]|' \
     -e 's/^DB_DATABASE=.*/DB_DATABASE=[project]_production_db/' \
     -e 's/^DB_USERNAME=.*/DB_USERNAME=[project]_production_user/' \
     -e 's/^DB_PASSWORD=.*/DB_PASSWORD=<FROM_SEEDED_PRODUCTION_ITEM_OR_VAULT>/' \
     -e 's/^LOG_LEVEL=.*/LOG_LEVEL=error/' \
     -e 's/^SESSION_SECURE_COOKIE=.*/SESSION_SECURE_COOKIE=true/' \
     Admin-Local/1-Project/2-Vault/.env.production
   # Expected: APP_DEBUG=false, LOG_LEVEL=error, SESSION_SECURE_COOKIE=true

   On Linux, use sed -i without the empty string after -i.

   • ✅ 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-Vault/.env.local .env
   php artisan key:generate
   # Expected: INFO  Application key set successfully.

   • ✅ grep -qE '^APP_KEY="?base64:' .env returns 0 — the key line matches whether or not the value is double-quoted (quoting secrets is safe and recommended).

Ownership — local .env wiring happens here

This page activates the local .env and wires its DB_* values from the Phase 2 database credentials. Phase 3 · Local database does not rewrite the env from scratch; it confirms .env resolves to the provisioned local DB and that the installer can connect.

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	Non-production target(s)	Production
APP_ENV	local	env key from Zaj-PROJECT.md	production
APP_DEBUG	true	false	false
APP_URL	https://app.test	URL from Zaj-PROJECT.md	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.

5. Final verification

Run after all templates exist and local is active.

echo "=== Env template verification ==="
ls -1 Admin-Local/1-Project/2-Vault/.env.* 2>/dev/null
# Quote-tolerant value greps below: an optional double-quote may sit right after
# the `=` because quoting secret values is safe and recommended (and mandatory in
# some project rules). Each check matches the value whether or not it is quoted.
grep -qE '^APP_KEY=("")?$' .env.example && echo "✅ .env.example has empty APP_KEY" || echo "❌ scrub secrets from .env.example"
git check-ignore -q .env && echo "✅ live .env ignored" || echo "❌ add .env to .gitignore"
grep -qE '^APP_DEBUG="?false"?' Admin-Local/1-Project/2-Vault/.env.production && echo "✅ production debug off" || echo "❌ fix production APP_DEBUG"
for env_file in Admin-Local/1-Project/2-Vault/.env.*; do
  case "$env_file" in
    *.local|*.vendor-*|*.vendor-original|*.vendor-example) continue ;;
  esac
  grep -qE '^APP_DEBUG="?false"?' "$env_file" && echo "✅ $env_file debug off" || echo "❌ fix $env_file APP_DEBUG"
  grep -qE '^SESSION_SECURE_COOKIE="?true"?' "$env_file" && echo "✅ $env_file secure cookies" || echo "⚠ set SESSION_SECURE_COOKIE in $env_file"
done
grep -qE '^APP_KEY="?base64:' .env && echo "✅ local APP_KEY set" || echo "❌ run php artisan key:generate"
# Expected: all ✅ lines; no real .env in git status

• ✅ Vault holds the local, production, and non-production environment templates; .env.example has empty secrets; live .env is gitignored; remote templates differ from local on debug and secure cookies.

Checklist

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

• 🤖 Vendor env backed up — .env / .env.example copied to the vault.
• 🤖 Credential items exist — Local, Staging, and Production 1Password items were seeded in Prerequisites and use the flat field set.
• 🔀 Templates created — .env.local, .env.production, and one .env.<env-key> for each real non-production row exist in the vault.
• 🤖 Local active + keyed — .env active and a unique APP_KEY generated (grep -qE '^APP_KEY="?base64:' .env — passes whether or not the value is quoted).
• 👤 Off-local debug off — every non-local template sets APP_DEBUG=false.
• 🤖 No secrets staged — git status shows no real .env files staged.

→Next step

Commit & freeze the vendor