> ## 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 Web Server from GitHub to AWS ECS

> Build and run a containerized HTTP service on AWS ECS from your GitHub repository, with a public URL and auto-deploy on every push.

A web server in Springwinter is a containerized HTTP service built directly from your GitHub repository and run as a container inside your own AWS account. Springwinter provisions the load balancer, assigns a public URL, manages TLS, and keeps the container running — you own the infrastructure and the code.

## Requirements

Before you deploy a web server, make sure you have:

* A GitHub repository containing a `Dockerfile`, a `Procfile`, or a custom build command that produces a runnable container image.
* An AWS account connected to Springwinter via the CloudFormation IAM role. See [Connect Your AWS Account](/connect-aws).
* A GitHub account connected via the Springwinter GitHub App. See [Connect GitHub](/connect-github).

## Deploy a Web Server

<Steps>
  <Step title="Open your project">
    Navigate to your project in the Springwinter dashboard. If you do not have a project yet, create one from the dashboard home screen.
  </Step>

  <Step title="Add a web server resource">
    Click **Add resource**, then select **Web server** from the resource type list.
  </Step>

  <Step title="Select a repository and branch">
    Choose the GitHub repository you want to deploy from. Then select the branch to track — Springwinter will build and deploy every time a commit is pushed to that branch.
  </Step>

  <Step title="Configure your build">
    If your repository does not have a `Dockerfile` at the root, enter a custom **build command** that produces the image. Set the **health check path** — the HTTP path Springwinter polls to determine whether your container is healthy. The default is `/`.
  </Step>

  <Step title="Choose a compute size">
    Select the **CPU** and **memory** allocation for your container. You can change these later by patching the resource.
  </Step>

  <Step title="Deploy">
    Click **Deploy**. Springwinter validates the required IAM permissions, builds the container image, and launches the service. When the health check passes, your public URL becomes active.
  </Step>
</Steps>

<Note>
  Springwinter checks every required IAM action against your connected role before creating any resource. If a permission is missing, deployment stops immediately and nothing is created in your account.
</Note>

## Configuration Options

<CardGroup cols={2}>
  <Card title="Source" icon="code-branch">
    The GitHub repository and branch to build from. Toggle **auto-deploy** to control whether every push to the tracked branch triggers a new deployment automatically.
  </Card>

  <Card title="Compute" icon="microchip">
    The CPU units and memory (MiB) allocated to your container. Update these at any time — Springwinter performs a rolling replacement with zero downtime.
  </Card>

  <Card title="Health Path" icon="heart-pulse">
    The HTTP path Springwinter uses to determine container health. Return a `200`–`399` status on this path to pass the health check. Defaults to `/`.
  </Card>

  <Card title="Environment Variables" icon="key">
    Injected into the container at runtime. Manage them from the dashboard or via the API. See [Environment Variables](/concepts/environment-variables).
  </Card>
</CardGroup>

## API Reference

### Create a Web Server

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

```json theme={null}
{
  "name": "my-web-server",
  "repository": "my-org/my-app",
  "branch": "main",
  "cpu": 256,
  "memory": 512,
  "health_check_path": "/healthz",
  "auto_deploy": true
}
```

### Get a Web Server

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

### Update a Web Server

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

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

## Redeploy

To trigger a manual redeploy without pushing a commit, call the redeploy endpoint:

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

Springwinter pulls the latest image for the tracked branch and performs a rolling update of the service.

## Branch Previews

Every branch in your repository can have its own isolated preview deployment, each with its own URL. Previews are created by calling:

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

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

Each preview is a full copy of the service running in your AWS account. For a full explanation of how previews work, see [Branch Previews](/concepts/previews).

## Environment Variables

Retrieve the current environment variables for a web server:

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

Replace all environment variables at once:

```http theme={null}
PUT /api/projects/{project_id}/web_servers/{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",
  "NODE_ENV": "production"
}
```

<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 and Metrics

Logs are streamed from CloudWatch and are accessible from the **Logs** tab of your web server in the dashboard, or via the API:

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

CPU utilization, memory usage, request count, and error rate metrics are available under the **Metrics** tab or at:

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

## Cost Estimate

Springwinter shows a live cost estimate and monthly run rate for each web server. Retrieve the current estimate via the API:

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

## Teardown

Deleting a web server removes the container service and the load balancer listener rule from your AWS account:

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

<Warning>
  Teardown is permanent. The container service and all associated run history are removed from your account. Ensure you no longer need the resource before deleting it.
</Warning>