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

# Springwinter Projects: Organize and Deploy Resources

> A project is the top-level container for all your Springwinter resources, grouping web servers, workers, databases, caches, and more.

A project is the top-level organizational unit in Springwinter. Every resource you deploy — web servers, workers, static websites, caches, databases, and storage buckets — lives inside a project. Projects share a hostname suffix, an AWS connection, and access permissions with your team, making it easy to keep related services together and manage them as a unit.

## What a Project Contains

Each project can hold any combination of the following resource types:

* **Web servers** — containerized HTTP services with a public URL, running on ECS.
* **Workers** — background ECS processes with no public URL.
* **Static websites** — files built from GitHub and served via S3 + CloudFront.
* **Caches** — Valkey (Redis-compatible) instances running in your AWS account.
* **Databases** — PostgreSQL or MySQL instances managed by AWS RDS.
* **Storage buckets** — private S3 buckets with metrics and cost tracking.

All resources inside a project share the same AWS account connection and are visible to every team member with access to that project.

## Hostname Suffix

Every project has a **hostname suffix** that Springwinter appends to resources by default when generating their public URLs. For example, if your suffix is `acme.springwinter.app`, a web server named `api` would receive the URL `api.acme.springwinter.app`.

You can update the hostname suffix at any time using the API:

```http theme={null}
PATCH /api/projects/{id}
Content-Type: application/json

{
  "hostname_suffix": "your-new-suffix.springwinter.app"
}
```

<Warning>
  Changing the hostname suffix updates the URLs of all resources in the project. Make sure to update any DNS records, environment variables, or external integrations that reference the old URLs before making this change.
</Warning>

## Enabling HTTPS

Springwinter can provision an AWS Certificate Manager (ACM) certificate for your project's load balancer, enabling HTTPS for all web servers in the project. To enable HTTPS, send a request to the certificate endpoint:

```http theme={null}
POST /api/projects/{project_id}/certificate
```

Springwinter requests the certificate from ACM and attaches it to the project load balancer automatically. To disable HTTPS and remove the certificate:

```http theme={null}
DELETE /api/projects/{project_id}/certificate
```

<Note>
  ACM certificate provisioning requires DNS validation. Springwinter will provide the CNAME records you need to add to your DNS provider. The certificate becomes active once DNS validation completes.
</Note>

## Creating a Project

<Steps>
  <Step title="Open the dashboard">
    Sign in at [springwinter.dev](https://springwinter.dev/auth?mode=signup) and navigate to the main dashboard.
  </Step>

  <Step title="Click New Project">
    Select **New Project** in the top-right corner of the projects list.
  </Step>

  <Step title="Name your project">
    Enter a name for your project. The name is used to generate the default hostname suffix and must be unique within your account.
  </Step>

  <Step title="Confirm creation">
    Click **Create Project**. Springwinter provisions the project and takes you to the project overview, where you can start adding resources.
  </Step>
</Steps>

## Deleting a Project

You can only delete a project that contains no resources. Before deleting, remove all web servers, workers, static websites, caches, databases, and storage buckets from the project. Once the project is empty, send:

```http theme={null}
DELETE /api/projects/{id}
```

<Warning>
  Deleting a project is permanent. Any project-level settings, hostname suffix configuration, and ACM certificates are removed immediately and cannot be recovered.
</Warning>

## API Reference

The following endpoints let you manage projects programmatically. All requests require an `Authorization: Bearer <token>` header or an active cookie session with a CSRF token.

| Method | Endpoint | Description |
| - | - | - |
| `GET` | `/api/projects` | List all projects in your account. |
| `POST` | `/api/projects` | Create a new project. |
| `GET` | `/api/projects/{id}` | Retrieve details for a single project. |
| `PATCH` | `/api/projects/{id}` | Update the project name or hostname suffix. |
| `DELETE` | `/api/projects/{id}` | Delete an empty project permanently. |
| `POST` | `/api/projects/{project_id}/certificate` | Provision an ACM certificate and enable HTTPS. |
| `DELETE` | `/api/projects/{project_id}/certificate` | Remove the ACM certificate and disable HTTPS. |