calypso/installer/alpha/INSTALLATION-GUIDE.md

Calypso Appliance Installation Guide

Prerequisites

• Ubuntu Server 24.04 LTS (recommended)
• Root or sudo access
• Minimum 10GB free disk space
• Network connectivity
• At least 4GB RAM

Quick Installation

# Clone or extract Calypso source
cd /path/to/calypso

# Run installer
sudo ./installer/alpha/install.sh

Installation Options

Basic Installation

sudo ./installer/alpha/install.sh

Skip Optional Components

# Skip ZFS (if already installed)
sudo ./installer/alpha/install.sh --skip-zfs

# Skip SCST (install manually later)
sudo ./installer/alpha/install.sh --skip-scst

# Skip MHVTL
sudo ./installer/alpha/install.sh --skip-mhvtl

# Skip Bacula
sudo ./installer/alpha/install.sh --skip-bacula

Configuration Only

# Only setup configuration, don't build/install binaries
sudo ./installer/alpha/install.sh --config-only

Custom Version

sudo ./installer/alpha/install.sh --version 1.0.0

Installation Process

The installer performs the following steps:

1. Pre-flight Checks

   • Verify OS compatibility
   • Check disk space
   • Verify network connectivity

2. Filesystem Setup

   • Create directory structure per architecture spec
   • Set permissions
   • Create calypso user

3. System Dependencies

   • Install Go 1.22+
   • Install Node.js 20.x LTS
   • Install PostgreSQL 14+
   • Install storage and tape tools

4. Component Installation

   • ZFS (if not installed)
   • SCST prerequisites
   • MHVTL (optional)
   • Bacula (optional)

5. Application Build

   • Build backend binary
   • Build frontend assets
   • Install to /opt/adastra/calypso/releases/VERSION/

6. Database Setup

   • Create PostgreSQL database
   • Create database user
   • Run migrations (on first API start)

7. Configuration

   • Generate secrets
   • Create configuration files
   • Setup environment variables

8. Service Installation

   • Install systemd service
   • Enable service
   • Start service

9. Verification

   • Verify installation
   • Test API connectivity
   • Print access information

Post-Installation

1. Access Web UI

Open browser and navigate to:

http://<server-ip>:3000

2. Login

Default credentials (displayed during installation):

• Username: admin
• Password: (check installation output)

⚠️ IMPORTANT: Change the default password immediately!

3. Configure System

1. Storage Configuration

   • Create ZFS pools
   • Create datasets
   • Configure storage repositories

2. Network Configuration

   • Configure network interfaces
   • Setup NTP servers

3. Service Configuration

   • Enable/disable services
   • Configure SCST targets
   • Setup tape libraries

4. Setup Reverse Proxy (Optional)

For production, setup reverse proxy:

# Nginx
sudo ./installer/alpha/scripts/setup-reverse-proxy.sh nginx

# Or Caddy
sudo ./installer/alpha/scripts/setup-reverse-proxy.sh caddy

Directory Structure

After installation:

/opt/adastra/calypso/
  releases/
    1.0.0-alpha/
      bin/calypso-api
      web/          (frontend assets)
      migrations/
      scripts/
  current -> releases/1.0.0-alpha

/etc/calypso/
  config.yaml
  secrets.env
  tls/
  integrations/
  system/
  scst/

/srv/calypso/
  db/
  backups/
  object/
  shares/
  vtl/
  iscsi/
  uploads/
  cache/
  _system/

/var/log/calypso/
  (application logs)

/var/lib/calypso/
  (runtime data)

/run/calypso/
  (runtime files)

Service Management

Start Service

sudo systemctl start calypso-api

Stop Service

sudo systemctl stop calypso-api

Restart Service

sudo systemctl restart calypso-api

Check Status

sudo systemctl status calypso-api

View Logs

# Follow logs
sudo journalctl -u calypso-api -f

# Last 100 lines
sudo journalctl -u calypso-api -n 100

Configuration

Main Configuration

Edit /etc/calypso/config.yaml:

sudo nano /etc/calypso/config.yaml

Environment Variables

Edit /etc/calypso/secrets.env:

sudo nano /etc/calypso/secrets.env

After changing configuration, restart service:

sudo systemctl restart calypso-api

Uninstallation

Full Uninstallation

sudo ./installer/alpha/uninstall.sh

Keep Data and Configuration

sudo ./installer/alpha/uninstall.sh --keep-data --keep-config

Troubleshooting

See TROUBLESHOOTING.md for common issues and solutions.

Manual Steps (if needed)

SCST Installation

If SCST installation fails, install manually:

# See documentation
docs/on-progress/scst-installation.md

ZFS Setup

If ZFS needs manual setup:

# Create ZFS pool
sudo zpool create tank /dev/sdb /dev/sdc

# Create datasets
sudo zfs create tank/calypso

Database Setup

If database setup fails:

sudo -u postgres createdb calypso
sudo -u postgres createuser calypso
sudo -u postgres psql -c "ALTER USER calypso WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE calypso TO calypso;"

Support

For issues:

1. Check TROUBLESHOOTING.md
2. Review logs: sudo journalctl -u calypso-api -f
3. Check documentation: docs/alpha/