Working with environment variables

The files in the env/ directory

The env/ directory in app and backend repositories contains files following the pattern <environment>.<kind>.env with the environments local, dev, prod, and shared (all environments) and the kind generated or custom.

The platform overwrites the generated files whenever the configuration changes, so you do not edit them; in the custom files you add or override values. ap run-local loads both kinds for the matching environment, for Flutter apps via --dart-define-from-file; a new local variable goes into env/local.custom.env followed by a restart, a value for all environments into shared.custom.env. New generated values require a change to the platform configuration; ask support.

Deployment configuration for dev and prod

What runs on the servers is configured in your project’s gitops-configuration repository with one folder per environment:

gitops-configuration/
└── configurations/
    ├── dev/
    │   ├── generated.yaml   # platform: hostnames, registry, secrets (SOPS)
    │   ├── custom.yaml      # you: your own environment variables
    │   └── versions.yaml    # pipeline: deployed image versions
    └── prod/                # same structure

The platform writes generated.yaml, the pipeline maintains versions.yaml, and custom.yaml is yours and takes your own environment variables under additional_env_variables. A commit to main rolls the change out to the respective environment, as Git workflow and deployment describes; the overall picture is shown in Architecture.

Secrets

Passwords, tokens, and keys such as database credentials, JWT secrets, and registry credentials are generated and managed by the platform; in generated.yaml they are encrypted with SOPS and edited with ap secrets edit <file>.

Do not print env files in full, not even in a chat with an AI agent, and never commit secrets; the AGENTS.md in the project already contains this rule.