Environment Files

Conveyor manages one shared .env file per project, centrally, instead of you hand-editing it on every server. It’s stored encrypted in Conveyor’s own database and pushed out to every configured server whenever you save it.

Setting it up

On a project’s Environment tab, the first time you configure it you’re asked for:

• An environment password, required before the .env content can be set.
• The .env content itself.

Saving encrypts the content and pushes it to every server configured for the project.

Viewing and editing later

Once a password is set, viewing or editing the .env requires unlocking it again with that password. A successful unlock grants edit access for 15 minutes (scoped to your session and that specific project) before you’re asked to unlock again.

What’s encrypted, and with what

The .env content itself is encrypted at rest with AES-256-GCM using Conveyor’s instance-wide CONVEYOR_ENCRYPTION_KEY, the same key that encrypts SSH private keys and GitHub tokens.

The per-project password is a separate, bcrypt-hashed access gate: it controls who can view or edit the .env through the UI, but it is not the encryption key for the content, and losing it does not make the content unrecoverable the way losing CONVEYOR_ENCRYPTION_KEY does. There is no built-in “forgot password” flow in the UI. If a project’s environment password is lost, regaining access requires direct database access to clear the project’s stored password hash, after which you can set a new one from the Environment tab.

Caution

Anyone who knows a project’s environment password can view its decrypted .env content through the UI, including any secrets in it (API keys, database credentials). Treat it the same way you’d treat those secrets.

How it reaches your servers

When you save the .env, Conveyor pushes the plaintext content directly to each server over SCP, writes it to <deploy_path>/.env, and sets its permissions to 600. This happens outside the normal deploy pipeline: saving the environment pushes it immediately, without triggering a deployment.

The file lives at the project’s deploy path root, not inside any release. Each release symlinks it in:

/home/website/project.com/
├── .env                                 # the file Conveyor pushes to
├── current -> releases/20251018132019
└── releases/
    └── 20251018132019/
        └── .env -> /home/website/project.com/.env

The clone step creates this symlink immediately after extracting a new release, before any custom steps run, so migrations and other artisan commands that need the app’s configuration or database credentials can run pre-activation. The activate step re-links it too, as an idempotent safety net.

See Backups for why CONVEYOR_ENCRYPTION_KEY must be backed up separately from the database.