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

# Deploy a Background Worker from GitHub to AWS

> Run long-running background processes on AWS ECS from your GitHub repository — no public URL, no ports, just continuous execution.

A worker in Springwinter is a long-running background process built from your GitHub repository and run as a container inside your own AWS account. Unlike web servers, workers expose no HTTP port and receive no public URL — they run continuously in the background, processing work as fast as your code allows.

## Use Cases

Workers are the right resource type for any process that runs independently of incoming HTTP traffic:

<CardGroup cols={2}>
  <Card title="Queue Consumers" icon="list-check">
    Pull jobs from SQS, Redis, or any other queue and process them in a tight loop.
  </Card>

  <Card title="Scheduled Jobs" icon="clock">
    Run periodic tasks such as report generation, cache warming, or data aggregation on a fixed schedule.
  </Card>

  <Card title="Data Pipelines" icon="database">
    Ingest, transform, and load data between systems without tying up a web server.
  </Card>

  <Card title="Webhook Processors" icon="webhook">
    Consume events from third-party services and take action asynchronously.
  </Card>
</CardGroup>

## Requirements

Before you deploy a worker, make sure you have:

* A GitHub repository with a `Dockerfile` or a build setup that produces a runnable image.
* An AWS account connected to Springwinter. See [Connect Your AWS Account](/connect-aws).
* A GitHub account connected via the Springwinter GitHub App. See [Connect GitHub](/connect-github).

## Deploy a Worker

<Steps>
  <Step title="Open your project">
    Navigate to your project in the Springwinter dashboard and click **Add resource**.
  </Step>

  <Step title="Select the Worker resource type">
    Choose **Worker** from the resource type list. You will be taken to the worker configuration form.
  </Step>

  <Step title="Select a repository and branch">
    Pick the GitHub repository and the branch to track. Springwinter builds a new image and redeploys the worker on every push to that branch when auto-deploy is enabled.
  </Step>

  <Step title="Set the start command">
    If your `Dockerfile` does not define a default command, or you want to override it, enter the **start command** — for example, `python worker.py` or `node dist/worker.js`.
  </Step>

  <Step title="Choose a compute size">
    Select the CPU units and memory allocation for the container. Larger workers can process more jobs in parallel or handle heavier in-memory workloads.
  </Step>

  <Step title="Deploy">
    Click **Deploy**. Springwinter builds the image and starts the container. The worker begins running immediately once the container reaches a running state.
  </Step>
</Steps>

## Configuration Options

<Accordion title="Source">
  The GitHub repository and branch your worker is built from. Enable **auto-deploy** to automatically rebuild and restart the worker whenever you push a new commit to the tracked branch.
</Accordion>

<Accordion title="Compute size">
  CPU units and memory (MiB) assigned to the container. You can update the compute size at any time — Springwinter stops the current container and starts a replacement with the new allocation.
</Accordion>

<Accordion title="Auto-deploy">
  When enabled, every push to the tracked branch triggers a new build and a rolling restart of the worker. Disable auto-deploy if you want to control exactly when the worker is updated.
</Accordion>

<Accordion title="Environment variables">
  Injected into the container at launch. Use environment variables to pass connection strings, API keys, and feature flags to your worker process. See [Environment Variables](/concepts/environment-variables).
</Accordion>

## API Reference

### Create a Worker

```http theme={null}
POST /api/projects/{project_id}/workers
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{
  "name": "my-background-worker",
  "repository": "my-org/my-app",
  "branch": "main",
  "start_command": "python worker.py",
  "cpu": 256,
  "memory": 512,
  "auto_deploy": true
}
```

### Get a Worker

```http theme={null}
GET /api/projects/{project_id}/workers/{id}
Authorization: Bearer <token>
```

### Update a Worker

```http theme={null}
PATCH /api/projects/{project_id}/workers/{id}
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{
  "cpu": 512,
  "memory": 1024
}
```

## Redeploy

To manually trigger a new build and restart without pushing a commit:

```http theme={null}
POST /api/projects/{project_id}/workers/{id}/redeploy
Authorization: Bearer <token>
```

Springwinter fetches the latest commit on the tracked branch, builds a fresh image, and replaces the running container.

## Branch Previews

Each branch in your repository can have its own isolated preview worker deployment. Create a preview via the API:

```http theme={null}
POST /api/projects/{project_id}/workers/{id}/previews
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{
  "branch": "feature/new-processor"
}
```

Each preview runs as a fully independent worker in your AWS account. For a full explanation, see [Branch Previews](/concepts/previews).

## Environment Variables

Retrieve the current environment variables for a worker:

```http theme={null}
GET /api/projects/{project_id}/workers/{id}/environment
Authorization: Bearer <token>
```

Replace all environment variables at once:

```http theme={null}
PUT /api/projects/{project_id}/workers/{id}/environment
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{
  "DATABASE_URL": "postgresql://user:pass@host:5432/db",
  "REDIS_URL": "rediss://cache-endpoint:6379",
  "QUEUE_NAME": "jobs"
}
```

<Note>
  `PUT` replaces the entire set of environment variables. Any keys not included in the request body are removed. See [Environment Variables](/concepts/environment-variables) for full details.
</Note>

## Logs

Worker output (stdout and stderr) is forwarded to CloudWatch and surfaced in the Springwinter dashboard under the **Logs** tab. You can also fetch logs via the API:

```http theme={null}
GET /api/projects/{project_id}/workers/{id}/logs
Authorization: Bearer <token>
```

## Metrics

CPU utilization and memory usage for your worker are available from the **Metrics** tab or via the API:

```http theme={null}
GET /api/projects/{project_id}/workers/{id}/metrics
Authorization: Bearer <token>
```

## Cost Estimate

Retrieve the current cost estimate and monthly run rate for a worker:

```http theme={null}
GET /api/projects/{project_id}/workers/{id}/cost
Authorization: Bearer <token>
```

## Teardown

To delete a worker and remove the container service from your AWS account:

```http theme={null}
DELETE /api/projects/{project_id}/workers/{id}
Authorization: Bearer <token>
```

<Warning>
  Deleting a worker stops the container immediately. Any in-flight jobs the worker is processing will be interrupted.
</Warning>

<Tip>
  Workers share the same environment variable API as web servers. Pass your cache connection string or database URL as an environment variable so the worker can connect to other resources in the same project without any hard-coded configuration.
</Tip>