Environment variables and secrets

Environment variables keep application configuration outside your source code. They let you run the same code with different settings in development, staging and production. In Deplomo PaaS , you can define values at project, environment, add-on or service level.

What is an env file?

During local development, a .env file is a common way to store key-value settings. A library such as dotenv can load those values into the local process environment. Keep files with real credentials out of Git: add .env to .gitignore, and share an .env.example containing only placeholder values.

In Deplomo, add variables in the dashboard or CLI. The platform provides them to the service process; you do not need to create a .env file on the server.

Choose where to define a variable

Use project secrets for values shared by services in a project, environment variables for values that differ between environments, add-on bindings for generated connection values, and service variables for values specific to one service.

When runtime keys have the same name, the effective order from lowest to highest priority is:

Project secret > Environment variable > Add-on binding > Service env > Service variable

The service’s typed variables can therefore override a value in its plain env map. Platform-managed values may also take precedence for reserved keys. Build input follows a separate rule: only environment and typed service variables marked for build time are available to the builder. Project secrets, add-on credentials and plain service env values are runtime-only.

Build-time and runtime variables

Type	Available when	Typical use	Keep in mind
Build-time	While building the image or compiling frontend assets	Private package access during build; public frontend settings such as `NEXT_PUBLIC_*`	Values compiled into browser assets are visible to users. Do not pass secrets that way.
Runtime	When the deployed service process runs	Database connection strings and server-side credentials	Keep server-side secrets at runtime so they are not embedded in the built image or frontend assets.

Changing a runtime setting causes the service to recreate so it can receive the new value. Changing a build-time value also runs a new build so the value can be included in the artifact.

Do not put secrets in Git, Dockerfiles, public build variables, screenshots or logs. If a secret is exposed, replace it at its original source and update the service. Marking a value as secret masks it in the dashboard; CLI output can include values, so do not share or log it.

Reference variables

References let a value use another variable without copying it. They are resolved during deployment:


# Read a variable from another service named db in this project
DATABASE_URL=${{ db.DATABASE_URL }}
 
# Read a project secret
APP_KEY=${{ shared.APP_KEY }}
 
# Read the public domain generated for a service named api
PUBLIC_URL=https://${{ api.DEPLOMO_PUBLIC_DOMAIN }}

${{ shared.KEY }} reads a project secret, ${{ ServiceName.KEY }} reads a variable from another service in the same project, and ${{ KEY }} reads from the current service’s environment. An unresolved reference becomes an empty value. Check the service name and key spelling, and make sure the referenced value exists in the same project.

Add or change a variable in the dashboard

Open the service variables

In the dashboard, open the service and go to its Variables section. For shared values, open the project’s environment settings instead.

Enter the key and value

Add the variable name and value. Choose whether the value is available at runtime or during the build. Use the secret option for credentials or other values that should be masked in the dashboard.

Save and review the service operation

Save the variable. The service is recreated to apply runtime changes; build-time changes also need a new build. Check the operation and runtime or build logs if the service does not start as expected.

Manage variables with the CLI

The CLI has a plain runtime env map and a typed vars store. The typed store supports the --secret and --build-time options.


# List the service's plain env values
deplomo service env my-app
 
# Set or remove a plain runtime value
deplomo service env my-app set PORT=3000
deplomo service env my-app rm PORT
 
# List typed variables, including their build/secret markers
deplomo service vars my-app
 
# Set a masked runtime secret or a build-time frontend value
deplomo service vars --secret my-app set API_SECRET="replace-with-a-secret"
deplomo service vars --build-time my-app set NEXT_PUBLIC_API_URL="https://api.example.com"

The plain service env list can print its values. Typed secrets are masked, but other typed values may be shown. Avoid sharing terminal output or saving it in logs.

Protect secret values

Mark credentials and tokens as secrets in the typed variable store.
Rotate credentials at the service that issued them, then update the variable and confirm the service has applied the new value.
Avoid printing the complete process environment, for example with console.log(process.env) in Node.js.
Keep real .env files out of the repository and its history. If a credential was committed, treat it as exposed and rotate it.