Skip to content

Docs / RivetIT / Deploying & administering

Deployment (Docker or bare metal)

Choose between the two supported install paths, and how backup, disaster recovery and updates work end to end.

This document is the narrative overview of how to get a RivetIT instance running, how to choose between the two supported paths, and how backup/restore actually works end to end. It complements two more detailed references rather than replacing them:

  • deploy/README.md — the full flag-by-flag reference for every script under deploy/ (full-restore-deploy.sh, install.sh, harden.sh, backup.sh, restore.sh, restore_admin_zip.sh, update.sh).
  • .env.example — every Docker Compose environment variable, with inline comments.

See ARCHITECTURE.md for how the codebase itself is organized, and ISO27001-COMPLIANCE.md for a control-by-control mapping of what this deployment tooling covers from a security standpoint.

1. Two paths — which one do you want?#

Docker Compose Bare-metal (deploy/install.sh)
Best for Trying it out, a lightweight self-hosted deployment, a homelab A production instance you're running long-term
What it sets up nginx + PHP-FPM + MariaDB + Redis in containers nginx, PHP 8.5, MariaDB, Redis, TLS, and OS-level hardening directly on the box
TLS None — put a reverse proxy in front Built in (Let's Encrypt via certbot, or your own reverse proxy with --proxy-mode)
Hardening None (a container has no fail2ban/ufw/unattended-upgrades equivalent) fail2ban, ufw, PHP-FPM/MariaDB hardening drop-ins, unattended security upgrades
Update path git pull + docker compose up -d --build deploy/update.sh (pulls code, runs pending DB migrations)
Multi-company on one box Not designed for it Yes — re-run install.sh with a different --domain/--db-name

If you're not sure, start with Docker Compose to evaluate the app, then move to deploy/install.sh for anything you intend to keep running and trust with real data.

2. Docker Compose#

git clone https://github.com/TheTractorHacker/RivetIT.git
cd RivetIT
cp .env.example .env
# edit DB_PASSWORD / DB_ROOT_PASSWORD, and DOCKER_UID / DOCKER_GID (run `id -u` / `id -g`)
docker compose up -d --build

Visit http://localhost:8080/ (or whatever APP_PORT you set) — it redirects to the browser-based /setup/ wizard, the same one a manual/bare-metal install would use. Enter database host db and the credentials from your .env.

Architecture, briefly: the app container runs nginx + PHP-FPM + a Redis instance (for live ticket/chat updates) + a cron/cron.php loop, all under supervisord. Application code is bind-mounted from your checkout (.:/var/www/html), not baked into the image — this keeps config.php, uploads/, backups/, and vendor/ on the host, persisting across docker compose down and image rebuilds, and makes git pull the update path (matching deploy/update.sh's model on bare metal, just without the wrapper script). DOCKER_UID/DOCKER_GID in .env remap the container's www-data to your host user so it can actually write into that bind-mounted checkout.

Names. The containers are rivetit-web and rivetit-db and the built image is tagged rivetit-web:local. To run a second stack on the same host, set RIVETIT_CONTAINER_PREFIX in that stack's .env; it prefixes both container names and the image tag, so the stacks neither collide nor overwrite each other's image. The compose service keys (app, db) and the itflow_db_data volume keep the names they had before the RivetIT rename, so an existing stack comes back up on its existing database. Upgrading such a stack: git pull then docker compose up -d --build; Compose recreates both containers under the new names and reattaches the same volume. docker-compose.yml's own DB_NAME/DB_USER fallback (used only when .env sets neither) stays itflow for the same reason — a stack that never set them explicitly really does have a database named itflow inside that volume. .env.example's suggested values for a new install are rivetit; copy it to .env and set your own before the first docker compose up. A host that already runs two or more stacks must give every stack but one its own RIVETIT_CONTAINER_PREFIX before that docker compose up: before the rename Compose named containers per project, and now the second stack would stop with "container name /rivetit-db is already in use". Use docker compose exec app … / docker compose exec db … (service names) in your own scripts rather than container names.

No TLS termination and no hardening are built into the container — this is intentional, to keep the image simple and portable. Put a real reverse proxy (Traefik, Caddy, nginx-proxy, a cloud load balancer) in front for anything beyond local evaluation.

Restoring a backup instead of a fresh install#

If you already have a deploy/backup.sh backup (see §4 below) and want this container to come up with that data instead of an empty instance:

  1. Drop the backup file and its passphrase file under ./restore/ (already bind-mounted read-only into the container at /var/www/restore).
  2. Set RESTORE_FROM and RESTORE_PASSPHRASE_FILE in .env to their in-container paths.
  3. docker compose up -d --build.

The entrypoint writes config.php and hands off to deploy/restore.sh automatically on first boot; a container that already finished setup (fresh or restored) skips this and starts normally. If a restore attempt fails partway (e.g. a permissions problem with the passphrase file), it's safe to fix the issue and just restart the container — it retries rather than getting stuck, because it checks whether setup actually completed, not merely whether config.php exists.

Once the restore succeeds, delete the backup and passphrase from ./restore/ and remove RESTORE_FROM/RESTORE_PASSPHRASE_FILE from .env. ./restore/ sits inside the same checkout nginx serves; docker/nginx.conf denies /restore/ and every dotfile (including .env), but a decryption passphrase shouldn't outlive the one restore it was needed for.

3. Bare-metal (deploy/install.sh)#

git clone https://github.com/TheTractorHacker/RivetIT.git
cd RivetIT
sudo deploy/install.sh --domain=rivetit.example.com

This provisions the whole box — packages, database, TLS/vhost, PHP-FPM/MariaDB hardening, ufw, fail2ban, a cron entry — then runs the app's own first-run setup. See deploy/README.md for the full flag reference, worked examples (including adding a second company's instance to a box that already runs one), and the hardening/backup/update tooling that ships alongside it.

Don't already know which flags you want? Run sudo deploy/full-restore-deploy.sh --domain=rivetit.example.com instead — it asks about restoring from a backup, the database name, an SSL certificate, and the extra harden.sh pass below, then calls install.sh with the answers.

Restoring onto a brand-new box instead of a fresh company setup is a single extra pair of flags:

sudo deploy/install.sh --domain=rivetit.example.com \
    --restore-from=/path/to/backup-itflow-<timestamp>.tar.gz.enc \
    --restore-passphrase-file=/etc/itflow/backup-passphrase

This is the disaster-recovery path: box died, stand up a new one, get your data back. It skips every company/localization/admin-user prompt — the restored data already has all of that — and provisions the box exactly as a fresh install would otherwise. --restore-from also accepts an in-app itflow_<timestamp>_*.zip here (no --restore-passphrase-file needed for that format) — see §4.1 below.

4. Backup & disaster recovery#

Two independent backup systems exist. Knowing which one you're restoring matters — they use different formats and different restore tools.

4.1 In-app backup (quick snapshots)#

Reachable from inside the app at Settings → Backup, this produces a plain (unencrypted) zip containing db.sql + uploads.zip + version.txt. It runs two ways:

  • On demand ("Download Backup" / "Save to Server").
  • Automatically, once an hour, if enabled — and optionally pushed to S3-compatible remote storage (also configured under Settings → Backup).

Restore it from the browser or the command line: the /setup wizard has a "Restore from Backup" step (reachable from the Welcome screen, or the ?restore Utilities link) that accepts exactly this zip format; deploy/restore_admin_zip.sh restores the same zip from an SSH session instead, with a master-key fallback (--admin-user) for when the backup passphrase is lost — something the browser wizard has no equivalent for at all (see deploy/README.md). Useful for "undo my last change" or moving a quick snapshot between instances — the zip bytes themselves aren't encrypted, so it's not on its own the tool for genuine disaster recovery; pair it with a backup passphrase (Settings → Backup) if that matters for your threat model.

4.2 deploy/backup.sh (the actual DR mechanism)#

Scheduled via a systemd timer, root-only, and encrypted — this is what the deployment tooling considers the real disaster-recovery backup. It produces one file, backup-<database>-<timestamp>.tar.gz.enc, containing the SQL dump, the full uploads/ tree, and a small backup-manifest.json (see below), all encrypted together with openssl. See deploy/README.md for setting up the passphrase file and the scheduled timer.

Restoring it is deploy/restore.sh (a command-line tool, not the browser wizard — the /setup ?restore form does not accept this format):

sudo deploy/restore.sh --app-dir=/var/www/rivetit.example.com \
    --backup=/path/to/backup-itflow-<timestamp>.tar.gz.enc \
    --passphrase-file=/etc/itflow/backup-passphrase \
    --confirm-restore

--confirm-restore is mandatory — there is no interactive prompt to click through, since this replaces every table in the target database and everything under uploads/. By default it takes a fresh safety backup of the target's current state first and aborts before touching anything if that fails.

Why the settings key matters: config_settings_enc_key — the key that decrypts every stored SMTP/IMAP password, RMM/UniFi API key, webhook secret, and the wrapped credential-vault master key — lives only in config.php, which is deliberately never included in the backup itself. The key must also not travel in the same file as the data it unlocks, so backup.sh writes it to a separate backup-<db>-<timestamp>.settings-key file (mode 0600) next to the archive; the archive's backup-manifest.json holds only a fingerprint of it. Move that file off the server. restore.sh finds the file next to the archive (or takes --settings-key-file), checks it against the fingerprint and applies it to the new instance's config.php after import. Archives made before this change still hold the key in their manifest and restore as before. The in-app zip refuses to build without a backup passphrase (16+ characters) and keeps the key only inside its passphrase-encrypted manifest. Archives are now encrypted with 600000 PBKDF2 iterations; restore.sh falls back to the old default for older archives.

Standing up a brand-new server from a backup in one step: see §3 above (install.sh --restore-from, which also accepts an in-app .zip — see §4.1) or §2 (Docker's RESTORE_FROM, which for now only accepts this encrypted format and calls restore.sh internally after provisioning).

Testing a restore without touching a real instance: point --app-dir at a disposable one — either a throwaway install.sh run with --skip-tls --skip-firewall --skip-fail2ban, or just scripts/setup_cli.php --config-only against a scratch database — then inspect it and throw it away. restore.sh never creates an instance from nothing; the target must already have a config.php.

5. Updating#

  • Docker Compose: git pull then docker compose up -d --build.
  • Bare-metal: sudo deploy/update.sh — pulls code and runs any pending database migrations. Always take a fresh backup (or confirm the scheduled timer ran recently) before updating a production instance.
This page is rendered from docs/DEPLOYMENT.md in the RivetIT repository. View or edit on GitHub