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

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

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

## Installation Options

### Basic Installation
```bash
sudo ./installer/alpha/install.sh
```

### Skip Optional Components
```bash
# 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
```bash
# Only setup configuration, don't build/install binaries
sudo ./installer/alpha/install.sh --config-only
```

### Custom Version
```bash
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:

```bash
# 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
```bash
sudo systemctl start calypso-api
```

### Stop Service
```bash
sudo systemctl stop calypso-api
```

### Restart Service
```bash
sudo systemctl restart calypso-api
```

### Check Status
```bash
sudo systemctl status calypso-api
```

### View Logs
```bash
# 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`:
```bash
sudo nano /etc/calypso/config.yaml
```

### Environment Variables
Edit `/etc/calypso/secrets.env`:
```bash
sudo nano /etc/calypso/secrets.env
```

After changing configuration, restart service:
```bash
sudo systemctl restart calypso-api
```

## Uninstallation

### Full Uninstallation
```bash
sudo ./installer/alpha/uninstall.sh
```

### Keep Data and Configuration
```bash
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:
```bash
# See documentation
docs/on-progress/scst-installation.md
```

### ZFS Setup
If ZFS needs manual setup:
```bash
# Create ZFS pool
sudo zpool create tank /dev/sdb /dev/sdc

# Create datasets
sudo zfs create tank/calypso
```

### Database Setup
If database setup fails:
```bash
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/`