# Deployments

> Follow a NexHost release from source preparation through build, startup, and readiness.

Source: https://nexthomelabs.com/docs/deployments
Markdown: https://nexthomelabs.com/docs-md/deployments
Slug: deployments
Section: Operate
Last updated: 2026-08-30
Reading time: 5 min read

---

# Deployments

Every deployment records five things: **which source** brought the code, **which configuration** was in force, **what the build output** said, **whether the platform could start the artifact**, and the **final status**. Open **Deployments** from the dashboard to see releases across the whole workspace, or use a single project’s deployment history to watch one service in isolation.

Treat deployments as the platform’s audit log for itself. When someone asks what shipped, what failed, and what changed, the deployment detail page is the answer.

## When to use this

- When you want to know whether a change you made actually reached production.
- When a build succeeded locally but the remote release failed or never became reachable.
- When you need to restore a previously known-good release quickly.

## Release flow

Each release moves through a fixed sequence. The detail page separates output by stage so you can tell whether the problem was source, configuration, or application behavior:

1. **Source** — NexHost prepares the selected repository, archive, folder, or image. Failures here usually mean the branch, path, or image reference did not resolve.
2. **Dependencies and build** — the configured install and build commands run when required (`npm ci`, `pip install -r requirements.txt`, `npm run build`, etc.). Failures here mirror the same commands failing locally.
3. **Publish or start** — a Static Site publishes its output directory; a runtime service starts its configured process (for example `npm start`, `gunicorn …`, or a custom server command).
4. **Readiness** — runtime services must open a TCP listener reachable through their container network. NexHost discovers that listener and allocates isolated ingress automatically; Static Sites skip this step.

The release detail page shows **which step failed** — not just that something failed. A successful build followed by a failed readiness check is a startup/configuration issue, not a source-build issue. That distinction decides whether you touch source/settings or application startup and binding behavior next.

> [!TIP]
> The split exists so you fix in the right layer. A successful build that cannot become reachable will not be fixed by changing the branch — read the startup and readiness output instead.

## How to use the deployment list

The workspace **Deployments** screen is a live, filtered view over all recent releases. Use it as a system dashboard; drill into a project’s own **Deployments** tab when you care about a single service.

| What you want | Where to click | What to notice |
| --- | --- | --- |
| "Did my last commit deploy?" | Sort by time, find the row for the service and branch | Source commit or archive name, status, and timestamp. |
| "Which configuration rode with that release?" | Open the row → detail page | Framework detection where available, output directory, chosen stack, and scoped environment variables snapshot. |
| "Why is the public URL still serving the previous version?" | Status column: look for a failed readiness step | A healthy build but failed startup readiness leaves the previous successful release live. |
| "Who triggered what?" | Detail line for trigger/source + timestamp | The actor and the recorded source line — useful when multiple teammates deploy. |

## Review a deployment

Open a deployment to review its **source information**, **framework detection** where available, **output directory**, **build log**, and **timestamps**. Some useful checks in order:

1. **Source** — branch and root directory match the package that actually contains the build manifest? A mis-pointed root is a frequent source of dependency failures.
2. **Framework / stack** — does the detected stack match the actual project? When the dashboard suggests a different preset, correct it rather than carrying a stale assumption forward.
3. **Configuration snapshot** — build and start commands, publish directory, and environment variable scoping all ride with the release record. If two otherwise-identical deploys behave differently, the diff of this snapshot is often the explanation.
4. **Build log** — search from the first error upward. The earliest error is usually the root cause; later timeouts and connection warnings are downstream consequences.
5. **Timestamps** — correlate the deployment time against when a teammate says they pushed or changed a setting.

Use **Retry deployment** only **after** correcting the relevant source or configuration problem. Retrying the same failing input with no change produces the same failure and buries the useful log diff under noise.

## Restore a release

When the project shows a **previous successful release**, use the **restore action on that release** to make it active again. Restoration does not rebuild — it returns the project to a previously observed working state, which is valuable when a recent change was clearly harmful.

Before you confirm, review the restore summary — the platform shows the service and the version you are about to reactivate. Confirm you are restoring the right project and the right release (timestamp and source line), then confirm the action. Not every project will have a previous successful release available; when none is shown, restore is not applicable.

> [!WARNING]
> Restoration brings the platform back to a release the platform previously recorded as successful — it does not merge, patch, or cherry-pick a single file. Fix forward in Git/CLI and redeploy if a surgical change is more appropriate.

## Building confidence over time

Two habits keep the deployment history useful rather than noisy:

- **Small, diagnosable changes.** Prefer one edit per release while debugging. Changing two things at once doubles the search space when you compare two logs.
- **Own the review screen.** Before clicking deploy, re-read the branch, root, commands, directory, and environment variable scopes with the detail page of the **next** deployment in mind — as if you will soon need to read it cold.

## Next steps

- Something failed in an identifiable stage? Start at [Deployment Troubleshooting](/docs/deployments/troubleshooting) — it maps symptoms to stage and exact field to check.
- Need broader reading of output? See [Logs](/docs/operations/logs) for how the detail page is structured and how to share excerpts safely.
- Deploying a frontend that still fails startup readiness? Reread [Frontend Apps](/docs/services/frontend-app) and verify the start command and `0.0.0.0` binding pattern shown there.