# How Noust works, and what it leaves when it goes

Noust is a program that writes the ordinary files of a Linux server (systemd units, web server
sites, certbot's configuration) and runs the tools that read them. This page is the model in one
place: what an application is on disk, what a release and the health gate are, who a build runs
as, what Noust does not do, and what happens to your applications if you remove it. Each section
ends in the page that has the detail.

## What is on your server

| What | Where | Who reads it |
|---|---|---|
| An application's code | `/var/www/apps/{app}/`, where `{app}` is the domain with dots as dashes (`shop.example.com` is `shop-example-com`) | the application |
| Its process | the unit `{app}.service` (systemd), or a Docker Compose project run as a unit | systemd |
| Its site | a file in the web server's sites directory, marked "Generated by Noust" when Noust wrote it | nginx or Apache |
| Its certificate | certbot's own directory, `/etc/letsencrypt` | certbot, the web server |
| Noust's configuration, secrets and audit trail | `/etc/noust` (secrets are written mode 0600; the trail is `web-audit.log`) | Noust |
| Noust's state (the store, deployment and job logs) | `/var/lib/noust` | Noust |
| Noust's own log files (the monitor's) | `/var/log/noust` | Noust |
| Backups | `/var/backups/noust`, and the destinations you add | Noust |
| Noust's own units | `noust-web` (the console, only if you enabled it), `noust-monitor`, and timers for the work you scheduled: `noust-cron-*`, `noust-backup-*`, storage cleanup, automatic updates | systemd |

Nothing here is private to Noust. You can read an application's unit with `systemctl cat`, its
site with `cat`, and its logs with `journalctl`, and the server goes on serving if you do. Units
from before 0.14.1 keep a legacy prefix until the application's next deployment, which renames the
unit as part of the restart it makes anyway.

## A release

A deploy does not rebuild the tree that is serving. It builds in its own directory,
`releases/<id>/`, and a link called `current` points at the release that serves; the unit and the
site point at `current`, so the same unit and the same site serve whichever release is active. The
`.env` and the paths that must persist (uploads, storage) live in `shared/`, outside every
release. Going back is pointing `current` at an older release still on disk and restarting: seconds,
no rebuild. Applications deployed by 1.x build in place and stay that way until you migrate
them; Noust never converts one on its own.

Detail: [releases.md](/docs/guides/releases/).

## The health gate

Every time an application is activated (a deploy, an update, a rollback, a migration, a change of
limits that restarts it) Noust asks it to answer: the path, the status codes and the time you
configured, or the defaults. If it does not answer, **what served before is put back** (the previous
release, the in-place tree, the old limits) and the error carries the probes and the journal as
they were, not a summary. A new application that runs a process behind nginx starts as two
instances, and the next release starts beside the old one; nginx switches only once it answers.

What the gate cannot do is put a database back. A deploy that changes the schema is a decision:
going back to older code after a migration asks you to confirm that, and Noust puts code back, never
data. Older data is a restore from a backup.

Detail: [releases.md](/docs/guides/releases/), [declarative.md](/docs/guides/declarative/) (the health check and its
settings).

## Who a build runs as

A repository is somebody else's code, so installing and building never run as root. They run as an
unprivileged account (`noust-build`) in a transient systemd unit that cannot read the rest of the
machine, and Noust refuses to build when it cannot prove the sandbox is in place. An application
created from 3.2 also runs as a system account of its own, so one cannot read another's files; the
ones from before keep the shared account until you move them (`noust app identity migrate`).

The sandbox is a boundary between a build and the machine, **not** between running applications:
they share the kernel, the disk and the network of the server.

Detail: [security.md](/docs/concepts/threat-model/#builds), [security.md](/docs/concepts/threat-model/#threat-model).

## What Noust does, and does not do

- It **writes files and runs the tools that read them** (nginx, systemctl, certbot, git, a
  package manager, a database client), always as a list of arguments and never through a shell.
- It **is not in the path of your traffic.** nginx or Apache serves; Noust is not a proxy and has no
  daemon your requests go through. The console is optional, and is a client of the same commands.
- It **changes nothing it did not make** without being told. A site you wrote is never rewritten,
  a Compose stack you already ran is adopted without being touched, and a directory it did not
  create is never removed unless you name it.
- It **is not a cluster.** Each server manages itself; a central drives several by SSH tunnel and
  schedules nothing across them.
- It **sends nothing out you did not set up.** What leaves a server is listed in
  [PRIVACY.md](/docs/concepts/privacy/).

Detail: the README's "What Noust is, and is not", and [security.md](/docs/guides/security/).

## Taking Noust away

Removing the program does not take your applications with it: they are systemd units, web server
sites and certbot certificates, and none of them needs Noust to keep running. What follows is what
changes, by what you did.

### Removing the package

`apt remove noust` and `dnf remove noust` (the last copy) stop and disable `noust-web` and
`noust-monitor` and stop a console started with `noust web start -d`. They touch nothing else:
the configuration, the store, the logs, the backups and `/var/www/apps` stay where they are.
`pip uninstall noust` removes the program and nothing more, so run `noust web disable` and
`noust monitor uninstall` first if you enabled either, or their units are left pointing at a program
that is gone.

**Keeps working**

- Every application, its unit, its site and its certificate; restarts and reboots included.
- Certificate renewal: certbot's own timer, and the small script it runs afterwards to reload the
  web server (`/etc/letsencrypt/renewal-hooks/deploy/noust-reload`), neither of which calls Noust.
- Databases, whether on the host or in containers, and Docker Compose stacks.
- The cron jobs you made for an application: each is a timer and a unit whose command is yours.

**Stops, and starts again when Noust is back**

- The console and the API, and with them the deploy webhooks.
- Deploying, updating, rolling back, and everything else that is a Noust command.
- The monitor and its alerts.

**Keeps firing and fails** (each one runs `/usr/bin/noust`): scheduled backups of applications,
databases and volumes, Noust's own backup, storage cleanup, automatic updates and the preview sweep.
They show in `systemctl --failed`. If you are leaving for good, list the timers with
`systemctl list-timers 'noust-*'` and disable the ones that name a backup, a cleanup, an update or
previews, so a missed backup is a decision and not a surprise. The cron jobs above are not among
them.

### Purging it

`apt purge noust` also deletes `/etc/noust` (the configuration, **the secrets in it and the audit
trail**), `/var/log/noust` and the two unit files if Noust wrote them. It never touches `/var/www/apps`,
`/var/lib/noust` or `/var/backups/noust`. If you may come back, take a `noust self-backup` first
([disaster-recovery.md](/docs/guides/backups/)): it is the one file that restores the state onto a fresh install.

### Managing an application by hand afterwards

Nothing has to be converted. The unit is `systemctl status {app}`, its code is
`/var/www/apps/{app}/current` (or the directory itself for an in-place application), its
environment is `shared/.env` (or `.env` in place), and the site is the file in
`/etc/nginx/sites-enabled` or its Apache counterpart. Noust's rule for a site, if you install it
again, is its marker: a file without "Generated by Noust" is yours and is never rewritten.

Installing Noust again brings back what stopped: the scheduled timers go on by themselves, and
`noust web enable` and `noust monitor install` start the console and the monitor again.

## Where to go next

- [first-application.md](/docs/start/first-application/): a first deploy.
- [releases.md](/docs/guides/releases/): the layout, the gate, rollback and migrations.
- [security.md](/docs/guides/security/): the threat model, builds, sudo mode and the audit trail.
- [PRIVACY.md](/docs/concepts/privacy/): what leaves a server.
- [coolify.md](/docs/guides/from-coolify/), [dokploy.md](/docs/guides/from-dokploy/), [caprover.md](/docs/guides/from-caprover/) and
  [dokku.md](/docs/guides/from-dokku/): the same concepts for someone coming from each of them.
- [examples/README.md](/docs/start/examples/): a minimal application for every type, to deploy as is.