Skip to main content

Installation

This guide will walk you through installing StagDB on your Ubuntu system.

Prerequisites​

Before installing StagDB, ensure your system meets the following requirements:

System Requirements​

  • Operating System: Ubuntu 20.04 LTS or newer
  • RAM: Minimum 4GB (8GB+ recommended)
  • Storage: At least 20GB free space
  • CPU: 2+ cores recommended

Required Software​

  • Docker and Docker Compose
  • ZFS utilities
  • Git (for installation)

Quick Installation​

1. Install Docker​

# Update package index
sudo apt update

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Start and enable Docker
sudo systemctl start docker
sudo systemctl enable docker

Log out and back in for the group changes to take effect.

2. Install ZFS​

# Install ZFS utilities
sudo apt install zfsutils-linux

# Verify ZFS installation
sudo zfs version

3. Clone and Setup StagDB​

# Clone the repository
git clone https://github.com/aayushgoel92/stagdb-ce.git
cd stagdb-ce

# Create environment file
cp .env.example .env

# Edit environment variables
nano .env

4. Configure Environment​

Edit the .env file with your settings:

# Domain configuration
DOMAIN=your-domain.com

# ZFS pool configuration
ZFS_POOL=tank

# Database settings
DEFAULT_POSTGRES_VERSION=15
DEFAULT_MYSQL_VERSION=8.0
DEFAULT_MONGODB_VERSION=7.0

5. Start StagDB​

# Build and start services
docker-compose up -d

# Check service status
docker-compose ps

Configuration​

ZFS Pool Setup​

StagDB requires a ZFS pool for database branching. Create one if you don't have it:

# Create a ZFS pool (replace /dev/sdb with your disk)
sudo zpool create tank /dev/sdb

# Or create a pool with multiple disks for redundancy
sudo zpool create tank mirror /dev/sdb /dev/sdc

Firewall Configuration​

Open necessary ports:

# Open HTTP and HTTPS
sudo ufw allow 80
sudo ufw allow 443

# Open API port (if needed)
sudo ufw allow 3000

Verification​

Check Service Health​

# Check all services are running
docker-compose ps

# Check logs
docker-compose logs -f

# Test API endpoint
curl https://api.your-domain.com/health

Create Your First Database​

# Create a PostgreSQL database
curl -X POST https://api.your-domain.com/api/v1/databases \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-db",
    "type": "postgresql",
    "version": "15"
  }'

Troubleshooting​

Common Issues​

Docker Permission Denied​

# Make sure your user is in the docker group
sudo usermod -aG docker $USER
# Log out and back in

ZFS Pool Not Found​

# Check ZFS pools
sudo zpool list

# Import existing pool
sudo zpool import tank

Services Not Starting​

# Check logs for errors
docker-compose logs

# Rebuild containers
docker-compose down
docker-compose up --build -d

Log Locations​

  • Application logs: docker-compose logs
  • ZFS logs: /var/log/syslog
  • Docker logs: journalctl -u docker

Next Steps​

Once installation is complete:

  1. Access the web dashboard at https://dashboard.your-domain.com
  2. Read about Database Provisioning
  3. Learn about Database Branching
  4. Explore the API Reference

Updating StagDB​

To update to the latest version:

# Pull latest changes
git pull origin main

# Rebuild and restart
docker-compose down
docker-compose up --build -d

Uninstallation​

To completely remove StagDB:

# Stop and remove containers
docker-compose down -v

# Remove Docker images
docker rmi $(docker images stagdb* -q)

# Remove data (WARNING: This deletes all databases)
sudo zfs destroy -r tank/stagdb