Documentation

Deployment Guides

QueryGlow runs in Docker and keeps its own state in JSON files. ./queryglow install (it runs deploy.sh) sets up nginx, the HTTPS certificate, the login and the app on a server that already has Docker with the compose plugin, or plugs into the nginx you already run; ./queryglow update keeps it current with a backup and automatic rollback.

Minimum Requirements

  • RAM: 512 MB minimum (1 GB recommended)
  • Disk: 10 GB free
  • OS: Ubuntu 20.04+, Debian 11+ or similar Linux, with Docker and the compose plugin
  • User: a regular user with sudo (the installer refuses to run as root)
  • Tools: dig, curl, openssl, htpasswd (the installer offers to install them on Debian and Ubuntu)
  • Ports: 80 and 443 open for the SSL certificate and HTTPS
  • Domain: DNS A record pointing to your server IP

🔥 Firewall Setup

Open the required ports before running ./queryglow install:

sudo ufw allow 22/tcp   # SSH (don't lock yourself out!)
sudo ufw allow 80/tcp   # HTTP (Let's Encrypt verification)
sudo ufw allow 443/tcp  # HTTPS (QueryGlow)
sudo ufw enable

⚠️ Never open database ports (5432, 3306) to the internet. QueryGlow connects to databases internally or through its SSH tunnel.

Auto-Detected Deployment Modes

The installer detects your server setup and picks the mode itself:

  • Standalone mode: a server with no nginx running. Docker runs nginx, certbot and the app.
  • Integration mode: a system nginx is already running. Only the app container runs; the installer adds a site to your nginx and gets the certificate with the system certbot. It needs the Debian/Ubuntu sites-available layout and an installed certbot.

After install: the queryglow command

Everything you do on the host after the first install goes through one command in your checkout. It needs bash, git, Docker with the compose plugin and curl, no Node.js.

CommandWhat it does
./queryglow installFirst install or a re-run: runs deploy.sh and records the install
./queryglow updateBack up, fetch the newest release, rebuild, verify, roll back on failure
./queryglow update --checkOnly asks whether a newer release is available (exit code 10 when it is)
./queryglow update --tag v1.3.0Update or downgrade to one release
./queryglow statusWhat is installed and running, last backup and last update
./queryglow doctorChecks the host and the install; --fix applies safe repairs, --report prints a support report
./queryglow backupSnapshot of .env, the app data and the nginx files to backups/<timestamp>/
./queryglow restore backups/<ts>Puts the app data from a snapshot back
./queryglow rollbackReturns to the release recorded in the newest snapshot
./queryglow logsLast 100 lines of the app container (logs -f to follow)

An update backs up to backups/<timestamp>/ first and validates the nginx config before anything restarts. It keeps the running image as queryglow:previous, checks that the new version answers, and returns to the previous release on its own if it does not. Each run leaves a receipt in .queryglow/receipts/. How updating works

What the installer configures automatically:

  • ✔ HTTPS with Let's Encrypt
  • ✔ nginx reverse proxy
  • ✔ Basic Auth login (htpasswd)
  • ✔ Safe Mode enabled by default
  • ✔ AES-256-GCM credential encryption
  • ✔ Search engine blocking
  • ✔ Security headers (X-Frame-Options, CSP, Permissions-Policy; HSTS in standalone mode)
  • ✔ A free app port (3000 by default)
  • ✔Records the install for ./queryglow update, status and doctor