Dokploy / Dokploy/dokploy

[Dockerfile build] Allow customizing the generated env file name (e.g. .env.local)

Open
#4,507 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
TypeScript
Stars
37.4k
Forks
3k
Avg merge
1d 3h
Merged PRs (30d)
73

Description

What problem will this feature address?

When using the Dockerfile build type and Create Environment File is enabled in the Environment tab, Dokploy writes UI-configured variables to a .env file in the build context root. The target file name is hardcoded to .env, so the generated file unconditionally replaces any .env file committed in the repository.

This makes it impossible to follow the common pattern of keeping framework-default values in a committed .env and only overriding a subset per environment via the Dokploy UI. Every variable used at build time has to be re-declared in the UI for every environment, even those that never change.

For example, Next.js naturally supports a precedence chain (.env.production.local > .env.local > .env.production > .env) that we cannot leverage today because Dokploy always writes to .env.

Describe the solution you'd like

Add an optional Env file name field on the application's environment settings (default: .env). When set, Dokploy writes the generated variables to that path instead of the hardcoded .env.

This is fully backward-compatible (the default reproduces the current behavior) and unlocks the precedence pattern naturally:

  • Committed .env keeps repository defaults.
  • Dokploy writes to .env.local (or .env.production.local) and Next.js picks up those values at higher precedence than the committed .env.

Implementation outline:

  • Add an envFileName column to the application schema, defaulting to .env.
  • Pass it through createEnvFileCommand in packages/server/src/utils/builders/utils.ts.
  • Add a text input in the application environment settings form, shown when Create Environment File is enabled.
Describe alternatives you've considered
  • Re-declare every variable in Dokploy UI: defeats the purpose of committed defaults; tedious to keep in sync across environments.
  • Build Args / Build Secrets with ARG/ENV in the Dockerfile: verbose, brittle, and duplicates the source of truth.

None of these match the simplicity of letting the user pick the file name that matches their framework's existing semantics.

Additional context

No response

Will you send a PR to implement it?

Yes

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with packages/server/src/utils/builders/utils.ts and trace createEnvFileCommand, then locate the application schema and environment settings form described in the issue. Add the optional envFileName setting with a .env default, pass it through the Dockerfile build path, and verify the form only exposes it when Create Environment File is enabled.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, dockerfile, typescript
Domain
build-system, devops
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.