> ## Documentation Index
> Fetch the complete documentation index at: https://docs.springwinter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Set and Manage Environment Variables in Springwinter

> Environment variables are injected into web servers and workers at deploy time via ECS task definitions, keeping configuration separate from your code.

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.

<Note>
  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.
</Note>

## 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:

```http theme={null}
GET /api/projects/{project_id}/web_servers/{id}/environment
```

The same pattern applies to workers and static websites:

```http theme={null}
GET /api/projects/{project_id}/workers/{id}/environment
GET /api/projects/{project_id}/static_websites/{id}/environment
```

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:

```http theme={null}
PUT /api/projects/{project_id}/web_servers/{id}/environment
Content-Type: application/json

[
  { "name": "DATABASE_URL", "value": "postgres://user:pass@host:5432/mydb" },
  { "name": "REDIS_URL", "value": "rediss://cache.internal:6379" },
  { "name": "APP_ENV", "value": "production" }
]
```

The same endpoint pattern works for workers and static websites:

```http theme={null}
PUT /api/projects/{project_id}/workers/{id}/environment
PUT /api/projects/{project_id}/static_websites/{id}/environment
```

<Warning>
  `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.
</Warning>

## 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:

```http theme={null}
POST /api/projects/{project_id}/web_servers/{id}/redeploy
```

<Tip>
  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.
</Tip>

## 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:

```http theme={null}
PUT /api/projects/{project_id}/web_servers/{id}/previews/{preview_id}/environment
```

This lets you point a preview at a staging database or a test API key without touching the production configuration. See [Preview Environments](/concepts/previews) for more details on how previews work.

## Handling Sensitive Values

<Tip>
  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.
</Tip>

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.