Skip to main content
Environment variables are the primary way to pass runtime configuration — connection strings, API keys, feature flags, and service URLs — into your Springwinter services. Springwinter stores variables as ECS task environment variables and injects them into your container process at startup, so your application reads them from the standard environment just like any other twelve-factor app.

​
How Environment Variables Work

When you deploy a web server or worker, Springwinter writes your environment variables directly into the ECS task definition for that service. Each time a new task starts — whether due to a redeploy, a scaling event, or a task replacement — ECS passes the variables to your container process as part of the startup sequence. No sidecar, secrets agent, or custom SDK is required; your application reads them with process.env, os.environ, System.getenv, or whichever standard mechanism your language provides.
Environment variables are scoped to a single resource. A web server and a worker inside the same project do not automatically share variables — you set them independently for each resource.

​
Reading Environment Variables

To retrieve the current environment variable set for a resource, send a GET request to the environment endpoint for that resource type:
The same pattern applies to workers and static websites:
The response is a JSON array of { "name": "...", "value": "..." } objects representing every variable currently set on the resource.

​
Setting Environment Variables

To update the environment variables for a resource, send a PUT request with the complete list of variables you want active:
The same endpoint pattern works for workers and static websites:
PUT replaces the entire environment variable set. Include all variables you want to keep, not just the ones you are changing. Any variable omitted from the request body is permanently removed from the resource’s configuration.

​
Applying Changes

Setting new environment variables does not automatically restart your service. You must trigger a redeploy for the updated task definition — and therefore the new variables — to take effect. You can do this from the dashboard by clicking Redeploy, or via the API:
Batch all your environment variable changes into a single PUT request before triggering a redeploy. This way, your service restarts exactly once with the full updated configuration rather than cycling multiple times.

​
Preview Environments

Preview environments inherit the environment variables of the production resource they are based on at the time the preview is created. You can override individual variables for a specific preview by calling the same PUT endpoint on the preview resource:
This lets you point a preview at a staging database or a test API key without touching the production configuration. See Preview Environments for more details on how previews work.

​
Handling Sensitive Values

For secrets such as database passwords, API keys, and signing keys, store the value in AWS Secrets Manager and reference it via an ECS secret rather than a plain environment variable. Springwinter reads the secret from Secrets Manager when the task starts and injects it into the process environment — the secret value is never stored in plaintext by Springwinter.
To use an ECS secret reference, set the variable value to the ARN of the Secrets Manager secret or the name of a Systems Manager Parameter Store parameter. Ensure the IAM role Springwinter assumes has secretsmanager:GetSecretValue or ssm:GetParameters permission for the resource in question.