Environment Variables and Secrets on Dockup

Environment variables and secrets connect application code to production configuration, but they have different disclosure and lifecycle requirements. A public API base URL may be safe to show in logs; a database password or signing key is not. Dockup represents that distinction explicitly and masks stored secret values in read output.

Configuration changes also require a redeploy. Setting a new value updates the desired service configuration, but the already running process keeps the environment it received at startup.

What is the difference between a variable and a secret?

Both values enter the application process as environment data, but their operational treatment differs.

Type	Example	May appear in read output?	Recommended handling
Plain variable	NODE_ENV=production	Yes	Reviewable configuration
Plain variable	PUBLIC_API_URL=https://...	Yes	May live in dockup.yaml
Secret	DATABASE_URL=postgres://...	No stored value	Secret command or CI store
Secret	JWT_SIGNING_KEY=...	No stored value	Rotate and restrict
Secret	DOCKUP_TOKEN=...	Never store as app config unless required	Process-level auth

Mark a value secret when disclosure would allow access, impersonation, decryption, signing, or lateral movement. “The frontend already contains it” is a sign that the value is public configuration, not a secret.

Do not put secrets in source control, dockup.yaml, example output, screenshots, agent prompts, or issue descriptions. A redacted placeholder is safer than a realistic-looking token because copied examples tend to become production practice.

How do you set and inspect environment configuration?

List current keys for an exact target:

dockup env list -s production/api --json

The response includes each key, whether it is secret, and the value only when it is not protected.

Set an ordinary variable:

dockup env set NODE_ENV=production \
  -s production/api \
  --json

Set a secret from the current shell environment:

dockup env set DATABASE_URL="$DATABASE_URL" \
  --secret \
  -s production/api \
  --json

Remove an obsolete value:

dockup env remove OLD_FEATURE_FLAG \
  -s production/api \
  --json

Bulk import a .env-style file:

dockup env import .env.production \
  -s production/api \
  --json

Use --secret on import only when every imported value should be treated as secret. Mixed files are harder to review and often encourage over-classifying harmless config or under-classifying credentials. Separate them when possible.

The exact command surface is maintained in the Dockup CLI reference.

Why is a redeploy required after configuration changes?

Environment variables are read when a process starts. Updating platform configuration does not mutate the memory of a running Node.js, Python, Go, or other process. The service must start a new container with the new environment.

The correct sequence is:

dockup env set FEATURE_FLAG=on \
  -s production/api \
  --json

dockup deploy production/api --wait --json

--wait makes the second step verifiable. The default timeout is 900 seconds, exit 0 means success, and failures return non-zero with structured codes.

Dockup’s zero-downtime blue-green process starts the new version, applies the health gate, and only then shifts traffic. This avoids restarting the current container in place with an unverified configuration.

If a secret rotation changes both producer and consumer, plan compatibility. Rotating a database password before the application receives the new value can cause an outage. Use an overlap period, dual-key support, or an ordered change when the external system permits it.

The deployment mechanics are explained in zero-downtime deployments.

How does secret masking reduce agent risk?

Coding agents frequently summarize command output. A tool that returns stored secrets turns a harmless “show current config” request into credential exposure.

Dockup masks secret values. The agent can see that DATABASE_URL exists and is marked secret, but it cannot read the stored connection string. It can replace the value when the user provides a new one through a secure environment.

This supports a safer instruction:

Confirm that the required secret keys exist, but never print their values. If a value must change, read it only from the process environment and return the key name, not the secret.

Secret masking should extend to diagnostics. Avoid:

printenv

in an agent transcript, even though the PRO exec command can run one-shot container commands. Prefer a targeted application check that reports presence, length class, or connection success without disclosing the value.

The AI agent production guardrails guide covers prompt and tool boundaries together.

How should secrets be rotated and audited?

Rotation is a controlled production change, not a text edit. Use this sequence:

1. Create or obtain the new credential in the owning system.
2. Store it in the approved CI or operator environment.
3. Set the new secret in Dockup without printing it.
4. Deploy with --wait.
5. Verify health and application behavior.
6. Revoke the old credential after the new version is active.
7. Review the Dockup audit log.
8. Record the rotation date and owner without recording the value.

dockup audit --writes --json

Audit evidence should show that the configuration changed and a deployment followed. It should not contain the secret value.

For database credentials, consider connection pools. Existing connections may remain authenticated after rotation while new connections use the new password. Verification should include a fresh connection, not only requests served by an old pool.

For permissioned API keys, capture the generated value securely during creation. Store it immediately in the approved secret system, scope it to the required permissions, and rotate it without reproducing it in deployment output.

What configuration policy prevents drift?

Define which values belong in each source:

Source	Appropriate content
Repository code	Defaults that are not environment-specific
dockup.yaml	Reviewable plain deployment configuration
Dockup secret variables	Runtime credentials
CI secret store	Deployment token and injected rotation values
Managed database output	Connection data handed to the consuming service
Local .env	Developer-only values, excluded from Git

dockup.yaml apply is additive by default. Plain environment values not in the file remain until --prune is explicitly used, and secrets are never pruned through that path. Review dockup.yaml config as code before adopting manifest cleanup.

Use consistent key names across environments, but do not assume values are interchangeable. A staging key should not grant production access. Preview deployments in a private-networking project receive an automatically created read-only database user for production data access; they should not inherit write credentials by default.

Incident response for a leaked secret

If a secret appears in a transcript, log, commit, or screenshot, masking it later is not enough. Treat it as compromised:

1. Revoke or rotate it in the source system.
2. Update the Dockup secret.
3. Redeploy and verify.
4. Remove the exposed material where possible.
5. Search audit and access logs for misuse.
6. Document the cause and prevention change.

Git history rewriting can reduce future discovery but cannot prove that a copied credential disappeared. Revocation is the decisive action.

Environment review checklist

Before every production release, verify that required keys exist, secret keys are marked secret, no secret is committed, plain values match the intended environment, and a redeploy is part of the change. Then check status and uptime:

dockup status production/api --json
dockup uptime production/api --hours 24 --json

Monitoring runs every minute and includes p95 response time. A successful config deployment should still be observed for runtime regressions.

For service creation and initial setup, follow Git repository to production.

Validate configuration without disclosing it

Applications should fail clearly when a required key is missing, but diagnostics must not print the value. A startup check can report a list such as missing: ["DATABASE_URL"] or invalid format: ["PUBLIC_URL"] and then exit non-zero.

For an optional value, define the fallback in code and document whether the fallback is safe in production. Silent development defaults—local database hosts, debug modes, permissive CORS, or test credentials—should not activate merely because a production key was absent.

This validation makes environment variables and secrets observable without turning logs into a credential inventory.

Handle multiple services and shared credentials deliberately

Copying one secret into several services creates a rotation dependency. Prefer service-specific credentials where the external system supports them. A compromised worker token should not grant the same access as the public API.

When a shared value is unavoidable, maintain an owner and consumer list. Rotate all consumers in a coordinated window and verify fresh connections after each redeploy. Do not ask an agent to “find every service that probably uses this key” from name similarity; use explicit inventory and audit evidence.

Private networking can reduce exposure of database traffic, but it does not make credentials unnecessary. Internal hostnames control the path; authentication controls who may use the database.

Start with a verifiable deployment

Classify every key before setting it, verify that secret reads are masked, and include the required redeploy in the same reviewed change.

Start free at app.dockup.ai. The Free plan is $0 per month, includes $2.50 in starting credit, and supports one workspace, three databases, and three deployments.

FAQ

Does Dockup return stored secret values?

No. Secret values are masked in read output. Keys and secret markers remain visible so operators can verify that required configuration exists.

Why must I redeploy after changing an environment variable?

The running process received its environment at startup. A new deployment creates a new container with the updated values and verifies it through the health gate.

Can I put secrets in dockup.yaml?

No. Use dockup.yaml for plain reviewable configuration and use secret environment commands or CI secret injection for credentials.

How do I import multiple environment variables?

Use dockup env import with a .env-style file and the exact service target. Use the import --secret option only when all imported values are secrets.

What should I do if a secret is exposed in a log?

Revoke or rotate it immediately, update the Dockup secret, redeploy, investigate access logs, and fix the process that allowed the disclosure.