# Installing RivetMSP

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

```bash
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.

```bash
git clone https://github.com/TheTractorHacker/RivetMSP.git
cd RivetMSP
sudo deploy/install.sh --domain=msp.example.com
```

### What it does, in order

1. Installs nginx, MariaDB, PHP 8.4 (from the `ondrej/php` PPA if your release does not carry it), certbot, ufw, fail2ban, git and composer. Anything already present is left alone.
2. Copies the code into the instance's app directory (or clones it fresh) and runs `composer install --no-dev`.
3. Creates the `uploads/` tree and sets ownership and permissions: `www-data`, directories `750`, files `640`, widening only `uploads/` and `backups/`.
4. Creates a database and a same-named user, bound to `localhost`, with a random 32-character password and only the grants the app needs (no `SUPER`, `FILE` or `GRANT OPTION`).
5. Sets up the nginx virtual host and a certificate. In direct-TLS mode it runs certbot; with `--proxy-mode` or `--skip-tls` it keeps a self-signed certificate.
6. Applies PHP-FPM and MariaDB hardening, validating each change and rolling back automatically if the config test fails.
7. Allows SSH (the port is detected) and HTTP/HTTPS through ufw before enabling it, then installs fail2ban jails.
8. Installs a system cron entry that runs `cron/cron.php` every five minutes. It does nothing until you enable cron in the app.
9. Runs `scripts/setup_cli.php` to write `config.php`, import the schema and create the first admin. If `config.php` already exists this step is skipped, so re-running the script is safe.

### Flags worth knowing

- `--domain=<fqdn>` is required.
- `--proxy-mode` is 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-tls` is for when there is no public DNS yet.
- `--non-interactive` fails instead of prompting for anything missing.
- `--restore-from` and `--restore-passphrase-file` build the new box from an existing backup.
- `--default-vhost` marks 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

```bash
sudo deploy/install.sh \
  --domain=msp.example.com \
  --email=admin@example.com \
  --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:

```bash
sudo deploy/install.sh \
  --domain=msp2.example.com \
  --db-name=msp2 \
  --email=admin@example.com \
  --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

```bash
sudo deploy/install.sh \
  --domain=msp.example.com \
  --email=admin@example.com \
  --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](/docs/msp/backups-and-disaster-recovery).

## After installing

Run `sudo deploy/harden.sh` once (see [Hardening and security checklist](/docs/msp/hardening-and-security)), enable cron in the app, turn on two-factor sign-in for your admin, and set up backups.
