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