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

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.

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, declarative.md (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, security.md.

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.

Detail: the README's "What Noust is, and is not", and security.md.

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): 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: a first deploy.
• releases.md: the layout, the gate, rollback and migrations.
• security.md: the threat model, builds, sudo mode and the audit trail.
• PRIVACY.md: what leaves a server.
• coolify.md, dokploy.md, caprover.md and dokku.md: the same concepts for someone coming from each of them.
• examples/README.md: a minimal application for every type, to deploy as is.