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:

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

# Run installer (requires root)
sudo ./installer/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

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

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

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

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

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

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

Manual Installation

Step 1: Install Dependencies

Ubuntu/Debian

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

# 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

# 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

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

Step 4: Create Directories

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

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:

[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:

sudo systemctl daemon-reload
sudo systemctl enable atlas-api

Step 7: Configure Environment

Create /etc/atlas/atlas.conf:

# 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

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:

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:

/opt/atlas/bin/atlas-tui

Configure TLS (Optional)

1. Generate or obtain TLS certificates

2. Place certificates in /etc/atlas/tls/:

   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:

   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:

   sudo systemctl restart atlas-api
   

Verify Installation

1. Check Service Status:

   sudo systemctl status atlas-api
   

2. Check Logs:

   sudo journalctl -u atlas-api -f
   

3. Test API:

   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

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

View Logs

# 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

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:

sudo systemctl restart atlas-api

Uninstallation

Remove Service

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

Remove Files

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

Remove User

sudo userdel atlas

Troubleshooting

Service Won't Start

1. Check Logs:

   sudo journalctl -u atlas-api -n 50
   

2. Check Permissions:

   ls -la /opt/atlas/bin/
   ls -la /var/lib/atlas/
   

3. Check Dependencies:

   which zpool
   which smbd
   which targetcli
   

Port Already in Use

If port 8080 is already in use:

# 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:

# 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:

# 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:

# 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:

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