# Software Factory: Deploys and Domains
How deployments work in the software factory and how to attach custom domains.
---
Every project has a **Live URL** on the platform's shared domain (for
example `your-project.on.chipp.ai`). You can also attach one or more custom
domains from the **Domains** tab.
## How deploys happen
A deploy is triggered automatically whenever:
- The agent's branch merges into your project's default branch.
- You click **Redeploy** in the project's detail view.
- You push a commit to the default branch yourself, directly to the
platform-hosted repo -- no GitHub account, and no need to eject first. See
[Clone Your App's Code and Develop Locally](/docs/guides/alchemist-local-development).
- After ejecting your repo to your own GitHub org, your own CI pushes a
commit and calls the platform's deploy API with a deploy token.
Each deploy runs a build sandbox that produces a container image, then the
platform's rollout controller pushes that image to the live pod behind the
same URL. Crossover is a few seconds; in-flight requests finish on the old
pod.
> **Note:** **New projects ship every merge by default.** Projects are created with the
> deploy gate in **Continuous** mode: work the agent merges is built and goes
> live as soon as the build finishes, with no release click. Switch the gate to
> **Manual** to hold each release until someone clicks **Deploy now**, or to
> **Scheduled** to release on a cadence. Projects you already set to Manual stay
> on Manual.
> See [Releases, the Deploy Gate, and Rollback](/docs/guides/alchemist-releases-and-rollback).
## Deploy pacing: rapid pushes coalesce
Pushes are never rejected and never queue up into a backlog of rollouts. Every
push is accepted immediately, and if another deploy for the same project is
already waiting, the newer one **replaces** it: only the newest commit gets
built. The older row stays visible in the deploys list marked *superseded*, with
a pointer to the deploy that replaced it, so you can see what happened rather
than watching a push disappear.
Consecutive deploys for one project are spaced by a short window (about five
minutes). Push three times in two minutes and you get one build of the newest
commit, not three builds. Because the newest commit already contains the earlier
ones, nothing is lost.
A failed build does **not** consume that window, so a retry (or a fix you push
straight after a failure) is picked up right away instead of waiting.
## Deployment configuration
Everything about how your app runs is controlled by an optional
`.alchemist/deployment.yaml` file in your repo. Omit the file, or any field in
it, and you get the defaults.
```yaml
# .alchemist/deployment.yaml
resourceClass: medium # default: small
replicas: 2 # default: 1
env:
LOG_LEVEL: info
FEATURE_X: enabled
```
| Field | Values | Notes |
| --- | --- | --- |
| `resourceClass` | `small` (default), `medium`, `large` | `xl` and `xxl` need approval first: email support@chipp.ai. |
| `replicas` | 1 to 5 self-serve (default 1) | Above 5 total pods needs approval: email support@chipp.ai with your expected concurrency profile. Each pod is billed while it runs. |
| `env` | up to 50 keys, 4KB each | Applied *after* the platform's own variables, so your value wins on a name collision. |
The concurrency threshold counts **total pods**, so a `worker` block counts
toward it: `replicas: 4` plus a worker is 8 pods and needs approval, while
`replicas: 2` plus a single-replica worker is 3 and does not.
### What each resource class gets
Each pod is guaranteed its *request* and can burst up to its *limit*:
| Class | CPU request / limit | Memory request / limit | Access |
| --- | --- | --- | --- |
| `small` (default) | 0.25 / 0.5 vCPU | 256 MB / 512 MB | Self-serve |
| `medium` | 0.5 / 1 vCPU | 512 MB / 1 GB | Self-serve |
| `large` | 1 / 2 vCPU | 1 GB / 2 GB | Self-serve |
| `xl` | 2 / 4 vCPU | 2 GB / 4 GB | Approval |
| `xxl` | 4 / 8 vCPU | 4 GB / 8 GB | Approval |
`replicas` is a fixed count, not an autoscaling range: the platform runs exactly
the number of pods you declare, whatever the traffic. The one automatic
adjustment is for memory: a pod that keeps running out of memory is moved up a
class (`small` to `medium` to `large`, never into `xl` or `xxl`), and the
project owner gets an email explaining why.
### Does your size fit? The recommendation
On the project's **Deployment** tab, the **Compute size** section tells you
whether to keep, increase or reduce your size, and why. It reads your app's real
usage, never a placeholder. A banner above the size cards shows one of four
states:
| Banner | When it shows |
| --- | --- |
| **Upgrade recommended** | In the last 7 days, peak memory reached 85% or more of what your size guarantees, a container was restarted after running out of memory, or the CPU was throttled in more than a quarter of scheduling periods. The banner names the smallest larger size whose guaranteed memory would have kept that peak under 85%. |
| **Downgrade available** | For 14 days, CPU and memory both stayed under 20% of what your size guarantees, with no restarts and no CPU throttling. The banner names the largest smaller size that would have held your peak with headroom. `micro` is the floor. |
| **No change needed** | Neither rule applies. |
| **Insufficient data** | Your app has less than 7 days of usage on the current size, or CPU or memory usage could not be read. No size is recommended. |
Below the banner, an **evidence panel** lists the inputs: peak CPU, peak memory,
restarts, and CPU throttling, with the window they cover (for example "Last 7
days"). CPU and memory are shown against what is **guaranteed**. Burst capacity
is shown on its own line, because a pod can use it only when the server has spare
room. A value that could not be read shows "Not available".
The recommended size carries a **Recommended** tag, and your current size carries
a **Current** tag. The button names where it takes you, such as "Switch to
Medium", and is hidden while your current size is selected.
The recommendation describes measured usage only. It does not promise that a
different size will change how your app performs. `xl` and `xxl` still need
approval: when the size that would fit is one of them and your project has no
approval, the banner says so and points you to **Request access** instead of
offering it. Usage history is kept for 15 days, which is why the downgrade check
looks at 14 days. A size change starts the 7-day clock again, so the banner
shows "Insufficient data" until the new size has a week of usage.
### Request time limit
The load balancer in front of your app closes any single HTTP request after
**10 minutes** (600 seconds), even if the response is still streaming. Anything
that can run longer than that, such as processing a large document with AI or a
bulk import, belongs in a [background worker](#background-workers): accept the
request, record the job, return right away, and let the worker do the work and
report progress.
The schema is strict: an unknown field fails the build rather than being
ignored, so a typo surfaces immediately instead of silently doing nothing.
Anything that affects security posture (service account, secret references,
network policy, namespace) is deliberately **not** settable from this file. Those
are platform-controlled, so a bad or malicious push can never request elevated
access for itself.
## Background workers
By default one pod both serves your traffic and runs everything else your app
does. If your app has real background work (scheduled jobs, a queue consumer, a
long poll) you can move it into its own pod by declaring a `worker` block:
```yaml
worker:
replicas: 1 # default: same as `replicas`
```
Your traffic pod then receives `WORKER_ROLE=api` and the worker pod receives
`WORKER_ROLE=worker`, both running the same image.
> **Warning:** **Your app has to honor `WORKER_ROLE` before you declare this.** Both pods run
> the same code, so if your background work is not gated on that variable it will
> run in **both** pods: every scheduled job fires twice, every queue is consumed
> twice. Gate the work on `WORKER_ROLE === "worker"`, and treat the variable being
> absent as "run everything" so the app still behaves correctly when deployed
> without a worker.
>
> Apps scaffolded from a software factory template now ship this gating already: a
> `src/lib/worker-role.ts` helper plus every background starter wrapped in
> `if (runsBackgroundWork)`. If your repo has that file, you can declare a worker
> as-is.
>
> If your repo was forked from a template **before** that landed, it will not have
> the file, and the gating did not reach you retroactively. Check for
> `src/lib/worker-role.ts` first: if it is missing, port the gating before
> declaring a worker, or your background work runs in both pods.
Why bother: a deploy restarts the pod it rolls, so background work sharing the
traffic pod gets interrupted on every deploy, and a long job competes with
request latency. A separate worker pod also gets a much longer shutdown grace
so in-flight work can finish, and it rolls without touching the pod serving
your users.
A worker is an additional running pod and is billed as one, on the same CPU and
memory basis as your app pod.
## Force a redeploy
If your Live URL stops responding or you want to ship a config change without
a code change, open the project and click **Redeploy**. The platform resolves
the current HEAD SHA of your default branch, enqueues a fresh deploy at that
SHA, and returns the existing in-flight deploy if one is already deploying that
same SHA (so the button is safe to click twice). A deploy of older code, or a
settings change, never stands in for it.
## Publishing while you change a setting
A project rolls out one change at a time. A public-address change, a feature
switch, a payments mode change or a credential update re-applies the image that is already live, and it
is a rollout like any other. If you publish and change one of those settings at
the same time, the software factory orders them so your newest code is never
held back or replaced:
- A settings change waits while your publish is building. When the build is
done, the settings go live with it, in one rollout.
- A settings change that starts first always applies the newest live image,
never an older one.
- A settings change that is still rolling out when your publish finishes
building stops within seconds, and your publish goes ahead. It carries the
new settings.
- An older rollout of your own code that is still running when a newer publish
finishes building also stops within seconds, and the newer publish goes ahead.
- If the platform itself restarts in the middle of your rollout, another part
of the platform picks the rollout up within about half a minute.
- If the new version keeps crashing on startup, the publish fails within a
couple of minutes with the reason, instead of waiting for a timeout. If the
platform cannot start it at all (for example, the image cannot be pulled), the
publish fails within about half a minute and is retried for you.
- A publish does not wait behind other projects' rollouts. Publishes have their
own rollout capacity.
- A publish is marked live only after your Live URL answers from the new
version. If the Live URL keeps answering from an older version, the publish
fails with that reason and is retried.
- After a publish, the platform checks that the Live URL's script and style
files are not cached as a page by the edge network, and clears that cache if
they are.
In the Builder, the **Live** tab keeps its usual "usually in a minute or two"
note for the first couple of minutes. After that it tells you the stage
instead: still building, or "Build complete, waiting for the public-address
update to finish". If a publish fails, the note gives the reason. Publish again
to retry.
## Auto-retry on transient failures
Builds and rollouts sometimes fail for reasons that have nothing to do with
your code -- registry rate-limits, transient auth blips, a flapping upstream
mirror. The platform automatically retries a failed deploy up to **two times**
(three attempts total) before surfacing the failure to you.
While the auto-retry is in flight you'll see an amber banner: "Build failed,
auto-retrying (attempt 2 of 3)", with a note that no action is needed. If all three attempts fail, a manual
**Retry Deployment** button appears. At that point the failure is usually
something the agent can fix -- open a ticket describing the error.
## The "Built with Chipp" badge
Published apps show a small **Built with Chipp** badge in the bottom-left
corner, on the Live URL and on custom domains. Visitors can close it for the
rest of their visit.
A click on the badge opens the Chipp Builder, where the visitor can describe
an app of their own and start building it for free. They do not need an
account to type their idea. Chipp keeps it while they sign up, then starts
their project with it.
To hide the badge:
- **One app:** open the project's **Settings** tab and turn on **Hide the
Built with Chipp badge**.
- **Every app in your organization:** an organization owner or admin can turn
it on in **Organization settings**. This wins over each project's setting.
Hiding the badge is part of branding, so it needs a plan that includes
custom domains and branding. White-label platforms never show it. A change shows on
your live app within a few minutes, with no redeploy.
## Custom domains
Every project can serve traffic on a domain you already own, in addition to
(or instead of) buying one through the platform. Open the **Domains** tab to
see both paths side by side:
- **Find a domain** -- search for and buy a new domain through the platform. Domains are
billed at the registrar's wholesale price plus a flat platform markup; the
price you pay is shown at purchase and frozen on your invoice -- future
markup changes never re-bill historical purchases.
- **Connect existing domain or subdomain** -- bring a domain or subdomain you
already own by adding two DNS records at your current DNS host. This is the
path most teams want, and it's covered in detail below.
The platform handles certificate issuance and renewal automatically for
domains added through either path.
### Connecting a domain or subdomain you already own
> **Note:** You do **not** change your domain's authoritative nameservers, and you never
> delegate them to Chipp. Your domain keeps whatever nameservers (and DNS host)
> it uses today -- you're just adding two records there.
**1.**
Pick a subdomain
We recommend connecting a subdomain, such as `app.example.com`, rather
than your apex/root domain (`example.com`). A subdomain keeps your main
website on its existing setup and makes the DNS records below simpler to
add without touching anything else on the domain.
**2.**
Open the Domains tab
From your project, open the **Domains** tab and click **Connect existing
domain or subdomain**. If you have more than one project, you'll be
prompted to pick which project this domain should route to.
**3.**
Enter your hostname
Type the hostname you chose, for example:
```
app.example.com
```
Do not include `https://` (or any path).
**4.**
Add the routing CNAME
At your existing DNS host, add:
| Type | Name / Host | Target / Value |
|------|-------------|-----------------|
| CNAME | your subdomain label (e.g. `app`) | `fallback.chipp.ai` |
> **Warning:** **Using Cloudflare for DNS?** Set this record's proxy status to **DNS
> only** (gray cloud), not proxied (orange cloud). A proxied record breaks
> routing and certificate validation.
**5.**
Add the DCV/SSL validation CNAME
Once you register the hostname in step 3, the software factory generates a second,
unique DCV (domain control validation) CNAME record for that hostname.
Copy its **Name** and **Value** exactly as shown in the UI -- this record
is unique per domain, so don't reuse one from another domain or guess at
the value.
> **Warning:** Same rule applies here: if you're on Cloudflare, this record must also be
> **DNS only** (gray cloud), never proxied.
**6.**
Click Verify DNS
The software factory checks both records and, once they resolve correctly, issues
the certificate automatically. There's no separate "activate HTTPS"
step -- certificate issuance and renewal both happen automatically once
verification succeeds.
### Removing a domain
Every connected domain card on the project's **Domains** tab has a **Remove
domain** button, whether the card is healthy or shows **Needs attention**. It
is there for owners and editors of the project; viewers do not see it.
Click it and confirm. The software factory stops serving the domain, removes
its certificate and routing, and disconnects it from the project. The card
disappears from the list. You can then connect the same domain to a different
project.
The software factory does not change your DNS records. If you no longer want
them, delete them yourself at your DNS provider. If removal fails, you see an
error and the card stays, so you can try again.
### DNS records at a glance
| Step | Type | Name / Host | Target / Value |
|------|------|-------------|-----------------|
| Routing | CNAME | your subdomain label (e.g. `app`) | `fallback.chipp.ai` |
| DCV / SSL validation | CNAME | unique, shown in the software factory UI | unique, shown in the software factory UI |
### Propagation
DNS changes typically propagate within minutes, but can take up to 48 hours
depending on your provider and the record's TTL. If **Verify DNS** doesn't
succeed right away, wait a bit and try again before troubleshooting further.
### Troubleshooting
- **Verify DNS fails / CNAME not found** -- double-check the routing record's
Name matches your subdomain label and the Value is exactly `fallback.chipp.ai`
(no trailing dot mismatch, no typo). Confirm you added it at the DNS host
your domain actually uses.
- **Record present but still failing on Cloudflare** -- confirm both the
routing and DCV records are set to **DNS only** (gray cloud). A proxied
(orange cloud) record looks correct in the DNS panel but fails validation.
- **It's been a while and it's still not verifying** -- propagation can take
up to 48 hours depending on your provider and TTL; use a DNS lookup tool to
confirm the records are visible from outside your network before assuming
something is misconfigured.
- **HTTPS still shows as pending** -- this is expected until both DNS records
are verified and the DCV/SSL validation record has propagated. HTTPS
activates automatically right after that; there's no manual step to trigger
it.