diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md new file mode 100644 index 0000000..97d6601 --- /dev/null +++ b/docs/INSTALLATION.md @@ -0,0 +1,497 @@ +# 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 \ + sqlite3 \ + golang-go \ + git \ + build-essential +``` + +#### 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` diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..6f62c46 --- /dev/null +++ b/install.sh @@ -0,0 +1,493 @@ +#!/bin/bash +# +# AtlasOS Installation Script +# Installs AtlasOS storage controller on a Linux system +# +# Usage: sudo ./install.sh [options] +# + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# Default values +INSTALL_DIR="/opt/atlas" +DATA_DIR="/var/lib/atlas" +CONFIG_DIR="/etc/atlas" +SERVICE_USER="atlas" +LOG_DIR="/var/log/atlas" +BACKUP_DIR="/var/lib/atlas/backups" +HTTP_ADDR=":8080" +DB_PATH="/var/lib/atlas/atlas.db" +BUILD_BINARIES=true +SKIP_DEPS=false + +# Parse command line arguments +while [[ $# -gt 0 ]]; do + case $1 in + --install-dir) + INSTALL_DIR="$2" + shift 2 + ;; + --data-dir) + DATA_DIR="$2" + shift 2 + ;; + --skip-deps) + SKIP_DEPS=true + shift + ;; + --skip-build) + BUILD_BINARIES=false + shift + ;; + --http-addr) + HTTP_ADDR="$2" + shift 2 + ;; + -h|--help) + echo "AtlasOS Installation Script" + echo "" + echo "Usage: sudo ./install.sh [options]" + echo "" + echo "Options:" + echo " --install-dir DIR Installation directory (default: /opt/atlas)" + echo " --data-dir DIR Data directory (default: /var/lib/atlas)" + echo " --skip-deps Skip dependency installation" + echo " --skip-build Skip building binaries (use existing)" + echo " --http-addr ADDR HTTP address (default: :8080)" + echo " -h, --help Show this help message" + exit 0 + ;; + *) + echo "Unknown option: $1" + exit 1 + ;; + esac +done + +# Check if running as root +if [[ $EUID -ne 0 ]]; then + echo -e "${RED}Error: This script must be run as root (use sudo)${NC}" + exit 1 +fi + +# Detect distribution +detect_distro() { + if [[ -f /etc/os-release ]]; then + . /etc/os-release + DISTRO=$ID + VERSION=$VERSION_ID + else + echo -e "${RED}Error: Cannot detect Linux distribution${NC}" + exit 1 + fi +} + +# Install dependencies +install_dependencies() { + echo -e "${GREEN}Installing dependencies...${NC}" + + case $DISTRO in + ubuntu|debian) + apt-get update + apt-get install -y \ + zfsutils-linux \ + samba \ + nfs-kernel-server \ + targetcli \ + sqlite3 \ + golang-go \ + git \ + build-essential \ + curl + ;; + fedora|rhel|centos) + if command -v dnf &> /dev/null; then + dnf install -y \ + zfs \ + samba \ + nfs-utils \ + targetcli \ + sqlite \ + golang \ + git \ + gcc \ + make \ + curl + else + yum install -y \ + zfs \ + samba \ + nfs-utils \ + targetcli \ + sqlite \ + golang \ + git \ + gcc \ + make \ + curl + fi + ;; + *) + echo -e "${YELLOW}Warning: Unknown distribution. Please install dependencies manually:${NC}" + echo " - ZFS utilities" + echo " - Samba (SMB/CIFS)" + echo " - NFS server" + echo " - targetcli (iSCSI)" + echo " - SQLite" + echo " - Go compiler" + echo " - Build tools" + ;; + esac + + echo -e "${GREEN}Dependencies installed${NC}" +} + +# Create system user +create_user() { + echo -e "${GREEN}Creating system user...${NC}" + + if ! id "$SERVICE_USER" &>/dev/null; then + useradd -r -s /bin/false -d "$DATA_DIR" "$SERVICE_USER" + echo -e "${GREEN}User $SERVICE_USER created${NC}" + else + echo -e "${YELLOW}User $SERVICE_USER already exists${NC}" + fi +} + +# Create directories +create_directories() { + echo -e "${GREEN}Creating directories...${NC}" + + mkdir -p "$INSTALL_DIR/bin" + mkdir -p "$DATA_DIR" + mkdir -p "$CONFIG_DIR" + mkdir -p "$LOG_DIR" + mkdir -p "$BACKUP_DIR" + mkdir -p "$CONFIG_DIR/tls" + + # Set ownership + chown -R "$SERVICE_USER:$SERVICE_USER" "$DATA_DIR" + chown -R "$SERVICE_USER:$SERVICE_USER" "$LOG_DIR" + chown -R "$SERVICE_USER:$SERVICE_USER" "$BACKUP_DIR" + chown -R "$SERVICE_USER:$SERVICE_USER" "$CONFIG_DIR" + + # Set permissions + chmod 755 "$INSTALL_DIR" + chmod 755 "$INSTALL_DIR/bin" + chmod 700 "$DATA_DIR" + chmod 700 "$CONFIG_DIR" + chmod 750 "$LOG_DIR" + chmod 750 "$BACKUP_DIR" + + echo -e "${GREEN}Directories created${NC}" +} + +# Build binaries +build_binaries() { + if [[ "$BUILD_BINARIES" == "false" ]]; then + echo -e "${YELLOW}Skipping binary build${NC}" + return + fi + + echo -e "${GREEN}Building binaries...${NC}" + + # Get script directory + SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + cd "$SCRIPT_DIR" + + # Build binaries + echo "Building atlas-api..." + go build -o "$INSTALL_DIR/bin/atlas-api" ./cmd/atlas-api + + echo "Building atlas-tui..." + go build -o "$INSTALL_DIR/bin/atlas-tui" ./cmd/atlas-tui + + # Set permissions + chown root:root "$INSTALL_DIR/bin/atlas-api" + chown root:root "$INSTALL_DIR/bin/atlas-tui" + chmod 755 "$INSTALL_DIR/bin/atlas-api" + chmod 755 "$INSTALL_DIR/bin/atlas-tui" + + echo -e "${GREEN}Binaries built${NC}" +} + +# Create systemd service +create_systemd_service() { + echo -e "${GREEN}Creating systemd service...${NC}" + + cat > /etc/systemd/system/atlas-api.service < "$CONFIG_DIR/atlas.conf" < /dev/null; then + JWT_SECRET=$(openssl rand -hex 32) + echo "ATLAS_JWT_SECRET=$JWT_SECRET" >> "$CONFIG_DIR/atlas.conf" + echo -e "${GREEN}JWT secret generated${NC}" + else + echo -e "${YELLOW}Warning: openssl not found. Please set ATLAS_JWT_SECRET manually${NC}" + fi +} + +# Setup ZFS (if needed) +setup_zfs() { + echo -e "${GREEN}Checking ZFS...${NC}" + + if ! command -v zpool &> /dev/null; then + echo -e "${YELLOW}Warning: ZFS not found. Please install ZFS utilities${NC}" + return + fi + + # Check if ZFS module is loaded + if ! lsmod | grep -q zfs; then + echo -e "${YELLOW}Warning: ZFS kernel module not loaded${NC}" + echo " Run: modprobe zfs" + fi + + echo -e "${GREEN}ZFS check complete${NC}" +} + +# Setup Samba +setup_samba() { + echo -e "${GREEN}Setting up Samba...${NC}" + + if ! command -v smbd &> /dev/null; then + echo -e "${YELLOW}Warning: Samba not found${NC}" + return + fi + + # Enable and start Samba (if not already) + systemctl enable smbd 2>/dev/null || true + systemctl enable nmbd 2>/dev/null || true + + echo -e "${GREEN}Samba setup complete${NC}" +} + +# Setup NFS +setup_nfs() { + echo -e "${GREEN}Setting up NFS...${NC}" + + if ! command -v exportfs &> /dev/null; then + echo -e "${YELLOW}Warning: NFS not found${NC}" + return + fi + + # Enable and start NFS (if not already) + systemctl enable nfs-server 2>/dev/null || true + systemctl enable rpcbind 2>/dev/null || true + + echo -e "${GREEN}NFS setup complete${NC}" +} + +# Setup iSCSI +setup_iscsi() { + echo -e "${GREEN}Setting up iSCSI...${NC}" + + if ! command -v targetcli &> /dev/null; then + echo -e "${YELLOW}Warning: targetcli not found${NC}" + return + fi + + # Enable and start iSCSI target (if not already) + systemctl enable target 2>/dev/null || true + + echo -e "${GREEN}iSCSI setup complete${NC}" +} + +# Create initial admin user +create_admin_user() { + echo -e "${GREEN}Creating initial admin user...${NC}" + + echo "" + echo -e "${YELLOW}Please set up the initial admin user:${NC}" + echo " Username: admin" + echo " Password: (you will be prompted)" + echo "" + echo "After starting the service, you can create the admin user via:" + echo " curl -X POST http://localhost:8080/api/v1/users \\" + echo " -H 'Content-Type: application/json' \\" + echo " -d '{\"username\":\"admin\",\"password\":\"your-password\",\"role\":\"administrator\"}'" + echo "" + echo "Or use the TUI:" + echo " $INSTALL_DIR/bin/atlas-tui" + echo "" +} + +# Start service +start_service() { + echo -e "${GREEN}Starting AtlasOS service...${NC}" + + systemctl enable atlas-api + systemctl start atlas-api + + # Wait a moment for service to start + sleep 2 + + if systemctl is-active --quiet atlas-api; then + echo -e "${GREEN}AtlasOS service started successfully${NC}" + else + echo -e "${RED}Error: Service failed to start${NC}" + echo "Check logs with: journalctl -u atlas-api -n 50" + exit 1 + fi +} + +# Print summary +print_summary() { + echo "" + echo -e "${GREEN}========================================${NC}" + echo -e "${GREEN}AtlasOS Installation Complete!${NC}" + echo -e "${GREEN}========================================${NC}" + echo "" + echo "Installation Directory: $INSTALL_DIR" + echo "Data Directory: $DATA_DIR" + echo "Config Directory: $CONFIG_DIR" + echo "Log Directory: $LOG_DIR" + echo "" + echo "Service Status:" + systemctl status atlas-api --no-pager -l || true + echo "" + echo "Useful Commands:" + echo " Service: systemctl {start|stop|restart|status} atlas-api" + echo " Logs: journalctl -u atlas-api -f" + echo " TUI: $INSTALL_DIR/bin/atlas-tui" + echo "" + echo "Web Interface:" + echo " http://localhost:8080" + echo "" + echo "API Documentation:" + echo " http://localhost:8080/api/docs" + echo "" + echo -e "${YELLOW}Next Steps:${NC}" + echo "1. Create initial admin user (see instructions above)" + echo "2. Configure TLS certificates (optional)" + echo "3. Review configuration in $CONFIG_DIR/atlas.conf" + echo "" +} + +# Main installation +main() { + echo -e "${GREEN}========================================${NC}" + echo -e "${GREEN}AtlasOS Installation Script${NC}" + echo -e "${GREEN}========================================${NC}" + echo "" + + detect_distro + echo "Detected distribution: $DISTRO $VERSION" + echo "" + + if [[ "$SKIP_DEPS" == "false" ]]; then + install_dependencies + else + echo -e "${YELLOW}Skipping dependency installation${NC}" + fi + + create_user + create_directories + build_binaries + create_config + generate_jwt_secret + create_systemd_service + + setup_zfs + setup_samba + setup_nfs + setup_iscsi + + create_admin_user + + # Ask if user wants to start service + echo "" + read -p "Start AtlasOS service now? (y/n) " -n 1 -r + echo "" + if [[ $REPLY =~ ^[Yy]$ ]]; then + start_service + else + echo -e "${YELLOW}Service not started. Start manually with: systemctl start atlas-api${NC}" + fi + + print_summary +} + +# Run main +main