SessionDB Installation Guide

This guide covers how to easily install, configure, and manage a SessionDB instance using the official SessionDB CLI (scli).

🚀 1-Line Installation

The recommended and fastest way to install the SessionDB CLI is via the install script. It downloads the latest binary and adds it to your shell path (/usr/local/bin if writable, otherwise ~/.local/bin).

curl -sSL https://raw.githubusercontent.com/sessiondb/scli/main/install.sh | bash

To install a specific version of scli:

curl -sSL https://raw.githubusercontent.com/sessiondb/scli/main/install.sh | bash -s -- v1.0.0

Note: After installation, you may need to open a new terminal or run source ~/.zshrc (or ~/.bashrc) so that scli is available on your $PATH.

Other Installation Options

Install via Go (from source)

If you have a Go environment set up, you can install directly from the source repository:

go install .
export PATH="$PATH:$(go env GOPATH)/bin"

Manual Binary Installation

1. Go to the Releases page.
2. Download the binary matching your OS and architecture.
3. Place the binary in a directory on your $PATH.
4. Name the binary scli (or scli.exe on Windows).
5. Open a terminal and run scli --help to verify.

First-Time Setup Flow

Once scli is installed, you can initialize and deploy the full SessionDB application in a few short steps.

1. Initialize Configuration: scli init will start an interactive prompt to connect to your PostgreSQL (Metadata DB) and Redis instances. It generates secrets and creates a single config.toml file.
2. Download SessionDB Engine: scli install v1.0.1 downloads the corresponding backend binary and frontend UI dist payloads.
3. Deploy (e.g., to Bare Metal with Systemd): Configure SessionDB to run as a persistent background service automatically.

   scli deploy --platform baremetal --output sessiondb.service
   
   sudo cp sessiondb.service /etc/systemd/system/
   sudo systemctl daemon-reload && sudo systemctl enable sessiondb && sudo systemctl start sessiondb

4. Run Database Migrations: Apply the target backend schema against your new database instance.

   scli migrate

5. Verify Status: Check the health of the locally running service.

   scli status

Install Directory Structure

The CLI heavily manages and structures the root installation paths for isolation and safe rollbacks.

• Install root path: Default is /opt/sessiondb (when running as root) or $HOME/.local/share/sessiondb. You can override this using the SESSIONDB_INSTALL_ROOT environment variable.
• Directory Layout:
  • versions/<tag>/: Contains the backend binary, frontend dist, setup scripts, and configurations specific to a version.
  • current: A dynamic symlink pointing directly to versions/<installed-tag>.
• Checksum Security: If a downloaded release contains checksums.txt, all backend and frontend artifacts are strongly verified with SHA256 before extraction.

Docker Installation

SessionDB provides official Docker images. You can deploy it using Docker Compose in two primary ways depending on your infrastructure needs.

1. All-in-One Setup (Quickstart)

This configuration spins up the SessionDB app container along with its required Redis and PostgreSQL instances locally.

⬇️ Download docker-compose.yml

# version: '3.8'

services:
  app:
    build:
      context: .
    ports:
      - "8080:8080"
    environment:
      - DB_HOST=postgres
      - DB_USER=sessiondb
      - DB_PASSWORD=sessiondb_password
      - DB_NAME=sessiondb
      - DB_PORT=5432
      - REDIS_ADDR=redis:6379
      - DB_CREDENTIAL_ENCRYPTION_KEY=12345678901234567890123456789012
      - MIGRATE_TOKEN=${MIGRATE_TOKEN}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started

  ui:
    image: saimouli03/sessiondb-ui:tagname
    ports:
      - "3000:3000"
    depends_on:
      - app

  migrate-via-api:
    image: curlimages/curl:latest
    command:
      - sh
      - -c
      - |
        until curl -sf http://app:8080/health; do echo "waiting for app"; sleep 2; done
        curl -sf -X POST http://app:8080/v1/migrate -H "X-Migrate-Token: $$MIGRATE_TOKEN"
    environment:
      - MIGRATE_TOKEN=${MIGRATE_TOKEN}
    depends_on:
      - app

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=sessiondb
      - POSTGRES_PASSWORD=sessiondb_password
      - POSTGRES_DB=sessiondb
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U sessiondb" ]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

2. App-Only Setup (Managed Cloud Databases)

If you already use managed cloud databases like AWS RDS (Postgres) and Elasticache (Redis), you only need to run the SessionDB application container and point the environment variables to your remote resources.

⬇️ Download docker-compose.cloud.yml

# version: '3.8'

services:
  app:
    image: sessiondb/server:latest
    ports:
      - "8080:8080"
    environment:
      - DB_HOST=your-cloud-postgres-url.rds.amazonaws.com
      - DB_USER=sessiondb
      - DB_PASSWORD=your_secure_password
      - DB_NAME=sessiondb
      - DB_PORT=5432
      - REDIS_ADDR=your-cloud-redis-url.cache.amazonaws.com:6379
      - DB_CREDENTIAL_ENCRYPTION_KEY=12345678901234567890123456789012
      - MIGRATE_TOKEN=${MIGRATE_TOKEN}

  ui:
    image: saimouli03/sessiondb-ui:tagname
    ports:
      - "3000:3000"
    depends_on:
      - app

Kubernetes Installation

🚀 Coming Soon! Official Helm charts and Kubernetes Operator deployment strategies are currently in active development.

If you are interested in deploying SessionDB at scale on Kubernetes, join our early access waitlist to be notified as soon as the beta is released. We’d love to hear about your infrastructure use-cases!