Documentation

Quick Start

This guide covers a production install on your own server with HTTPS and a login, your first database connection, and how to keep QueryGlow current.

Prerequisites

Before you install, make sure you have:

A Linux server with Docker

Ubuntu 20.04+, Debian 11+ or similar. 512 MB RAM minimum, 1 GB recommended, 10 GB free disk. Docker with the compose plugin, and your user in the docker group.

A regular user with sudo, not root

The installer refuses to run as root, so log in to the server as a normal user with sudo rights.

A domain pointing at the server

A DNS A record, for example db.yourcompany.com → your server IP. It is needed for the HTTPS certificate.

Ports 80 and 443 open

Required for the Let's Encrypt certificate and HTTPS.

dig, curl, openssl and htpasswd

The installer checks for these tools. On Debian and Ubuntu it offers to install missing ones with apt-get; on other distributions install them yourself.

Access to the private GitHub repository

After purchase you get an invite to the repository for the GitHub username you entered at checkout. Accept it, then clone with your GitHub account over SSH or HTTPS.

Don't have Docker yet?

Install it first: curl -fsSL https://get.docker.com | sh

Then add your user to the docker group and log out and back in: sudo usermod -aG docker $USER

Need more detail on the server setup? See the Docker deployment guide

1. Clone the Repository

Accept the GitHub invite sent after purchase, then clone on the server:

git clone [email protected]:mxfschr/queryglow.git
cd queryglow

Why SSH ([email protected]) instead of HTTPS?

GitHub disabled password authentication in 2021. If you try HTTPS, you'll be prompted for a password, but your actual GitHub password will NOT work. SSH keys are the simplest solution.

❌ Getting "Permission denied (publickey)" error?

This means your SSH key isn't set up with GitHub. Here's how to fix it:

  1. Check if you have an SSH key:ls -la ~/.ssh/id_*.pub
  2. If no key exists, create one:ssh-keygen -t ed25519 -C "[email protected]"
  3. Copy your public key:cat ~/.ssh/id_ed25519.pub
  4. Add to GitHub: Go to github.com/settings/keys → New SSH key → Paste your key
  5. Test the connection:ssh -T [email protected]
🔐 Corporate network blocking SSH? Use HTTPS with a token

If your network blocks port 22 (SSH), you can use HTTPS with a Personal Access Token:

  1. Generate a token: Go to github.com/settings/tokens → Generate new token (classic) → Select repo scope → Generate
  2. Copy the token immediately (it's only shown once!)
  3. Clone using the token:git clone https://github.com/mxfschr/queryglow.git

    Username: your GitHub username

    Password: paste your token (NOT your GitHub password)

2. Install

./queryglow install

./queryglow install runs deploy.sh, the interactive installer, and records your install for update, status, backup and doctor. It offers to link the command into /usr/local/bin, so queryglow status works from any directory.

The installer detects your server setup and picks the mode itself: Standalone on a server without nginx (Docker runs nginx, certbot and the app) or Integration when a system nginx is already running (only the app container runs, the installer adds a site to your nginx and uses the system certbot).

It asks for:

  • Domain: for example db.yourcompany.com
  • Email: for the SSL certificate
  • Admin username and password (at least 8 characters): the login your team shares
  • AI keys: optional. You can also add OpenAI, Anthropic or Google keys later in the app (Ask AI, AI providers)
  • Query Editor mode: Safe (recommended) or Power
  • Update check: whether queryglow status may run git fetch to report new releases (default no)

What the installer does:

  • Checks the prerequisites: not root, Docker and the compose plugin, the docker group, the four tools
  • Picks the app port: 3000, or the next free one up to 3100
  • Checks that your domain points at the server (and warns about a Cloudflare proxy)
  • Generates SESSION_SECRET and ENCRYPTION_SALT for the AES-256-GCM encryption of stored credentials
  • Gets the certificate from Let's Encrypt and sets up the login
  • Starts QueryGlow, bound to 127.0.0.1 behind nginx

✓ Once complete, your app is live at https://your-domain.com

Running it again later is safe: it keeps your secrets, port and mode and only adds settings that are missing.

3. Log In

Open https://your-domain.com. The browser asks for the username and password you set, once per browser. It is one shared login (Basic Auth) for everyone on your team; the app has no per-user accounts.

4. Connect Your First Database

Click New in the sidebar. You do not have to type every field:

  • Paste a connection URL. Put a postgres://, mysql://, mariadb:// or cockroachdb:// URL into "Connection URL" and the fields below fill themselves.
  • Find local servers. Checks the standard database ports on the QueryGlow server itself and fills type, host and port for a PostgreSQL, MySQL, MariaDB or CockroachDB it finds.
  • Find databases on this server. Enter username and password, tick the databases you want and add them all at once, one connection per database.
  • SSH tunnel. For a database that is not exposed to the internet, tick "Connect via SSH Tunnel" and enter the SSH host, user and private key. QueryGlow pins the SSH server's host key on first connect and refuses the connection if it changes.

Click Test Connection, then Create. Mark a live database as Production: it shows in red everywhere, and the Query Editor asks before any write (on by default). More on connections

QueryGlow New Connection dialog with the Connection URL field, the Find local servers button and the connection form

5. Keep It Current

./queryglow update --check   # is a newer release available?
./queryglow update           # back up, update, verify, roll back on failure

Every 1.x update is included. ./queryglow update backs up first, checks that the new version is serving and returns to the previous release on its own if it is not. How updating works

Alternative: Run Locally (Development)

For testing on your laptop without SSL or a login, with Docker:

# Create .env with a session secret
echo "SESSION_SECRET=$(openssl rand -hex 32)" > .env

# Start the container
docker compose up --build

Or without Docker, with Node.js 22 or newer:

cp .env.example .env
# paste the output of: openssl rand -hex 32
# after SESSION_SECRET= in .env
npm install
npx next dev --webpack -H 127.0.0.1

Open http://localhost:3000 in your browser. No login in local dev mode, and the app is reachable on this machine only (127.0.0.1).

Note: Local dev mode has no authentication. For production, always install with ./queryglow install, which sets up SSL and Basic Auth.

Security by Default

After the install, QueryGlow has these protections in place:

  • Safe Mode (unless you chose Power): blocks DROP TABLE, TRUNCATE and DELETE or UPDATE without WHERE in the Query Editor. DROP DATABASE is blocked in both modes.
  • HTTPS: all traffic encrypted with a Let's Encrypt certificate.
  • Basic Auth: login required for the app and its API (the health check, the agent endpoint with its own tokens and the browser icons excepted).
  • Credentials encrypted: database passwords, SSH keys and AI keys entered in the app are stored with AES-256-GCM.
  • SSH host keys pinned on first connect.
  • Confirmation before writes on connections marked production (Query Editor, on by default).
  • Search engines blocked: your instance won't appear in Google.