Installation Guide

Step-by-step guide for installing and setting up SelfHostedDB

This guide walks you through installing SelfHostedDB on your system, whether you're using Docker, a cloud platform, or a local server.

Quick Start

Fastest way to get started (5 minutes):

# 1. Clone or download the project
git clone <repository-url>
cd db-tool-pgvista
 
# 2. Start with Docker Compose (includes PostgreSQL)
docker-compose up -d
 
# 3. Access the application
# Open http://localhost:3001 in your browser
# Default credentials: admin / secret

That's it! You now have a running SelfHostedDB with a test database.

Prerequisites

Required Software

Docker (version 20.10 or higher)
- Windows: Docker Desktop (opens in a new tab)
- macOS: Docker Desktop (opens in a new tab)
- Linux: Docker Engine (opens in a new tab)
Verify installation:
```
docker --version
docker-compose --version
```
PostgreSQL Database (version 12 or higher)
- Can be local, remote, or cloud-hosted
- Or use the bundled PostgreSQL in Docker Compose (recommended for testing)

Optional Software

Git (for cloning the repository)
Text Editor (for editing configuration files)

Installation Methods

Method 1: Docker Compose (Recommended for Beginners)

Best for: Quick setup, testing, development, single-server deployments

Steps:

Download or clone the project:

git clone <repository-url>
cd db-tool-pgvista

Configure environment variables (optional):

# Copy the example file
cp backend/env.example .env
 
# Edit .env with your settings (or use defaults for testing)
# DATABASE_URL=postgres://postgres:testpass@db:5432/postgres
# AUTH_USER=admin
# AUTH_PASS=secret

Start the application:
```
docker-compose up -d
```

Verify it's running:

docker-compose ps
# You should see 'selfhosteddb-db' and 'selfhosteddb-app' running

Access the application:
- Open your browser: http://localhost:3001
- Login with credentials from .env (default: admin / secret)

What this does:

Starts a PostgreSQL database container
Starts the application container
Connects them together
Persists database data in ./data directory

Stop the application:

docker-compose down

Stop and remove all data:

docker-compose down -v

Method 2: Docker Run (Using Existing Database)

Best for: Production deployments, using existing PostgreSQL instance

Steps:

Pull or build the Docker image:

# Option A: Pull from registry (if available)
docker pull your-registry/selfhosteddb:latest
 
# Option B: Build from source
git clone <repository-url>
cd db-tool-pgvista
docker build -t selfhosteddb:latest .

Run the container:

# Create directory for license data persistence
mkdir -p ./license-data
 
docker run -d \
  --name selfhosteddb \
  --restart unless-stopped \
  -p 3001:3001 \
  -e DATABASE_URL="postgres://username:password@host:5432/database" \
  -e AUTH_USER="admin" \
  -e AUTH_PASS="your-strong-password" \
  -e NODE_ENV="production" \
  -e LICENSE_SERVER_URL="https://license.selfhosteddb.com" \
  -v ./license-data:/app/license-data \
  selfhosteddb:latest

Optional: Auto-activate license on startup:

-e LICENSE_KEY="YOUR_LICENSE_KEY" \
-e LICENSE_EMAIL="your@email.com"

Verify it's running:

docker ps | grep selfhosteddb
docker logs selfhosteddb

Access the application:
- Open: http://localhost:3001 (or your server IP)
- Login with your AUTH_USER and AUTH_PASS

Notes:

Replace host with your PostgreSQL hostname/IP
For local PostgreSQL: use host.docker.internal (Windows/Mac) or 172.17.0.1 (Linux)
For remote PostgreSQL: use the server's IP address or hostname

Method 3: Manual Installation (Development)

Best for: Developers who want to modify the code

Prerequisites:

Node.js 18+ installed
PostgreSQL 12+ running locally or remotely

Steps:

Clone the repository:

git clone <repository-url>
cd db-tool-pgvista

Install backend dependencies:
```
cd backend
npm install
```

Configure backend:

cp env.example .env
# Edit .env with your database connection

Start backend:

npm run dev
# Backend runs on http://localhost:3001

Install frontend dependencies (in a new terminal):
```
cd frontend
npm install
```

Start frontend:

npm start
# Frontend runs on http://localhost:3000

Access the application:
- Open: http://localhost:3000
- The frontend will connect to the backend automatically

Configuration

Environment Variables

Required Variables:

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgres://user:pass@host:5432/db`
`AUTH_USER`	Admin username for login	`admin`
`AUTH_PASS`	Admin password for login	`your-strong-password`
`LICENSE_SERVER_URL`	License server URL (for license validation)	`https://license.yourdomain.com`

Optional Variables:

Variable	Description	Default
`PORT`	Server port	`3001`
`NODE_ENV`	Environment mode	`development`
`LICENSE_KEY`	License key for auto-activation on startup	Not set
`LICENSE_EMAIL`	Email address for license activation	Not set
`LICENSE_ENCRYPTION_KEY`	Key for encrypting local license cache (recommended for production)	Not set

Note: If LICENSE_KEY and LICENSE_EMAIL are set, the license will activate automatically on container startup. These variables are cleared after successful activation for security.

Database Connection String Format

postgres://username:password@hostname:port/database_name

Examples:

Local PostgreSQL:

postgres://postgres:mypassword@localhost:5432/mydb

Remote PostgreSQL:

postgres://user:pass@192.168.1.100:5432/production_db

Cloud PostgreSQL (with SSL):

postgres://user:pass@db.example.com:5432/mydb?sslmode=require

Docker Compose (internal network):

postgres://postgres:testpass@db:5432/postgres

Security Configuration

Change default credentials immediately:

# Generate a strong password
# Linux/Mac:
openssl rand -base64 32
 
# Windows PowerShell:
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Minimum 0 -Maximum 256 }))

Update .env or environment variables:

AUTH_USER=my_admin_username
AUTH_PASS=your-generated-strong-password

First Run

Initial Setup

Start the application (using your chosen method)
Activate License (Before or After Login):

You can activate your license either before or after logging in. The application allows access for license activation even without an active license.

Option A: Activate via CLI Tool (Recommended)
```
# If using Docker
docker exec -it selfhosteddb-app activate-license \
  --key "YOUR_LICENSE_KEY" \
  --email "your@email.com"
 
# Or if using docker-compose
docker exec -it selfhosteddb-app activate-license \
  --key "YOUR_LICENSE_KEY" \
  --email "your@email.com"
```
Option B: Auto-activate via Environment Variables
```
# Add to your docker run command or docker-compose.yml
-e LICENSE_KEY="YOUR_LICENSE_KEY" \
-e LICENSE_EMAIL="your@email.com"
```
The license will activate automatically on container startup.

Option C: Activate After Login
- Login first (see step 3)
- Navigate to Settings → License Status panel
- Follow the CLI instructions shown in the UI
Login to the application:
- Open http://localhost:3001 (or your server address)
- Enter your AUTH_USER and AUTH_PASS
- Click "Login"
- You can login even without an active license (license check happens after login)
Check License Status (After Login):
- Navigate to Settings tab
- View License Status panel at the top
- If license is not activated, you'll see instructions for activation
Start using the application:
- Browse tables in the "Tables" tab
- Run queries in the "SQL Editor" tab
- View schema relationships in the "Schema" tab

Note: For detailed license activation instructions, see the License Activation Guide.

License Information

License Model:

Email-based activation - License is tied to the purchaser's email address
Unlimited deployments - Same owner can deploy on unlimited machines/platforms
Unlimited team members - No limit on who can access the deployed instance
Lifetime license - Pay once, use forever with free updates

Trial Period:

14-day free trial with full feature access
No credit card required
Automatically converts to license after purchase

Sample Data (Optional)

Load sample data for testing:

# If using Docker Compose
docker exec -i selfhosteddb-db psql -U postgres < seed.sql
 
# If using local PostgreSQL
psql -U postgres -d your_database < seed.sql

This creates sample tables (users, posts, comments) with test data.

Verification

Health Check

Test if the application is running:

# Using curl
curl http://localhost:3001/api/health
 
# Expected response:
# {"status":"ok","timestamp":"2025-01-27T10:00:00.000Z"}

Using browser:

Open: http://localhost:3001/api/health
Should see JSON response with "status": "ok"

Database Connection

Check if database connection works:

Login to the application
Navigate to "Tables" tab
You should see a list of tables (or empty list if no tables exist)
If you see an error, check:
- DATABASE_URL is correct
- PostgreSQL is running
- Network connectivity (if remote database)
- Firewall rules (if remote database)

Common Issues

Application won't start:

Check Docker is running: docker ps
Check logs: docker logs selfhosteddb-app
Verify environment variables are set

Can't connect to database:

Verify PostgreSQL is running
Check DATABASE_URL format
Test connection: psql "your-database-url"
For Docker: use host.docker.internal instead of localhost

Login doesn't work:

Verify AUTH_USER and AUTH_PASS are set correctly
Check for typos in credentials
Clear browser cache and cookies

For more troubleshooting: See the Troubleshooting Guide

Related Documentation:

Production Deployment Guide - Deploy to production environments
Security Best Practices - Secure your installation
API Documentation - Integrate with your applications

Next Steps

After installation:

Read the Production Deployment Guide - Deploy to production
Review Security Best Practices - Secure your installation
Check API Documentation - Integrate with your applications
Explore Features:
- Browse and edit tables
- Run SQL queries
- View schema relationships
- Export data

Uninstallation

Docker Compose

# Stop and remove containers
docker-compose down
 
# Remove containers and volumes (deletes database data!)
docker-compose down -v
 
# Remove images
docker rmi selfhosteddb:latest postgres:15-alpine

Docker Run

# Stop container
docker stop selfhosteddb
 
# Remove container
docker rm selfhosteddb
 
# Remove image
docker rmi selfhosteddb:latest

Manual Installation

# Stop processes (Ctrl+C in terminals)
 
# Remove dependencies (optional)
cd backend && rm -rf node_modules
cd ../frontend && rm -rf node_modules

Support

Need help?

Check Troubleshooting Guide for common issues
Review API Documentation for API usage
See Security Guide for security configuration

Last Updated: 2025-01-27

License Activation

Understanding the License System

SelfHostedDB uses an email-based license system that allows multiple deployments per license owner:

License Owner: Identified by email address (the purchaser)
Deployments: Up to 5 deployments per license (same owner can deploy on AWS, GCP, Docker, DigitalOcean, etc.)
Team Members: Unlimited per deployment (via Basic Auth or API Keys)
Restrictions: License key must match the purchaser's email address (prevents sharing)

Getting a License

Free Trial:

Visit https://license.selfhosteddb.com (opens in a new tab) to start a 14-day free trial
No credit card required
Full feature access for 14 days

Purchase License:

Buy a license at https://license.selfhosteddb.com/purchase (opens in a new tab)
Lifetime license - pay once, use forever
Receive license key via email after purchase

Activation Methods

Method 1: CLI Tool (Recommended)

docker exec -it selfhosteddb-app activate-license \
  --key "YOUR_LICENSE_KEY" \
  --email "your@email.com"

Method 2: Environment Variables (Auto-activation)

# Add to docker run or docker-compose.yml
-e LICENSE_KEY="YOUR_LICENSE_KEY" \
-e LICENSE_EMAIL="your@email.com"

Method 3: Volume Mount (Pre-configured)

Copy license file from another deployment
Mount volume: -v ./license-data:/app/license-data

License Persistence

Important: Always mount a volume for license persistence:

# Docker run
-v ./license-data:/app/license-data
 
# Docker Compose
volumes:
  - ./license-data:/app/license-data

This ensures your license persists across container restarts.

License Status

Check License Status:

Via UI: Login → Settings → License Status panel
Via API: GET /api/license/status (no authentication required)
Via CLI: docker exec selfhosteddb-app curl http://localhost:3001/api/license/status

Status Values:

trial - Active trial period
paid - Paid license active
expired - License has expired
grace_period - Expired but within grace period (7 days for paid, 3 days for trial)
none - No license found

Troubleshooting License Issues

"License key not found":

Verify you're using the correct license key from your purchase email
Ensure the email address matches the one used for purchase
Check that LICENSE_SERVER_URL is correctly configured

"License key does not match email":

Use the exact email address associated with your purchase
License keys are tied to the purchaser's email to prevent sharing

"Trial expired":

Purchase a license to continue using the application
Your trial data and configuration are preserved

"Deployment limit reached":

Each license allows up to 5 deployments
Deactivate an unused deployment via the license portal
Or purchase additional licenses

For more help:

See License Activation Guide for detailed instructions
See Troubleshooting Guide for license-related issues

Home Production