License Activation Guide

This guide explains how to activate your SelfHostedDB license in various deployment scenarios.

Table of Contents

• Prerequisites
• Activation Methods
  • Method 1: CLI Tool (Recommended)
  • Method 2: Environment Variables
  • Method 3: Pre-configured Volume Mount
• Checking License Status
• Deactivating a License
• Troubleshooting

Prerequisites

Before activating your license, you need:

1. License Key: Received via email after purchase or trial registration
2. Email Address: The email used for purchase/registration (must match)
3. Running Container: Your SelfHostedDB Docker container must be running

Getting a License

• Free Trial: Visit https://license.selfhosteddb.com (opens in a new tab) and start a 14-day trial
• Purchase: Buy a license at https://license.selfhosteddb.com/purchase (opens in a new tab)

Activation Methods

Method 1: CLI Tool (Recommended)

This is the recommended method for most users. The CLI tool provides immediate feedback and handles errors gracefully.

Basic Usage

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

With Custom License Server

If you're using a self-hosted license server:

docker exec -it selfhosteddb-app activate-license \
  --key "YOUR_LICENSE_KEY" \
  --email "your@email.com" \
  --server-url "https://license.yourdomain.com"

CLI Options

Success Output

🔐 Activating license...
   License Key: abc123...xyz9
   Email: user@example.com

   → Validating license key...
   → Activating on this machine...

✔ License activated successfully!

License Details:
   Type: Paid License
   Expires: Never (lifetime license)

📝 Next steps:
   1. Start or restart your application
   2. Login with your database credentials
   3. Access your database management interface

   License file saved to: license.json

Method 2: Environment Variables

Useful for automated deployments, CI/CD pipelines, or when CLI access is not available.

Docker Run

docker run -d \
  --name selfhosteddb-app \
  -p 3001:3001 \
  -e DATABASE_URL="postgres://user:pass@host:5432/dbname" \
  -e LICENSE_KEY="YOUR_LICENSE_KEY" \
  -e LICENSE_EMAIL="your@email.com" \
  -v ./license-data:/app/license-data \
  selfhosteddb:latest

Docker Compose

Edit your docker-compose.yml:

services:
  app:
    image: selfhosteddb:latest
    environment:
      DATABASE_URL: postgres://user:pass@host:5432/dbname
      LICENSE_KEY: "YOUR_LICENSE_KEY"
      LICENSE_EMAIL: "your@email.com"
    volumes:
      - ./license-data:/app/license-data

Then start the container:

docker-compose up -d

Behavior

• License activation occurs automatically on container startup
• Environment variables are cleared after successful activation for security
• License is saved to /app/license-data/license.json (persisted via volume)
• Check logs for activation status: docker logs selfhosteddb-app

Method 3: Pre-configured Volume Mount

Use this method when migrating between hosts or sharing a license across deployments.

Step 1: Activate on One Machine

Use Method 1 or 2 to activate the license on one machine. This creates /app/license-data/license.json.

Step 2: Copy License File

# From the host machine
docker cp selfhosteddb-app:/app/license-data/license.json ./license-data/

Step 3: Mount on New Deployment

docker run -d \
  --name selfhosteddb-app \
  -p 3001:3001 \
  -e DATABASE_URL="postgres://..." \
  -v ./license-data:/app/license-data \
  selfhosteddb:latest

The container will automatically detect and use the existing license file.

Checking License Status

Via CLI (Inside Container)

docker exec -it selfhosteddb-app curl http://localhost:3001/api/license/status

Example Response:

{
  "valid": true,
  "status": "trial",
  "type": "trial",
  "expiresAt": "2025-01-15T00:00:00.000Z",
  "daysRemaining": 12,
  "lastValidatedAt": "2025-01-03T10:30:00.000Z"
}

Via Web UI

1. Login to your SelfHostedDB instance
2. Navigate to Settings tab
3. View License Status panel at the top

Status Values

Deactivating a License

To free up a deployment slot for reuse on another machine:

Option 1: Via License Server Dashboard

1. Visit https://license.selfhosteddb.com/dashboard (opens in a new tab)
2. Login with your account
3. Navigate to My Licenses
4. Find the deployment to deactivate
5. Click Deactivate

Option 2: Via API (Advanced)

curl -X POST https://license.selfhosteddb.com/api/license/deactivate \
  -H "Content-Type: application/json" \
  -d '{
    "licenseKey": "YOUR_LICENSE_KEY",
    "machineId": "YOUR_MACHINE_ID",
    "email": "your@email.com"
  }'

To find your machine ID:

docker exec -it selfhosteddb-app cat /app/license-data/machine-id.json

Troubleshooting

Error: "License key not found or inactive"

Cause: The license key is invalid, expired, or not found in the database.

Solutions:

• Verify you copied the entire license key (no extra spaces)
• Check your email for the correct key
• Ensure your trial hasn't expired
• Contact support if the license was recently purchased

Error: "License key does not match this email address"

Cause: The email address provided doesn't match the purchase/trial email.

Solutions:

• Use the exact email address from your purchase confirmation
• Check for typos (email is case-sensitive for validation)
• If you used multiple emails, try each one
• Contact support to verify the correct email

Error: "Deployment limit reached"

Cause: Your license is already activated on the maximum number of machines (default: 5).

Solutions:

• Deactivate an existing deployment (see Deactivating a License)
• Purchase additional licenses for more deployments
• Each deployment can have unlimited schemas/projects—consider consolidating

Error: "Unable to connect to license server"

Cause: Network connectivity issues or license server is unreachable.

Solutions:

• Check your internet connection
• Verify the license server URL is correct
• Check if a firewall is blocking outbound connections
• Try again later if the license server is temporarily down

Grace Period Behavior:

• Paid licenses: 7-day grace period
• Trial licenses: 3-day grace period
• The app will continue to work during the grace period

Error: "LICENSE_SERVER_URL not configured"

Cause: The LICENSE_SERVER_URL environment variable is missing.

Solutions:

# Set via Docker run
docker run -e LICENSE_SERVER_URL=https://license.selfhosteddb.com ...
 
# Set via Docker Compose
environment:
  LICENSE_SERVER_URL: https://license.selfhosteddb.com
 
# Set via CLI flag
docker exec -it selfhosteddb-app activate-license \
  --server-url "https://license.selfhosteddb.com" \
  --key "..." \
  --email "..."

License File Permissions Issues

Cause: Container doesn't have write access to /app/license-data.

Solutions:

# Ensure the directory exists and is writable
mkdir -p ./license-data
chmod 755 ./license-data
 
# If running as non-root, ensure correct ownership
chown -R 1000:1000 ./license-data

License File Missing After Container Restart

Cause: License data directory is not mounted as a volume.

Solutions:

# Always use a volume mount for license persistence
docker run -v ./license-data:/app/license-data ...
 
# Or in docker-compose.yml:
volumes:
  - ./license-data:/app/license-data

CLI Tool Not Found

Cause: The activate-license CLI tool is not in the PATH or not executable.

Solutions:

# Use full path
docker exec -it selfhosteddb-app /app/bin/activate-license.js --help
 
# Or rebuild the Docker image
docker build -t selfhosteddb:latest .

Advanced Topics

Multiple Deployments

Each license allows up to 5 deployment instances. A "deployment" is:

• One Docker container with its own machine ID
• Each deployment can have unlimited PostgreSQL schemas
• Example: Deploy on AWS, GCP, and local dev (3 deployments)

License Caching

• License status is cached for 12 hours in memory
• File cache persists across restarts: /app/license-data/license.json
• Automatic revalidation when cache expires
• Grace period activates if license server is unreachable

Self-Hosted License Server

If you're running your own license server:

1. Deploy the license-server component
2. Set LICENSE_SERVER_URL to your server's URL
3. All license activation will use your server

Getting Help

• Documentation: https://docs.selfhosteddb.com (opens in a new tab)
• Support Email: support@selfhosteddb.com
• Community Forum: https://community.selfhosteddb.com (opens in a new tab)
• GitHub Issues: https://github.com/yourorg/selfhosteddb/issues (opens in a new tab)

Next Steps:

• Production Deployment Guide - Platform-specific deployment instructions
• Troubleshooting Guide - Common issues and solutions
• Architecture Overview - Understanding the licensing system