Install launchroom
One command on a Linux server with Docker. launchroom is Docker containers and one folder, and nothing is written outside that folder unless you agree to it.
launchroom installs with one command on any Linux server that runs Docker. After a few minutes:
- the dashboard runs on its own HTTPS address,
- the server can build and run your apps,
- you create the owner account in the browser.
Every install follows two rules:
- It's Docker containers and a folder. Everything launchroom needs lives in one folder,
./launchroomby default. - Nothing is written outside the folder without asking. The installer creates no systemd units and never edits
Docker's
daemon.json. Outside the folder, launchroom only creates Docker objects (containers, images, volumes, networks) labelledlaunchroom.managed=true. There are four exceptions, and the installer asks before each:- installing Docker, when it's missing
- raising the kernel's inotify limits in
/etc/sysctl.d/60-launchroom-inotify.conf, when they are too low - loading the AppArmor profile
/etc/apparmor.d/launchroom-buildkit, on Ubuntu 23.10 and later, so builds can run - creating a 2 GB swap file on servers with less than 4 GB of RAM and no swap
Requirements
| What | Needed |
|---|---|
| Operating system | Linux, x86_64 or arm64. Debian and Ubuntu are first-class; any distribution with a recent Docker Engine should work. |
| Docker | Docker Engine 24 or newer with the compose plugin. Docker installed from snap is not supported. The installer can install it for you. |
| User | root, or a user in the docker group. |
| Memory | 2 vCPU and 2 GB RAM for the control plane, small apps and builds on the same server. 1 GB works when builds run on a separate build server. |
| Ports | 80 and 443 (TCP) free and reachable from the internet, plus 443/UDP for HTTP/3. UDP 3478 helps other servers connect directly once you add them. |
| Kernel | inotify limits of at least 65,536 watches (fs.inotify.max_user_watches) and 256 instances (fs.inotify.max_user_instances). The installer can raise them for you. On Ubuntu 23.10 and later, builds need launchroom's AppArmor profile; the installer can load it for you. |
| Outbound | HTTPS to GitHub (the release bundle) and to the container registries the images come from. |
If the server has less than 2 GB of RAM, the installer warns and continues.
Docker
If Docker is missing, the installer asks:
launchroom: Docker is not installed. Install it now with Docker's official script (get.docker.com)? [Y/n]Enter or y runs Docker's official script (get.docker.com), which adds Docker Engine and the
compose plugin from Docker's package repository. n stops with a link to Docker's install instructions.
The question is asked on the terminal, so it works with curl … | sh. Without a terminal (cloud-init, CI, other
automation), the installer stops instead, unless you pass --install-docker. --no-install-docker never installs
Docker.
inotify limits
Containers and file watchers fail with "too many open files" when the kernel's inotify limits are low. Stock Ubuntu allows 128 instances. If a limit is below the minimum, the installer asks:
launchroom: This server's inotify limits are low (max_user_watches 8192, max_user_instances 128). Raise them to max_user_watches 524288, max_user_instances 512 now? [Y/n]Enter or y writes /etc/sysctl.d/60-launchroom-inotify.conf and applies the new values right away with sysctl -w.
The file contains only the limits that were lower than the new
values, so a higher value you set yourself stays as it is. n keeps the limits and prints the commands to raise them
later.
Without a terminal, nothing changes unless you pass --raise-inotify; the installer prints the commands instead. When
it doesn't run as root, it prints the same commands with sudo.
To undo it, delete the file and reboot. The file names the earlier values, if you want them back without a reboot:
sudo rm /etc/sysctl.d/60-launchroom-inotify.conf
sudo rebootSwap on small servers
On Linux servers with less than 4 GB of RAM and no swap, the installer offers a 2 GB /swapfile-launchroom. Swap gives memory-intensive builds room to slow down while build limits protect your dashboard and apps. It needs at least 3 GB free on the root filesystem.
Accepting creates the file with mode 0600, adds its entry to /etc/fstab, and sets vm.swappiness=10 in /etc/sysctl.d/60-launchroom-swap.conf. Declining prints the commands for later. Without a terminal, pass --create-swap or set LR_CREATE_SWAP=1; without root, the installer prints commands using sudo. Existing swap stays unchanged, and updates never create swap automatically.
Re-run the installer to add swap to an existing server. Uninstall keeps it; to remove it, run sudo swapoff /swapfile-launchroom, delete the file and its /etc/fstab entry, and remove /etc/sysctl.d/60-launchroom-swap.conf.
User namespaces for builds
launchroom builds with rootless BuildKit, which creates a user namespace. Ubuntu 23.10 and later restrict user
namespaces through AppArmor (kernel.apparmor_restrict_unprivileged_userns=1), so BuildKit can't start there. The
installer doesn't turn that restriction off. It asks to load one AppArmor profile that allows user namespaces for
launchroom's build container only:
launchroom: This server restricts user namespaces (Ubuntu 23.10 and later), and builds need one. Allow it for launchroom's build container only (AppArmor profile /etc/apparmor.d/launchroom-buildkit)? [Y/n]Enter or y writes /etc/apparmor.d/launchroom-buildkit and loads it with apparmor_parser. AppArmor loads it again
after every reboot. The profile is attached to no program: only the container launchroom starts with
apparmor=launchroom-buildkit uses it, and the restriction stays on for everything else on the server. n prints the
commands, and builds on this server fail until you run them.
The question only comes up when the restriction is on. Without a terminal, pass --allow-buildkit-userns (or set
LR_BUILDKIT_APPARMOR=1). Updates from the dashboard don't change the host, so a server installed before this step
existed gets the profile when you run the installer again, or with the commands in
Build problems.
To remove it:
sudo apparmor_parser -R /etc/apparmor.d/launchroom-buildkit
sudo rm /etc/apparmor.d/launchroom-buildkitRun the installer
curl -fsSL https://launchroom.vantezzen.io/install | shThe folder is created where you run the command. Run it in the directory you want launchroom/ to live in, for
example your home directory.
Your own domain or the automatic address
Without options, the dashboard gets an automatic address built from the server's public IP:
https://203-0-113-10.sslip.io for a server at 203.0.113.10. It has a real certificate and needs no DNS.
If you already have a name for the dashboard, pass it with --domain and point an A (or AAAA) record at the server
first:
curl -fsSL https://launchroom.vantezzen.io/install | sh -s -- --domain dash.example.comUse a stable name if you have one. If the server has to be rebuilt from a backup, you only change DNS and every other server reconnects by itself. You can also move the dashboard to a domain later, from the dashboard, without reinstalling. See Dashboard domain.
What the installer does
Checks the server
It checks for:
- Linux
- Docker Engine 24 or newer, not from snap (offers to install it when it's missing)
- the compose plugin
- at least 2 GB of RAM (warning only)
- ports 80 and 443 are free
- the kernel's inotify limits (offers to raise them when they are low)
- whether AppArmor restricts user namespaces (offers to load launchroom's build profile)
Downloads and verifies the release
It downloads the release bundle (compose file, helper script, image pins), checks its checksum and verifies its signature against the launchroom release on GitHub. A bundle whose signature does not verify is never installed.
Creates the folder and its secrets
It creates launchroom/ with compose.yml, .env (mode 0600) and data/, and generates:
- the application key
- database and cache passwords
- the key that encrypts your stored secrets
- the signing key servers trust
Starts the control plane
Postgres and Valkey start first, then the dashboard (which runs its database migrations on first start), background workers, realtime server, scheduler, image registry and private network coordinator.
Connects this server
The installer starts launchroomd on this server and connects it to the dashboard with the roles Run apps,
Serve traffic and Build. From here on this server serves the dashboard over HTTPS too.
Prints your links
It prints the dashboard address, a one-time setup link valid for 60 minutes and a reminder to back up two things.
Back up .env and data/keys/
launchroom/.env and launchroom/data/keys/ decrypt every secret launchroom stores. Copy them somewhere safe right
after the install. Setting up backups in the dashboard also produces a recovery kit that covers them.
Create the owner account
Open the setup link the installer printed (https://<your dashboard>/setup?token=…). The first-run screen confirms the
install and asks for your name, email and a password. This account becomes the instance owner.


If the setup link expired, run ./launchroom setup-token in the install folder for a new one.
After sign-in, Get started guides you through the remaining steps:
- Connect GitHub.
- Set an address for your apps.
- Deploy the first app.
- Set up backups.
Get started also recommends two-factor authentication. It is optional.
The install folder
launchroom/
├── compose.yml managed: replaced on upgrade (do not edit)
├── compose.override.yml yours: optional overrides (ports, resource limits)
├── .env generated secrets, settings and image pins (0600)
├── launchroom helper script
├── guard/ the pinned release identity for updates
└── data/
├── keys/ encryption and signing keys
├── postgres/ valkey/ control-plane state
├── zot/ the image registry's config and storage
├── headscale/ the private network's coordination state
├── daemon/ launchroomd's identity, last desired state, cached proxy config
└── backups/ control-plane backups to a local destinationPut local changes to the stack in compose.override.yml. compose.yml is replaced on every upgrade.
The ./launchroom helper
Run these from inside the install folder.
| Command | What it does |
|---|---|
./launchroom status | The dashboard address, every container's state and whether this server's launchroomd is connected. |
./launchroom logs [service] | Follow the logs of all services, or one (dashboard, horizon, launchroomd, …). |
./launchroom update | Pull the images pinned in .env again, restart and migrate. A new release comes from re-running the installer. |
./launchroom backup | Take a control-plane backup now. |
./launchroom restore | Restore the control plane from a backup. |
./launchroom registry show / apply | Show the registry config with credentials hidden, or write it and restart the registry. |
./launchroom setup-token | A new one-time setup link. |
./launchroom reset-owner-2fa EMAIL | Remove an instance owner's two-factor authentication after a typed confirmation. They set it up again at the next sign-in. |
./launchroom dashboard-domain-reset | Go back to the install address when the dashboard's own domain locks you out. |
./launchroom uninstall | Remove launchroom from this server. |
Installer options
| Option | What it does |
|---|---|
--dir DIR | Install folder. Default: $LAUNCHROOM_DIR, else ./launchroom. |
--domain HOST | Dashboard host name. Default: <public-ip>.sslip.io. |
--version V | Release to install. Default: the latest. |
--unstable | Install the newest release, including pre-releases, and offer pre-releases as updates (the beta channel). Re-running the installer without it keeps the channel. |
--bundle DIR | Use an unpacked bundle instead of downloading one. Not signature-verified: for air-gapped installs and testing. |
--no-public-ip-detect | Never contact IP echo services, neither the installer nor launchroomd (LR_PUBLIC_IP_DETECT=off in .env). Needs --domain. Set LR_PUBLIC_IPS=203.0.113.10 (IPv4 and IPv6, comma-separated) in .env so the DNS instructions in the dashboard name the right address, then run docker compose up -d in the folder. |
--install-docker | When Docker is missing, install it with Docker's official script without asking. For installs without a terminal. Also LR_INSTALL_DOCKER=1. |
--no-install-docker | Never install Docker: stop with instructions when it's missing. Also LR_NO_INSTALL_DOCKER=1. |
--raise-inotify | Raise low inotify limits without asking. For installs without a terminal. Also LR_RAISE_INOTIFY=1. |
--allow-buildkit-userns | On hosts that restrict user namespaces, load launchroom's AppArmor profile for builds without asking. Also LR_BUILDKIT_APPARMOR=1. |
--skip-port-check | Install even though 80 or 443 are taken. The dashboard is then only reachable on 127.0.0.1:8000, for example through an SSH tunnel. |
--allow-unsigned | Accept a downloaded bundle without a signature (development builds only). A signature that is present but does not verify is always refused. |
--restore | Rebuild the control plane from a backup. See Restore and disaster recovery. |
--recovery-kit FILE | The recovery kit for --restore (implies --restore). |
--restore-allow-http | Accept a plain-HTTP backup endpoint for --restore (LAN or test storage only). |
Pass options after sh -s --, for example curl -fsSL https://launchroom.vantezzen.io/install | sh -s -- --dir /srv/launchroom.
Upgrading is re-running the installer
Running the same command again is safe. It is how you move to a new release:
.envand everything indata/are kept.compose.yml, the helper script and the image pins are replaced.- The stack is brought up to date, and this server's launchroomd stays connected.
Run it from the same directory, or pass --dir to point at the existing folder.
You can also update from the dashboard. Settings → Updates takes a backup, updates the control plane and then every server, and rolls back if the new version doesn't come up. See Updates.
Uninstall
./launchroom uninstallThe command asks twice:
- Type
uninstallto stop the stack, remove launchroomd's firewall rules and remove every container and network labelledlaunchroom.managed=true, including your deployed apps, Caddy and BuildKit. - Type
deleteto also remove the labelled volumes (your databases and app data), the images those containers used and the folder. Skip this step and your data stays on disk.
If the installer raised the inotify limits, they stay: removing the file doesn't lower the running values, and other software on the server may rely on them by now. The uninstall reminds you of the file. To undo it, see inotify limits.
The AppArmor profile for builds stays too: the uninstall doesn't run as root, and without launchroom's build container nothing uses the profile. The uninstall prints the commands to remove it, see User namespaces for builds.
Other servers you added have their own small install folder. See Uninstalling a server.