> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Deploy a static site

> Publish a static site from a Git repository or an uploaded archive, and roll back to an earlier version.

**Goal**: a static site (HTML, CSS, JavaScript and assets) served by
A-Line.cloud, built from Git or uploaded as an archive.

A static site does not need a container: A-Line.cloud runs the server for
you. Each deploy of a **Versioned** site is a new immutable version, so you can
switch back to an older one at once.

## Before you start

- A [project](/getting-started/create-project) on a running cluster.
- Either a repository that builds the site (for example `npm run build`
  writing to `dist/`), or the built site as a `.zip` or `.tar.gz`.
- To build from a private repository: GitHub connected under **Settings >
  Integrations**.

## Option A: build from Git

<Steps>
<Step>

On the project canvas, select **From Git** in the sidebar.

</Step>
<Step>

Pick the repository and **Branch**, then set **Deploy as** to **Static
site**. The dialog marks it **Detected** when the repository looks like
a static site.

</Step>
<Step>

Select **Create site**. A-Line.cloud detects the framework and opens the
build settings:
- **Install command**, such as `npm ci`.
- **Build command**, such as `npm run build`.
- **Output directory**, such as `dist`.
- **Serve index.html for paths that match no file**: turn this on for a
  single-page app with client-side routing.
- **Headers** and **Redirects**, if you need them.

</Step>
<Step>

Select **Save & build**. The first version is built and published.

</Step>
</Steps>

Pushes to the branch build and publish a new version.

## Option B: upload an archive

<Steps>
<Step>

On the project canvas, select **Static Site** in the sidebar.

</Step>
<Step>

Pick the **Mode**:
- **Versioned**: immutable versions, instant rollback. Use this unless
  you have a reason not to.
- **Live**: one file tree, changes go out in place.

</Step>
<Step>

Select **Create site**.

</Step>
<Step>

Under **Upload a site archive**, drop a `.zip` or `.tar.gz` of the built
site (up to 1 GiB per version). Select **Upload later** to skip this
step for now.

</Step>
</Steps>

## Verify

Open the site on the canvas. The **Overview** tab shows the **Active
version** and a **Temporary URL**; open it to see the site. The
**Deploys** tab lists every version with its build and publish log.

## Roll back

On the **Deploys** tab, open the menu of an older version and select **Make
live**. The switch is immediate. A versioned site keeps 20 versions by
default; change it with **Versions kept** on the **Config** tab.

## Serve it on your domain

Open the site's **Domain** tab and add a host, the same way as for an app.
See [Add a custom domain](/guides/custom-domain).

## In IaC

A site linked to Git is a file `projects/<project>/sites/<site>.yaml`:

```yaml title="projects/web/sites/docs.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  repo: example/docs
  branch: main
retain_versions: 10
settings:
  install_command: npm ci
  build_command: npm run build
  output_dir: dist
  spa_fallback: true
```

All keys are in the [site file reference](/iac/reference/site-file).

## Troubleshooting

- **The build succeeds but the site is empty or 404s**: the **Output
  directory** is wrong. It must be the folder that holds `index.html` after
  the build.
- **Deep links of a single-page app return 404**: turn on **Serve
  index.html for paths that match no file**.
- **The upload is refused**: the archive must be a `.zip` or `.tar.gz` of
  at most 1 GiB.

## Next steps

- [Add a custom domain](/guides/custom-domain)
- [HTTP settings](/iac/networking#http): HTTPS and www redirects, HSTS and compression.
- [Logs and metrics](/guides/logs-and-metrics)
