launchroom
Getting started

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, ./launchroom by 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) labelled launchroom.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

WhatNeeded
Operating systemLinux, x86_64 or arm64. Debian and Ubuntu are first-class; any distribution with a recent Docker Engine should work.
DockerDocker Engine 24 or newer with the compose plugin. Docker installed from snap is not supported. The installer can install it for you.
Userroot, or a user in the docker group.
Memory2 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.
Ports80 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.
Kernelinotify 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.
OutboundHTTPS 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:

On the server
sudo rm /etc/sysctl.d/60-launchroom-inotify.conf
sudo reboot

Swap 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:

On the server
sudo apparmor_parser -R /etc/apparmor.d/launchroom-buildkit
sudo rm /etc/apparmor.d/launchroom-buildkit

Run the installer

On the server
curl -fsSL https://launchroom.vantezzen.io/install | sh

The 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:

On the server
curl -fsSL https://launchroom.vantezzen.io/install | sh -s -- --domain dash.example.com

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

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.

First-run screen: 'Your launchroom is installed' on fra-1, Hetzner Cloud, with a server illustration, beside a Create the owner account form.First-run screen: 'Your launchroom is installed' on fra-1, Hetzner Cloud, with a server illustration, beside a Create the owner account form.
Install, open the address, create the owner account.

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:

  1. Connect GitHub.
  2. Set an address for your apps.
  3. Deploy the first app.
  4. 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 destination

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

CommandWhat it does
./launchroom statusThe 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 updatePull the images pinned in .env again, restart and migrate. A new release comes from re-running the installer.
./launchroom backupTake a control-plane backup now.
./launchroom restoreRestore the control plane from a backup.
./launchroom registry show / applyShow the registry config with credentials hidden, or write it and restart the registry.
./launchroom setup-tokenA new one-time setup link.
./launchroom reset-owner-2fa EMAILRemove an instance owner's two-factor authentication after a typed confirmation. They set it up again at the next sign-in.
./launchroom dashboard-domain-resetGo back to the install address when the dashboard's own domain locks you out.
./launchroom uninstallRemove launchroom from this server.

Installer options

OptionWhat it does
--dir DIRInstall folder. Default: $LAUNCHROOM_DIR, else ./launchroom.
--domain HOSTDashboard host name. Default: <public-ip>.sslip.io.
--version VRelease to install. Default: the latest.
--unstableInstall 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 DIRUse an unpacked bundle instead of downloading one. Not signature-verified: for air-gapped installs and testing.
--no-public-ip-detectNever 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-dockerWhen Docker is missing, install it with Docker's official script without asking. For installs without a terminal. Also LR_INSTALL_DOCKER=1.
--no-install-dockerNever install Docker: stop with instructions when it's missing. Also LR_NO_INSTALL_DOCKER=1.
--raise-inotifyRaise low inotify limits without asking. For installs without a terminal. Also LR_RAISE_INOTIFY=1.
--allow-buildkit-usernsOn hosts that restrict user namespaces, load launchroom's AppArmor profile for builds without asking. Also LR_BUILDKIT_APPARMOR=1.
--skip-port-checkInstall 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-unsignedAccept a downloaded bundle without a signature (development builds only). A signature that is present but does not verify is always refused.
--restoreRebuild the control plane from a backup. See Restore and disaster recovery.
--recovery-kit FILEThe recovery kit for --restore (implies --restore).
--restore-allow-httpAccept 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:

  • .env and everything in data/ 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

In the install folder
./launchroom uninstall

The command asks twice:

  1. Type uninstall to stop the stack, remove launchroomd's firewall rules and remove every container and network labelled launchroom.managed=true, including your deployed apps, Caddy and BuildKit.
  2. Type delete to 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.

Next steps

On this page