Skip to main content
Mangrove runs on a Debian or Ubuntu box with Docker and Caddy. The installer sets everything up; you can also do it by hand.

​
Requirements

  • A Linux box you don’t use for anything else. 2 GB of RAM is enough for Mangrove plus a few small apps. Mangrove needs Docker access, which is equivalent to root, so don’t share the box with unrelated services.
  • Docker with the Compose plugin.
  • Caddy, with its admin API on 127.0.0.1:2019 (Caddy’s default).
  • Go 1.25+ and Node 20+ to build Mangrove from source.
  • nixpacks on the PATH, only if you want the nixpacks build strategy (see Builds). The installer doesn’t install it.

​
One command

setup.sh:
  1. Installs Docker, Caddy, Go and Node if they’re missing.
  2. Builds the dashboard and the mangrove binary.
  3. Creates the mangrove system user and its directories (/var/lib/mangrove, /var/lib/mangrove-static, /etc/mangrove).
  4. Installs the systemd units and memory slices from deploy/systemd/.
  5. Asks whether the box has a public IP or sits behind a home router, and sets up DDNS for the latter.
  6. Asks whether to install the optional storage helper (for turning a drive into a NAS).
  7. Starts the service and creates your admin account.
It prompts for the admin email and password. To run it unattended, pass them in the environment instead:
Re-running setup.sh is safe. Every step checks what’s already there. When it finishes, Mangrove is running at http://127.0.0.1:7777.

​
Claiming the instance

On a fresh install nobody has an account. The first account becomes the owner, and creating it needs a single-use setup token, so someone who reaches the dashboard before you can’t claim the box. Mangrove creates the token the first time it starts with no accounts. It logs it and saves it to the setup-token file in its data directory:
setup.sh reads the file and creates the account for you, so usually you never see it. If you start Mangrove some other way, enter the token on the dashboard’s first screen (opening /?setup_token=<token> fills it in), or pass it to mangrovectl setup --token. The token stays the same across restarts until it’s used. Creating the first account deletes it, and from then on new accounts come from an owner (see Workspaces and roles).

​
Reach the dashboard

Mangrove’s API and dashboard listen on loopback only (127.0.0.1:7777). Nothing on the network can reach them until you choose how. Two ways:
  • An SSH tunnel, for a quick look or a private box:
    Then open http://localhost:7777 on your own machine.
  • A domain with HTTPS, for everyday use: add a site to Caddy (or your host’s edge) that reverse-proxies to 127.0.0.1:7777. See Going to production.

​
Try it locally

To try Mangrove on a laptop or dev box without systemd:
This starts Mangrove on http://127.0.0.1:7777, with its database and encryption key in ./data. The first visit asks you to create the first account, which becomes the owner. Paste the setup token from Mangrove’s output (also in ./data/setup-token); see Claiming the instance. Mangrove creates its own Docker network (mangrove-net) the first time it needs it.

​
After installing

  • Put the dashboard behind HTTPS (see above).
  • Set up backups. Losing the data directory’s master.key makes every stored secret unrecoverable.
  • Deploy something.

​
If the install fails

  • apt-get not found: the installer only supports Debian and Ubuntu. On another distro, install Docker, Caddy, Go and Node yourself, then follow Going to production by hand.
  • The service starts but the dashboard is blank: the dashboard wasn’t built before the binary. Run cd web && npm run build, rebuild the binary, and restart. See Upgrades.
  • Port 7777 is taken: set MANGROVE_PORT in /etc/mangrove/mangrove.env and restart. See Configuration.
More in Troubleshooting.