Docs / RivetMSP / Getting started
Installing RivetMSP
Docker Compose to try it, or the install script for a hardened production server, with worked examples.
There are two supported ways to get a running instance. Pick by what you are doing.
| Docker Compose | Install script | |
|---|---|---|
| Best for | Trying it, lightweight self-hosting | A real production server |
| Hardening | None. Put a real reverse proxy in front | Firewall, fail2ban, PHP and MariaDB hardening, TLS |
| Updates | git pull then docker compose up -d --build |
deploy/update.sh |
Option 1: Docker Compose#
git clone https://github.com/TheTractorHacker/RivetMSP.git
cd RivetMSP
cp .env.example .env # set DB_PASSWORD and DB_ROOT_PASSWORD, and DOCKER_UID / DOCKER_GID (run `id -u` and `id -g`)
docker compose up -d --build
Then open http://localhost:8080/ (or the APP_PORT you set in .env). It redirects straight to the browser setup wizard at /setup/. When it asks for a database host, enter db and use the credentials from your .env.
The stack runs nginx, PHP-FPM, MariaDB and Redis. The application code is bind-mounted from your checkout, so config.php, uploads/ and backups/ persist on the host.
To stand the container up from an existing encrypted backup instead of a fresh install, drop the backup file and its passphrase file under ./restore/, set RESTORE_FROM and RESTORE_PASSPHRASE_FILE in .env, then run docker compose up -d --build. The comments in .env.example explain each value.
Option 2: the install script#
The tooling in deploy/ provisions a whole box from scratch. It targets Ubuntu and Debian and must run as root.
git clone https://github.com/TheTractorHacker/RivetMSP.git
cd RivetMSP
sudo deploy/install.sh --domain=msp.example.com
What it does, in order#
- Installs nginx, MariaDB, PHP 8.4 (from the
ondrej/phpPPA if your release does not carry it), certbot, ufw, fail2ban, git and composer. Anything already present is left alone. - Copies the code into the instance's app directory (or clones it fresh) and runs
composer install --no-dev. - Creates the
uploads/tree and sets ownership and permissions:www-data, directories750, files640, widening onlyuploads/andbackups/. - Creates a database and a same-named user, bound to
localhost, with a random 32-character password and only the grants the app needs (noSUPER,FILEorGRANT OPTION). - Sets up the nginx virtual host and a certificate. In direct-TLS mode it runs certbot; with
--proxy-modeor--skip-tlsit keeps a self-signed certificate. - Applies PHP-FPM and MariaDB hardening, validating each change and rolling back automatically if the config test fails.
- Allows SSH (the port is detected) and HTTP/HTTPS through ufw before enabling it, then installs fail2ban jails.
- Installs a system cron entry that runs
cron/cron.phpevery five minutes. It does nothing until you enable cron in the app. - Runs
scripts/setup_cli.phpto writeconfig.php, import the schema and create the first admin. Ifconfig.phpalready exists this step is skipped, so re-running the script is safe.
Flags worth knowing#
--domain=<fqdn>is required.--proxy-modeis for a box behind an external reverse proxy that already terminates public TLS. It skips certbot and serves a self-signed backend certificate on port 8443.--skip-tlsis for when there is no public DNS yet.--non-interactivefails instead of prompting for anything missing.--restore-fromand--restore-passphrase-filebuild the new box from an existing backup.--default-vhostmarks the instance that answers requests addressed to the server's IP. Only one vhost per nginx port can be the default.
Avoid --admin-password on an interactive terminal. It stays out of ps, but it lands in your shell history. Leave it out and answer the prompt instead.
Run sudo deploy/install.sh --help for the full list.
Example: a fresh dedicated server#
sudo deploy/install.sh \
--domain=msp.example.com \
[email protected] \
--company-name="Example Co" --country="United States" \
--locale=en_US --timezone=America/New_York --currency=USD
You are prompted for the admin's name, email and password. The result is a working instance at https://msp.example.com/ with a real Let's Encrypt certificate.
Example: a second company on the same server#
Every company gets its own app directory, database, database user and nginx virtual host. Run the script again with a different domain and database name:
sudo deploy/install.sh \
--domain=msp2.example.com \
--db-name=msp2 \
[email protected] \
--company-name="Second Co" --country="United States" \
--locale=en_US --timezone=America/New_York --currency=USD
Nginx, PHP-FPM and MariaDB are detected and not reinstalled. The firewall, fail2ban and the shared rate-limit zone are reused.
Example: a new server from a backup#
sudo deploy/install.sh \
--domain=msp.example.com \
[email protected] \
--restore-from=/root/backup-msp-20260101T023000Z.tar.gz.enc \
--restore-passphrase-file=/etc/itflow/backup-passphrase
In this mode the company and admin flags are ignored. Packages, TLS, hardening, firewall and cron are provisioned as usual, then the restore overwrites the database and uploads with the backup's contents. See Backups and disaster recovery.
After installing#
Run sudo deploy/harden.sh once (see Hardening and security checklist), enable cron in the app, turn on two-factor sign-in for your admin, and set up backups.