AdvancedUnsupported

Manual Node.js Deployment

Deploy directly on bare metal without Docker. Only use this if Docker is truly not an option.

Not Officially Supported

This deployment method is not covered in our official documentation and receives limited support. You are responsible for configuring Nginx, SSL certificates, Basic Auth, process management, and security hardening yourself.

We strongly recommend Docker deployment which handles all of this automatically.

Security Requirements (Your Responsibility)

• Reverse Proxy: You MUST set up Nginx or Caddy in front of QueryGlow
• SSL/HTTPS: You MUST configure Let's Encrypt or similar
• Authentication: You MUST configure Basic Auth or another auth layer
• Firewall: Port 3000 should NOT be exposed to the internet

Without these, your database credentials and data are exposed to anyone who finds your server.

1. Install Dependencies

Requires Node.js 18+ (20 recommended). Build tools are needed for the native SQLite driver (better-sqlite3).

# Install Node.js 20 and build tools (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs git build-essential python3

# Verify installation
node --version  # Should be v20.x.x
npm --version

2. Clone & Build

# Clone the repository
git clone [email protected]:mxfschr/queryglow.git
cd queryglow

# Install dependencies
npm ci

# Build for production
npm run build

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:

Check if you have an SSH key:ls -la ~/.ssh/id_*.pub
If no key exists, create one:ssh-keygen -t ed25519 -C "[email protected]"
Copy your public key:cat ~/.ssh/id_ed25519.pub
Add to GitHub: Go to github.com/settings/keys → New SSH key → Paste your key
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:

Generate a token: Go to github.com/settings/tokens → Generate new token (classic) → Select repo scope → Generate
Copy the token immediately (it's only shown once!)
Clone using the token:git clone https://github.com/mxfschr/queryglow.git
Username: your GitHub username
Password: paste your token (NOT your GitHub password)

3. Configure Environment

Create a .env file or export environment variables.

# Create .env file
cat > .env << 'EOF'
# REQUIRED: Encryption key for stored credentials
SESSION_SECRET=$(openssl rand -hex 32)

# Environment
NODE_ENV=production
PORT=3000

# Data storage location
DATA_DIR=/home/youruser/queryglow/data

# Safe Mode (default: false = Safe Mode ON)
# Set to true to allow DROP TABLE, TRUNCATE, etc. in Query Editor
QUERYGLOW_ALLOW_DESTRUCTIVE=false

# Optional: AI Assistant API keys (only need one)
# OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# GOOGLE_API_KEY=AIza...
EOF

# Generate the actual secret
sed -i "s/SESSION_SECRET=.*/SESSION_SECRET=$(openssl rand -hex 32)/" .env

# Create data directory
mkdir -p /home/youruser/queryglow/data

4. Run with PM2

PM2 keeps the process alive, handles logs, and restarts on crashes.

# Install PM2 globally
sudo npm install -g pm2

# Start QueryGlow with PM2
pm2 start npm --name "queryglow" -- start

# Save process list for auto-restart on reboot
pm2 save
pm2 startup  # Follow the instructions it prints

# View logs
pm2 logs queryglow

The app will be available at http://localhost:3000. Do NOT expose this directly to the internet.

5. Configure Nginx + SSL + Auth (Required)

You must set up a reverse proxy with authentication. Here's a minimal example:

# Install nginx and certbot
sudo apt install nginx certbot python3-certbot-nginx apache2-utils

# Create htpasswd file for Basic Auth
sudo htpasswd -c /etc/nginx/queryglow.htpasswd admin

# Create nginx config
sudo nano /etc/nginx/sites-available/queryglow

Add this configuration:

server {
    server_name db.yourcompany.com;

    auth_basic "QueryGlow";
    auth_basic_user_file /etc/nginx/queryglow.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Robots-Tag "noindex, nofollow" always;

    listen 80;
}

# Enable site and get SSL certificate
sudo ln -s /etc/nginx/sites-available/queryglow /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d db.yourcompany.com

How to Update

cd queryglow
git pull
npm ci
npm run build
pm2 restart queryglow

Environment Variables Reference

Variable	Required	Description
SESSION_SECRET	Required	Encryption key for stored credentials (AES-256-GCM). Generate with `openssl rand -hex 32`
NODE_ENV	Required	Set to `production`
QUERYGLOW_ALLOW_DESTRUCTIVE	Optional	`false` (default) = Safe Mode ON: blocks DROP TABLE, TRUNCATE, DELETE/UPDATE without WHERE in Query Editor. `true` = Power Mode: all SQL allowed.
DATA_DIR	Optional	Path to store connections, history, saved queries. Default: `/app/data` (set explicitly for Node.js deployment)
PORT	Optional	Server port. Default: `3000`
OPENAI_API_KEY	Optional	For AI SQL generation (GPT-4o)
ANTHROPIC_API_KEY	Optional	For AI SQL generation (Claude)
GOOGLE_API_KEY	Optional	For AI SQL generation (Gemini)

SQLite Security Note

For security, SQLite database paths are restricted to the DATA_DIR directory. If you want to use SQLite databases, place them in your configured data directory (e.g., /home/youruser/queryglow/data/).