atlas/docs/INSTALLATION.md

# AtlasOS Installation Guide

## Overview

This guide covers installing AtlasOS on a Linux system for testing and production use.

## Prerequisites

### System Requirements

- **OS**: Linux (Ubuntu 20.04+, Debian 11+, Fedora 34+, RHEL 8+)
- **Kernel**: Linux kernel with ZFS support
- **RAM**: Minimum 2GB, recommended 4GB+
- **Disk**: Minimum 10GB free space
- **Network**: Network interface for iSCSI/SMB/NFS

### Required Software

- ZFS utilities (`zfsutils-linux` or `zfs`)
- Samba (`samba`)
- NFS server (`nfs-kernel-server` or `nfs-utils`)
- iSCSI target (`targetcli`)
- SQLite (`sqlite3`)
- Go compiler (`golang-go` or `golang`) - for building from source
- Build tools (`build-essential` or `gcc make`)

## Quick Installation

### Automated Installer

The easiest way to install AtlasOS is using the provided installer script:

```bash
# Clone or download the repository
cd /path/to/atlas

# Run installer (requires root)
sudo ./install.sh
```

The installer will:
1. Install all dependencies
2. Create system user and directories
3. Build binaries
4. Create systemd service
5. Set up configuration
6. Start the service

### Installation Options

```bash
# Custom installation directory
sudo ./install.sh --install-dir /opt/custom-atlas

# Custom data directory
sudo ./install.sh --data-dir /mnt/atlas-data

# Skip dependency installation (if already installed)
sudo ./install.sh --skip-deps

# Skip building binaries (use pre-built)
sudo ./install.sh --skip-build

# Custom HTTP address
sudo ./install.sh --http-addr :8443

# Show help
sudo ./install.sh --help
```

## Manual Installation

### Step 1: Install Dependencies

#### Ubuntu/Debian

```bash
sudo apt-get update
sudo apt-get install -y \
    zfsutils-linux \
    samba \
    nfs-kernel-server \
    targetcli-fb \
    sqlite3 \
    golang-go \
    git \
    build-essential
```

**Note:** On newer Ubuntu/Debian versions, the iSCSI target CLI is packaged as `targetcli-fb`. If `targetcli-fb` is not available, try `targetcli`.

#### Fedora/RHEL/CentOS

```bash
# Fedora
sudo dnf install -y \
    zfs \
    samba \
    nfs-utils \
    targetcli \
    sqlite \
    golang \
    git \
    gcc \
    make

# RHEL/CentOS (with EPEL)
sudo yum install -y epel-release
sudo yum install -y \
    zfs \
    samba \
    nfs-utils \
    targetcli \
    sqlite \
    golang \
    git \
    gcc \
    make
```

### Step 2: Load ZFS Module

```bash
# Load ZFS kernel module
sudo modprobe zfs

# Make it persistent
echo "zfs" | sudo tee -a /etc/modules-load.d/zfs.conf
```

### Step 3: Create System User

```bash
sudo useradd -r -s /bin/false -d /var/lib/atlas atlas
```

### Step 4: Create Directories

```bash
sudo mkdir -p /opt/atlas/bin
sudo mkdir -p /var/lib/atlas
sudo mkdir -p /etc/atlas
sudo mkdir -p /var/log/atlas
sudo mkdir -p /var/lib/atlas/backups

sudo chown -R atlas:atlas /var/lib/atlas
sudo chown -R atlas:atlas /var/log/atlas
sudo chown -R atlas:atlas /etc/atlas
```

### Step 5: Build Binaries

```bash
cd /path/to/atlas
go build -o /opt/atlas/bin/atlas-api ./cmd/atlas-api
go build -o /opt/atlas/bin/atlas-tui ./cmd/atlas-tui

sudo chown root:root /opt/atlas/bin/atlas-api
sudo chown root:root /opt/atlas/bin/atlas-tui
sudo chmod 755 /opt/atlas/bin/atlas-api
sudo chmod 755 /opt/atlas/bin/atlas-tui
```

### Step 6: Create Systemd Service

Create `/etc/systemd/system/atlas-api.service`:

```ini
[Unit]
Description=AtlasOS Storage Controller API
After=network.target zfs.target

[Service]
Type=simple
User=atlas
Group=atlas
WorkingDirectory=/opt/atlas
ExecStart=/opt/atlas/bin/atlas-api
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=atlas-api

Environment="ATLAS_HTTP_ADDR=:8080"
Environment="ATLAS_DB_PATH=/var/lib/atlas/atlas.db"
Environment="ATLAS_BACKUP_DIR=/var/lib/atlas/backups"
Environment="ATLAS_LOG_LEVEL=INFO"
Environment="ATLAS_LOG_FORMAT=json"

NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/atlas /var/log/atlas /var/lib/atlas/backups /etc/atlas

[Install]
WantedBy=multi-user.target
```

Reload systemd:

```bash
sudo systemctl daemon-reload
sudo systemctl enable atlas-api
```

### Step 7: Configure Environment

Create `/etc/atlas/atlas.conf`:

```bash
# HTTP Server
ATLAS_HTTP_ADDR=:8080

# Database
ATLAS_DB_PATH=/var/lib/atlas/atlas.db

# Backup Directory
ATLAS_BACKUP_DIR=/var/lib/atlas/backups

# Logging
ATLAS_LOG_LEVEL=INFO
ATLAS_LOG_FORMAT=json

# JWT Secret (generate with: openssl rand -hex 32)
ATLAS_JWT_SECRET=$(openssl rand -hex 32)
```

### Step 8: Start Service

```bash
sudo systemctl start atlas-api
sudo systemctl status atlas-api
```

## Post-Installation

### Create Initial Admin User

After installation, create the initial admin user:

**Via API:**
```bash
curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your-secure-password",
    "email": "admin@example.com",
    "role": "administrator"
  }'
```

**Via TUI:**
```bash
/opt/atlas/bin/atlas-tui
```

### Configure TLS (Optional)

1. Generate or obtain TLS certificates
2. Place certificates in `/etc/atlas/tls/`:
   ```bash
   sudo cp cert.pem /etc/atlas/tls/
   sudo cp key.pem /etc/atlas/tls/
   sudo chown atlas:atlas /etc/atlas/tls/*
   sudo chmod 600 /etc/atlas/tls/*
   ```

3. Update configuration:
   ```bash
   echo "ATLAS_TLS_ENABLED=true" | sudo tee -a /etc/atlas/atlas.conf
   echo "ATLAS_TLS_CERT=/etc/atlas/tls/cert.pem" | sudo tee -a /etc/atlas/atlas.conf
   echo "ATLAS_TLS_KEY=/etc/atlas/tls/key.pem" | sudo tee -a /etc/atlas/atlas.conf
   ```

4. Restart service:
   ```bash
   sudo systemctl restart atlas-api
   ```

### Verify Installation

1. **Check Service Status:**
   ```bash
   sudo systemctl status atlas-api
   ```

2. **Check Logs:**
   ```bash
   sudo journalctl -u atlas-api -f
   ```

3. **Test API:**
   ```bash
   curl http://localhost:8080/healthz
   ```

4. **Access Web UI:**
   Open browser: `http://localhost:8080`

5. **Access API Docs:**
   Open browser: `http://localhost:8080/api/docs`

## Service Management

### Start/Stop/Restart

```bash
sudo systemctl start atlas-api
sudo systemctl stop atlas-api
sudo systemctl restart atlas-api
sudo systemctl status atlas-api
```

### View Logs

```bash
# Follow logs
sudo journalctl -u atlas-api -f

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

# Since boot
sudo journalctl -u atlas-api -b
```

### Enable/Disable Auto-Start

```bash
sudo systemctl enable atlas-api   # Enable on boot
sudo systemctl disable atlas-api  # Disable on boot
```

## Configuration

### Environment Variables

Configuration is done via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `ATLAS_HTTP_ADDR` | `:8080` | HTTP server address |
| `ATLAS_DB_PATH` | `data/atlas.db` | SQLite database path |
| `ATLAS_BACKUP_DIR` | `data/backups` | Backup directory |
| `ATLAS_LOG_LEVEL` | `INFO` | Log level (DEBUG, INFO, WARN, ERROR) |
| `ATLAS_LOG_FORMAT` | `text` | Log format (text, json) |
| `ATLAS_JWT_SECRET` | - | JWT signing secret (required) |
| `ATLAS_TLS_ENABLED` | `false` | Enable TLS |
| `ATLAS_TLS_CERT` | - | TLS certificate file |
| `ATLAS_TLS_KEY` | - | TLS private key file |

### Configuration File

Edit `/etc/atlas/atlas.conf` and restart service:

```bash
sudo systemctl restart atlas-api
```

## Uninstallation

### Remove Service

```bash
sudo systemctl stop atlas-api
sudo systemctl disable atlas-api
sudo rm /etc/systemd/system/atlas-api.service
sudo systemctl daemon-reload
```

### Remove Files

```bash
sudo rm -rf /opt/atlas
sudo rm -rf /var/lib/atlas
sudo rm -rf /etc/atlas
sudo rm -rf /var/log/atlas
```

### Remove User

```bash
sudo userdel atlas
```

## Troubleshooting

### Service Won't Start

1. **Check Logs:**
   ```bash
   sudo journalctl -u atlas-api -n 50
   ```

2. **Check Permissions:**
   ```bash
   ls -la /opt/atlas/bin/
   ls -la /var/lib/atlas/
   ```

3. **Check Dependencies:**
   ```bash
   which zpool
   which smbd
   which targetcli
   ```

### Port Already in Use

If port 8080 is already in use:

```bash
# Change port in configuration
echo "ATLAS_HTTP_ADDR=:8443" | sudo tee -a /etc/atlas/atlas.conf
sudo systemctl restart atlas-api
```

### Database Errors

If database errors occur:

```bash
# Check database file permissions
ls -la /var/lib/atlas/atlas.db

# Fix permissions
sudo chown atlas:atlas /var/lib/atlas/atlas.db
sudo chmod 600 /var/lib/atlas/atlas.db
```

### ZFS Not Available

If ZFS commands fail:

```bash
# Load ZFS module
sudo modprobe zfs

# Check ZFS version
zfs --version

# Verify ZFS pools
sudo zpool list
```

## Security Considerations

### Firewall

Configure firewall to allow access:

```bash
# UFW (Ubuntu)
sudo ufw allow 8080/tcp

# firewalld (Fedora/RHEL)
sudo firewall-cmd --add-port=8080/tcp --permanent
sudo firewall-cmd --reload
```

### TLS/HTTPS

Always use HTTPS in production:

1. Obtain valid certificates (Let's Encrypt recommended)
2. Configure TLS in `/etc/atlas/atlas.conf`
3. Restart service

### JWT Secret

Generate a strong JWT secret:

```bash
openssl rand -hex 32
```

Store securely in `/etc/atlas/atlas.conf` with restricted permissions.

## Next Steps

After installation:

1. **Create Admin User**: Set up initial administrator account
2. **Configure Storage**: Create ZFS pools and datasets
3. **Set Up Services**: Configure SMB, NFS, or iSCSI shares
4. **Enable Snapshots**: Configure snapshot policies
5. **Review Security**: Enable TLS, configure firewall
6. **Monitor**: Set up monitoring and alerts

## Support

For issues or questions:

- Check logs: `journalctl -u atlas-api`
- Review documentation: `docs/` directory
- API documentation: `http://localhost:8080/api/docs`