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

# Projects and apps

> Describe a project, its apps, where their containers come from and how they scale and deploy.

A project link reads `project.yaml` and one file per app in `apps/`. The app
file's name is the app's name.

## The project file

```yaml title="projects/shop/project.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
display_name: Shop
cluster: hetzner-fsn1
quotas:
  pods: 40
```

```yaml title="clusters/hetzner-fsn1.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
pools:
  - name: control-plane
    role: control_plane
  - name: general
```

| Key | Meaning |
| --- | --- |
| `name`, `display_name` | The project's name and the name shown in the dashboard. |
| `cluster` | The cluster the project runs on. Required when the project is created, and fixed while it has apps. The project belongs to the cluster's environment. |
| `quotas` | Resource limits for the whole project. `{}` removes them all. |
| `isolated` | Isolate the project's apps from each other. Changing it switches an existing project; leaving it out keeps the current setting. |
| `network_policies`, `egress` | Traffic between projects and out of the cluster, see [networking](/iac/networking). |

See the [project file reference](/iac/reference/project-file) for every key.

## Where the container comes from

`source` takes exactly one of `image`, `git` or `template`. Creating an app
needs a source. Leaving `source` out of an existing app's file leaves its
source as it is.

A prebuilt image:

```yaml title="projects/shop/apps/api.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
port: 8080
```

With `pin: release`, the image is set once when the app is created. After
that, release deploys own it: the sync neither reports drift for it nor locks
it.

```yaml title="projects/shop/apps/worker.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
  pin: release
port: 8080
```

A build from a GitHub repository reachable through one of your organization's
GitHub installations:

```yaml title="projects/shop/apps/web.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  git:
    repo: example/shop-web
    branch: main
    dockerfile: Dockerfile
    context: .
port: 3000
triggers:
  on: push
```

A managed template, with its version:

```yaml title="projects/shop/apps/db.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  template: postgres
  version: "16"
instances: 1
```

`registry_credential` names a registry credential for pulling a private image.

## What deploys the app

`triggers.on` decides which events deploy a git app:

- `push`: every push to the branch.
- `prerelease` or `release`: a matching tag or release. `tag_pattern`
  narrows which tags count.
- `manual`: only deploys you start.

Without a `triggers` block a new git app deploys on `push`, like an app made in
the console: the branch head builds as soon as the app is created and on every
push after that. Set `on: manual` to deploy only when you start a deploy. A trigger
already set on the app, such as `manual` picked in the console, is kept. Static
sites follow the same default.

`github_environment` names the GitHub environment deployments are reported to.

## Ports and health checks

`port` is the app's single port. For several ports, use `ports`; the first one
is the primary port.

```yaml title="projects/shop/apps/gateway.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
ports:
  - port: 8080
    name: http
  - port: 9090
    name: metrics
health_path: /healthz
health_port: 8080
```

## Scaling

- `replicas`: a fixed number of replicas.
- `autoscaling`: `min` and `max` replicas and the `triggers` that scale
  between them (such as `cpu`, `memory`, `http` or `cron`). `scale_to_zero`
  needs `min: 0`.
- `instances`: the instance count of a template that sizes by instances
  (Postgres, Valkey, ClickHouse and others), within the template's bounds and
  counted against the project quota.
- `replica_mode`: `fixed` (the default) runs `instances` as given.
  `per_node` runs `instances` on every running node of the app's
  [`pool`](#placement), so the total grows with the pool. An app without a
  pool runs `instances` as given.

```yaml title="projects/shop/apps/storefront.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/web:2.0.0
port: 3000
autoscaling:
  min: 2
  max: 10
  triggers:
    - type: cpu
```

## Rollouts

```yaml title="projects/shop/apps/checkout.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
port: 8080
deploy:
  strategy: rolling
  max_surge: 1
  max_unavailable: "25%"
  rollback_on_failure: true
```

`strategy` is `rolling`, `recreate` or `safe_replace`. `max_surge` and
`max_unavailable` take a count or a percentage.

## Placement

- `pool`: the node pool the app runs on. It must be a pool of the project's
  cluster, and not a control-plane pool. `pool: null` unpins the app. Apps
  must name a [reserved pool](/iac/clusters#reserved) to run on it.
- `isolation`: `standard` (the default) or `sandboxed`, which runs the app
  under Kata Containers where the pool offers it and gVisor otherwise.
- `require_kata: true`: require Kata, with no gVisor fallback. Implies
  `sandboxed`.
- `gpu_count`: the number of GPUs the app needs.

## Environment variables and secrets

`env` maps names to values. A value is a literal, a
[reference](/iac/references) to another resource's output, a [database
lease](/iac/databases#consumers), or `{external: true}` for a value you set in
the dashboard. A sync never writes or removes an external key.

```yaml title="projects/shop/apps/orders.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
port: 8080
env:
  LOG_LEVEL: info
  WORKERS: 4
  STRIPE_KEY:
    external: true
secrets:
  - shop-api
```

Numbers and booleans are stored as text. `secrets` links
[secret groups](/iac/secrets) of the environment to the app; `[]` unlinks
them all.

## Sidecar and init container secrets

A sidecar or init container under `pod` can take secret groups of its own.
Their values reach that container only, as environment variables; the app
container never sees them. Use this for a key only a helper needs, such as a
download licence.

```yaml title="projects/shop/apps/catalog.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
port: 8080
pod:
  volumes:
    - { name: data, size_limit: 1Gi }
  mounts:
    - { volume: data, path: /data, read_only: true }
  sidecars:
    - name: fetcher
      image: ghcr.io/example/fetcher:2.0.0
      secrets: [shop-fetcher]
      mounts:
        - { volume: data, path: /data }
```

The groups must exist in the app's environment; a deploy naming an unknown
group fails. Only members delivered as environment variables are passed; a
group value replaces a plain `env` entry of the same name on that container.
An init container runs to completion before the app starts, and a sidecar
keeps running next to it, so an init container that fetches a file once
plus a sidecar that refreshes it means the app starts with the file present.

## Workload namespace

An app with a workload namespace can start its own pods through the
Kubernetes API. Turning the namespace on is done in the dashboard only,
because it grants that API access. Its egress policy and quotas can be set
in the file:

```yaml title="projects/shop/apps/runner.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/runner:1.0.0
workload_namespace:
  egress_internet: false
  egress_allow_fqdns: [api.example.com]
  max_pod_seconds: 3600
  quota_cpu_millis: 4000
  quota_memory_mib: 8192
  quota_pods: 20
  isolate_pods: true
```

| Key | Meaning |
| --- | --- |
| `egress_internet` | Whether the namespace's pods may reach the public internet. Private ranges stay blocked. |
| `egress_allow_fqdns`, `egress_allow_cidrs` | Hosts and address ranges they may reach. |
| `max_pod_seconds` | The longest deadline a pod or job may set; when set, every pod and job must set one. |
| `quota_cpu_millis`, `quota_memory_mib`, `quota_pods` | The namespace's resource quotas. |
| `isolate_pods` | Block traffic between the namespace's own pods; each talks only to the app, DNS and allowed egress. |
| `enabled` | `false` turns the namespace off; `true` (or any other key) on an app whose namespace is off asks to turn it on. |
| `runtime` | The runtime workload pods run under: `kata`, or `runc` in dev environments only. |

- DNS egress is managed by the platform.
- Keys you leave out keep their current values.
- Turning the namespace on or changing its settings is never applied by the
  sync alone. It is [held](/iac/gitops#held) until an environment admin
  confirms it with step-up. Turning it off narrows access, so the sync
  applies it directly.
- While a file sets `workload_namespace` for an app, the app's workload
  namespace settings can't be edited in the console or API, including
  `enabled` and `runtime` (409 `field_managed_in_git`). Change the file
  instead.

## Removing an app

Deleting an app's file holds the app as a pending deletion until someone
confirms it. `delete_data.buckets: true` also deletes the app's buckets with
it. Backups are never deleted with their app.

## Other keys

- `pod`: low-level pod settings such as command, args, resources, probes,
  sidecars and init containers. See
  [`PodSettings`](/iac/reference/types#podsettings).
- `auto_update`: watch a public image for updates.
- `build_size`: the build machine size for a `git` source: `small`
  (1 vCPU, 2 GiB), `medium` (2 vCPU, 4 GiB, the default), `large` (4 vCPU,
  8 GiB), `xlarge` (8 vCPU, 16 GiB), `2xlarge` (16 vCPU, 32 GiB), `4xlarge`
  (32 vCPU, 64 GiB), `8xlarge` (64 vCPU, 128 GiB), `16xlarge` (128 vCPU,
  256 GiB) or `20xlarge` (160 vCPU, 320 GiB). A size that doesn't
  exist or exceeds your organization's build quota is refused with
  `invalid_build_size`. While the key is set, the size picker in the console
  is locked. When machines of a size are busy, its builds wait in the queue
  instead of failing. Leaving the key out keeps the current size.
- `http`, `domains`, `connections`, `egress`: see [networking](/iac/networking).
- `volumes`, `volume_mounts`, `backup`, `backup_policies`, `cron_jobs`: see
  [volumes, backups and cron jobs](/iac/data).
- `databases`, `roles`, `lease_files`: see [databases and leases](/iac/databases).

See the [app file reference](/iac/reference/app-file) for every key.
