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:

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" \
  selfhosteddb:latest

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_ENCRYPTION_KEY`	Key for encrypting local license cache (recommended for production)	Not set

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)
Access the login page:
- Open http://localhost:3001 (or your server address)
- You should see the login screen
Activate License or Start Trial:
- Option A: Activate a purchased license
  - Enter your license key (received via email after purchase)
  - Enter the email address associated with your purchase
  - Click "Activate License"
- Option B: Start a 14-day free trial
  - Enter your email address
  - Click "Start Free Trial"
  - You'll have full access for 14 days
Login:
- Enter your AUTH_USER and AUTH_PASS
- Click "Login"
Create your first project (schema):
- Click "New Project" or "Create Schema"
- Enter a schema name (e.g., my_project)
- Enter a password for the schema user
- Click "Create"
Start using the application:
- Browse tables in the "Tables" tab
- Run queries in the "SQL Editor" tab
- View schema relationships in the "Schema" tab

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 unlimited deployments per license owner:

License Owner: Identified by email address (the purchaser)
Deployments: Unlimited (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)

Activating Your License

After Purchase:

You'll receive a license key via email
Start the application
Enter your license key and the email address used for purchase
Click "Activate License"
The license is activated and cached locally

Starting a Trial

14-Day Free Trial:

Start the application
Enter your email address
Click "Start Free Trial"
You'll have full access for 14 days
After purchase, your trial automatically converts to a license

License Status

Check License Status:

View license status in the application UI
API endpoint: GET /api/license/status (no authentication required)
Shows: license validity, trial expiration, grace period status

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

For more help: See Troubleshooting Guide for license-related issues

Home Production