Reference guide · migration-hosting · Published 2026-08-16 · 3 min read
Keeping .env files portable between environments
.env file portability explained: environment-specific values, secrets handling and the deploy patterns that travel between environments.
- ·Separate by environment
- ·Keep secrets out of git
- ·Deploy templates not values
Separate the values that change per environment
A .env file stores configuration as key-value pairs that the application reads from environment variables. Most projects keep their code identical across local, staging and production, so the only differences live in configuration such as the database host, cache, credentials and build flags.
The core discipline is to keep .env values environment-specific and out of the code you deploy. A file that works in local development usually must not be copied to production unchanged, because the database host, the URL and the mail settings differ.
| Key | Local | Staging | Production |
|---|---|---|---|
APP_URL | http://localhost:8080 | https://staging.example.com | https://example.com |
DB_HOST | localhost | DB host on staging | DB host on prod |
DB_NAME | myapp_dev | myapp_stage | myapp_prod |
APP_ENV | local | staging | production |
Keep secrets out of version control
Real credentials in .env do not belong in git. Add .env to .gitignore, commit only a .env.example with placeholder values, and let each environment supply the real values through its own file, its deploy tool, or the hosting panel's environment-variable editor.
# .gitignore
.env
.env.local
.env.productionKeeping secrets out of git matters most on hard forks: if you copy a .env into the codebase to move a site, an API key can end up in the repository, in the build output, and in backups. On a CI or a scheduled release, the wrong .env also silently points the deployed code at the wrong host.
Deploy templates, not values
Apply environment-aware defaults and never hard-code environment-specific facts into the source:
- Ship a
.env.examplein the repo that documents every variable and its expected format. - Populate values at deploy time with the correct file for that environment, or from the platform's secret store.
- Validate on startup that the required variables are present, so a missing value fails fast during a deploy rather than after users arrive.
- Do not set
APP_ENV=productionlocally by copying a file; let each environment claim its own value.
On a typical stack the application loads .env first, and real platforms read printenv or a secret manager as the override. Test a migration by running the app against a staging .env that uses staging hosts, which raises any hard-coded path before you cut over.
Portability in a move
When you move to new hosting or push staging to live, treat .env as part of the migration inventory, not a file to carry verbatim. Recreate the production values from the live panel (not from a developer's laptop), check that privileges use the same DB user, and confirm the new server supports the same environment-variable interface. The hosting panel basics guide shows where each host expects you to set these values, which is often the difference between a site that opens and one that points at the wrong database.