This commit is contained in:
497
docs/INSTALLATION.md
Normal file
497
docs/INSTALLATION.md
Normal file
@@ -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`
|
||||
Reference in New Issue
Block a user