quadlet-migrator-skill/references/env-strategy.md

Environment Strategy

Use this file whenever the migration includes .env, env_file, Compose interpolation, or inline -e flags.

Goals

• preserve source-of-truth for variables
• avoid leaking secrets into generated Quadlet files by default
• keep resulting units readable
• report missing variables explicitly
• reduce large upstream env templates into a small set of user decisions

Default rules

The agent should actively interpret the env template and its comments. Do not offload the entire env review back to the user.

Prefer Environment= when

• there are only a few variables
• values are stable and not sensitive
• keeping everything in one file materially improves readability

Prefer EnvironmentFile= when

• the source already uses .env or env_file
• variables are numerous
• variables contain secrets or deployment-specific values
• the same env file is shared by multiple services

Sensitive-value heuristic

Treat names containing these substrings as sensitive unless the user tells you otherwise:

• PASSWORD
• TOKEN
• SECRET
• KEY
• PRIVATE
• PASS

Default behavior:

• do not inline them in Environment=
• keep them in EnvironmentFile= or generate a placeholder sample file instead

Compose interpolation

Common forms:

• ${VAR}
• ${VAR:-default}
• ${VAR-default}

Strategy:

• if the actual value source is present, resolve it and document where it came from
• if only a default is available, note that the value is default-derived
• if the variable is missing, list it as unresolved

Do not fabricate values.

Agent responsibility

When the source project ships a large .env.example or multiple env templates:

• read the comments and deployment docs yourself
• determine which values can safely stay at documented defaults
• determine which values are true deployment decisions and must be confirmed with the user
• prepare a candidate .env or env delta instead of asking the user to read the whole template manually

The user should only need to answer the small number of high-impact questions that cannot be discovered locally.

Minimal examples

Inline stable values

Source intent:

environment:
  APP_ENV: production
  APP_PORT: "8080"

Reasonable result shape:

[Container]
Environment=APP_ENV=production
Environment=APP_PORT=8080

Use this when there are only a few non-sensitive structural values.

Preserve env-file workflow

Source intent:

env_file:
  - .env

Reasonable result shape:

[Container]
EnvironmentFile=/opt/myapp/.env

Use this when the source already relies on an env file, especially for secrets or many variables.

Large template reduced to a candidate env

Source intent:

• upstream ships .env.example
• only a few values are true deployment decisions

Recommended behavior:

• keep documented defaults that are safe to preserve
• ask the user only for high-impact values such as domain, storage path, or database password
• generate a candidate .env or env delta with clear placeholders for the unresolved items

Output patterns

Small inline set

[Container]
Environment=APP_ENV=production
Environment=APP_PORT=8080

External env file

[Container]
EnvironmentFile=/opt/myapp/myapp.env

Mixed pattern

Use this when a few values are structural and the rest are secret or deployment-specific.

[Container]
Environment=APP_ENV=production
EnvironmentFile=/opt/myapp/myapp.env

Missing-variable reporting

When variables cannot be resolved, report them as a concrete checklist.

Example:

• missing DB_PASSWORD
• missing IMMICH_VERSION
• missing UPLOAD_LOCATION

If the user asks for scaffolding, generate a sample env file with obvious placeholders.

Even when the user does not explicitly ask for scaffolding, produce a candidate env result when that materially advances the migration.