glenn
/
asteroid
mirror of https://github.com/glenneth1/asteroid.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
asteroid/docs/INSTALLATION.org

16 KiB
Raw Blame History

Asteroid Radio - Installation Guide

Installation Overview

This guide covers the complete installation and deployment of Asteroid Radio. The recommended approach is Docker-based installation for easy deployment and consistency. Native installation is also available for development or custom deployments.

Quick Start (Docker - Recommended)

Prerequisites Check 

# Check if Docker is installed and running
docker --version
docker compose version
docker info

One-Command Setup 

# Clone and setup
git clone https://github.com/fade/asteroid asteroid-radio
cd asteroid-radio/docker
docker compose up -d

Verify Installation 

# Check all three streams are working
curl -I http://localhost:8000/asteroid.mp3     # 128kbps MP3
curl -I http://localhost:8000/asteroid.aac     # 96kbps AAC
curl -I http://localhost:8000/asteroid-low.mp3 # 64kbps MP3

Detailed Installation

System Requirements

Docker Installation Requirements

  • OS: Any OS with Docker support (Linux, macOS, Windows)
  • Docker: Docker Engine 20.10+ and Docker Compose 2.0+
  • RAM: 2GB minimum, 4GB recommended
  • Storage: 20GB minimum, 500GB+ for music library
  • CPU: 2 cores minimum, 4+ cores recommended
  • Network: Stable internet connection for streaming

Native Installation Requirements (Advanced)

  • OS: Ubuntu 20.04+ / Debian 11+ (for native installation)
  • RAM: 1GB minimum, 2GB recommended
  • Storage: 10GB minimum, 100GB+ for music library
  • CPU: 1 core minimum, 2+ cores recommended
  • Dependencies: SBCL, Icecast2, Liquidsoap, TagLib

Docker Installation (Recommended)

Step 1: Install Docker 

# Ubuntu/Debian
sudo apt update
sudo apt install -y docker.io docker compose
sudo usermod -a -G docker $USER
# Log out and back in for group changes

# CentOS/RHEL
sudo dnf install -y docker docker compose
sudo systemctl enable --now docker
sudo usermod -a -G docker $USER

# macOS
brew install docker docker compose
# Or install Docker Desktop

# Windows
# Install Docker Desktop from docker.com

Step 2: Clone and Setup 

# Clone repository
git clone <repository-url> asteroid-radio
cd asteroid-radio/docker

# Start services
docker compose up -d

# Check status
docker compose ps

Step 3: Add Music 

# Copy music files to the docker music directory
cp ~/path/to/music/*.mp3 music/
cp ~/path/to/music/*.flac music/

# Set proper permissions
sudo chown -R $USER:$USER music/

Step 4: Access Streams

Native Installation (Advanced Users)

Step 1: System Updates 

sudo apt update && sudo apt upgrade -y

Step 2: Install System Dependencies 

# Core dependencies
sudo apt install -y sbcl git curl wget build-essential

# Streaming dependencies
sudo apt install -y icecast2 liquidsoap

# Audio processing dependencies
sudo apt install -y libtag1-dev libtagc0-dev

# Optional: Development tools
sudo apt install -y emacs vim htop tree

Step 3: Configure Icecast2 

# Configure Icecast2 during installation
sudo dpkg-reconfigure icecast2

# Or manually edit configuration
sudo nano /etc/icecast2/icecast.xml

Icecast2 Configuration:

<icecast>
    <location>Asteroid Radio Station</location>
    <admin>admin@asteroid-radio.local</admin>
    
    <limits>
        <clients>100</clients>
        <sources>2</sources>
        <queue-size>524288</queue-size>
        <client-timeout>30</client-timeout>
        <header-timeout>15</header-timeout>
        <source-timeout>10</source-timeout>
    </limits>
    
    <authentication>
        <source-password>b3l0wz3r0</source-password>
        <relay-password>asteroid_relay_2024</relay-password>
        <admin-user>admin</admin-user>
        <admin-password>asteroid_admin_2024</admin-password>
    </authentication>
    
    <hostname>localhost</hostname>
    <listen-socket>
        <port>8000</port>
    </listen-socket>
    
    <mount type="normal">
        <mount-name>/asteroid.mp3</mount-name>
        <username>source</username>
        <password>b3l0wz3r0</password>
        <max-listeners>50</max-listeners>
        <dump-file>/var/log/icecast2/asteroid.dump</dump-file>
        <burst-on-connect>1</burst-on-connect>
        <fallback-mount>/silence.mp3</fallback-mount>
        <fallback-override>1</fallback-override>
    </mount>
    
    <fileserve>1</fileserve>
    <paths>
        <basedir>/usr/share/icecast2</basedir>
        <logdir>/var/log/icecast2</logdir>
        <webroot>/usr/share/icecast2/web</webroot>
        <adminroot>/usr/share/icecast2/admin</adminroot>
        <alias source="/" destination="/status.xsl"/>
    </paths>
    
    <logging>
        <accesslog>access.log</accesslog>
        <errorlog>error.log</errorlog>
        <loglevel>3</loglevel>
        <logsize>10000</logsize>
    </logging>
</icecast>

Step 4: Install Quicklisp 

# Download and install Quicklisp
cd /tmp
curl -O https://beta.quicklisp.org/quicklisp.lisp
sbcl --load quicklisp.lisp --eval "(quicklisp-quickstart:install)" --eval "(ql:add-to-init-file)" --quit

Step 5: Clone and Setup Project 

# Clone repository
git clone https://github.com/fade/asteroid /opt/asteroid-radio
cd /opt/asteroid-radio

# Create required directories
sudo mkdir -p music/incoming music/library static template
sudo chown -R $USER:$USER music/

# Set permissions
chmod 755 music/incoming music/library
chmod +x *.sh

Step 6: Install Lisp Dependencies 

# Start SBCL and install dependencies
sbcl --eval "(ql:quickload :asteroid)" --quit

CentOS/RHEL Installation

Step 1: Enable EPEL Repository 

sudo dnf install -y epel-release
sudo dnf update -y

Step 2: Install Dependencies 

# Core dependencies
sudo dnf install -y sbcl git curl wget gcc make

# Streaming dependencies (may require additional repositories)
sudo dnf install -y icecast liquidsoap

# Audio processing
sudo dnf install -y taglib-devel

Step 3: Follow Ubuntu Steps 3-6

The remaining steps are similar to Ubuntu installation.

macOS Installation (Development Only)

Step 1: Install Homebrew 

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Step 2: Install Dependencies 

# Core dependencies
brew install sbcl git

# Streaming dependencies
brew install icecast2 liquidsoap

# Audio processing
brew install taglib

Step 3: Follow Similar Setup Steps

Adapt the Linux steps for macOS paths and conventions.

Service Configuration

Systemd Service Setup (Linux)

Icecast2 Service 

# Enable and start Icecast2
sudo systemctl enable icecast2
sudo systemctl start icecast2
sudo systemctl status icecast2

Asteroid Radio Service

Create systemd service file:

sudo nano /etc/systemd/system/asteroid-radio.service

Service Configuration:

[Unit]
Description=Asteroid Radio Streaming Service
After=network.target icecast2.service
Requires=icecast2.service

[Service]
Type=forking
User=asteroid
Group=asteroid
WorkingDirectory=/opt/asteroid-radio
ExecStart=/opt/asteroid-radio/start-asteroid-radio.sh
ExecStop=/opt/asteroid-radio/stop-asteroid-radio.sh
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and Start Service 

# Create service user
sudo useradd -r -s /bin/false asteroid
sudo chown -R asteroid:asteroid /opt/asteroid-radio

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable asteroid-radio
sudo systemctl start asteroid-radio
sudo systemctl status asteroid-radio

Network Configuration

Firewall Setup

Ubuntu/Debian (ufw) 

# Allow required ports
sudo ufw allow 8000/tcp  # Icecast2 streaming and admin
sudo ufw allow 1234/tcp  # Liquidsoap telnet control (optional)
sudo ufw enable

CentOS/RHEL (firewalld) 

# Allow required ports
sudo firewall-cmd --permanent --add-port=8000/tcp  # Icecast2
sudo firewall-cmd --permanent --add-port=1234/tcp  # Liquidsoap telnet (optional)
sudo firewall-cmd --reload

Reverse Proxy Setup (Optional)

Nginx Configuration 

# Install Nginx
sudo apt install nginx

# Create configuration
sudo nano /etc/nginx/sites-available/asteroid-radio

Nginx Configuration:

server {
    listen 80;
    server_name your-domain.com;
    
    # Web interface
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    
    # Streaming endpoint
    location /stream {
        proxy_pass http://localhost:8000/asteroid.mp3;
        proxy_set_header Host $host;
        proxy_buffering off;
    }
}

Enable Nginx Site 

sudo ln -s /etc/nginx/sites-available/asteroid-radio /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Docker Management

Stream Services

The stream services can be managed using docker from inside the docker folder on this repository.

Container Management 

# Start services
docker compose up -d

# Stop services
docker compose down

# View logs
docker compose logs -f

# Restart services
docker compose restart

Docker Configuration

See docker/docker-compose.yml for complete Docker setup with Icecast2 and Liquidsoap containers. The setup includes:

  • Icecast2: Streaming server with three output formats
  • Liquidsoap: Audio processing and stream generation
  • Music Volume: Mounted to the ./music/library directory (can also be set with the MUSIC_LIBRARY environment variable)
  • Queue Playlist: Mounted to the ./stream-queue.m3u file (can also be set with the QUEUE_PLAYLIST environment variable)

Asteroid Radio Application

The asteroid radio application can also be served and managed using docker from inside the docker folder on this repository.

Container Management 

# Build service
docker compose -f docker-compose.asteroid.yml build

# Start service
docker compose -f docker-compose.asteroid.yml up -d

# Stop service
docker compose -f docker-compose.asteroid.yml down

# View logs
docker compose -f docker-compose.asteroid.yml logs -f

# Restart service
docker compose -f docker-compose.asteroid.yml restart

Docker Configuration

See docker/docker-compose.asteroid.yml for complete Docker setup, which includes:

  • Buils the application using the current cloned branch for the repository
  • Uses the host network for easy access to the stream endpoint
  • Stream endpoint mapped to http://localhost:8000 (can also be set with the ASTEROID_STREAM_URL environment variable)
  • Music Volume: Mounted to the ./music/library directory (can also be set with the MUSIC_LIBRARY environment variable)
  • Queue Playlist: Mounted to the ./stream-queue.m3u file (can also be set with the QUEUE_PLAYLIST environment variable)

Initial Configuration

First-Time Setup

Access Streaming Services

  1. Icecast Admin: http://localhost:8000/admin/ (admin/asteroid_admin_2024)

  2. Stream URLs:

  3. Telnet Control: telnet localhost 1234 (for Liquidsoap management)

Add Music Library 

# Copy music files to music directory
cp ~/path/to/music/*.mp3 ~/asteroid-radio/music/

# Files are automatically detected by Liquidsoap
# No additional processing needed - just add files to the music directory

Test Streaming 

# Test all streams with curl
curl -I http://localhost:8000/asteroid.mp3     # 128kbps MP3
curl -I http://localhost:8000/asteroid.aac     # 96kbps AAC
curl -I http://localhost:8000/asteroid-low.mp3 # 64kbps MP3

# Test with media player
vlc http://localhost:8000/asteroid.mp3         # High quality MP3
vlc http://localhost:8000/asteroid.aac         # High quality AAC

Configuration Files

Key Configuration Locations

Docker Setup:

  • docker/asteroid-radio-docker.liq - Liquidsoap streaming configuration
  • docker/icecast.xml - Icecast2 server settings
  • docker/docker-compose.yml - Container orchestration

Native Setup:

  • asteroid-radio.liq - Liquidsoap streaming configuration
  • /etc/icecast2/icecast.xml - Icecast2 server settings
  • radiance-core.conf.lisp - RADIANCE framework configuration

Production Deployment

Security Considerations

Change Default Passwords

  • Update Icecast2 admin password
  • Change streaming source password
  • Secure database access if using external DB

File Permissions 

# Secure file permissions
sudo chown -R asteroid:asteroid /opt/asteroid-radio
sudo chmod 750 /opt/asteroid-radio
sudo chmod 640 /opt/asteroid-radio/config/*

Network Security

  • Use HTTPS with SSL certificates
  • Implement rate limiting
  • Configure fail2ban for brute force protection

Performance Tuning

System Limits 

# Increase file descriptor limits
echo "asteroid soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "asteroid hard nofile 65536" | sudo tee -a /etc/security/limits.conf

Icecast2 Optimization

  • Adjust client limits based on server capacity
  • Configure appropriate buffer sizes
  • Enable burst-on-connect for better user experience

Monitoring Setup

Log Monitoring 

# Docker setup - monitor container logs
docker compose logs -f icecast
docker compose logs -f liquidsoap

# Native setup - monitor system logs  
sudo tail -f /var/log/icecast2/error.log
sudo tail -f /var/log/asteroid-radio/asteroid.log

Health Checks 

# Create health check script
cat > ~/asteroid-radio/health-check.sh << 'EOF'
#!/bin/bash
# Check all three streams
curl -I http://localhost:8000/asteroid.mp3 | grep -q "200 OK" || exit 1
curl -I http://localhost:8000/asteroid.aac | grep -q "200 OK" || exit 1
curl -I http://localhost:8000/asteroid-low.mp3 | grep -q "200 OK" || exit 1
# Check Icecast admin interface
curl -f http://localhost:8000/admin/ || exit 1
EOF
chmod +x ~/asteroid-radio/health-check.sh

Troubleshooting

Common Installation Issues

Dependency Problems

  • Ensure all system packages are installed
  • Check Quicklisp installation
  • Verify SBCL can load all required libraries

Permission Issues

  • Check file ownership and permissions
  • Verify service user has access to required directories
  • Ensure music directories are writable

Network Issues

  • Confirm firewall allows required ports
  • Check service binding addresses
  • Verify no port conflicts with other services

Streaming Issues

  • Check Icecast2 configuration and logs
  • Verify Liquidsoap can access music files
  • Test stream connectivity from different networks

Getting Support

  • Check project documentation and FAQ
  • Review system logs for error messages
  • Submit issues with detailed system information
  • Join our IRC chat room: #asteroid.music on irc.libera.chat
  • Join community discussions for help

Maintenance

Regular Maintenance Tasks

  • Update system packages monthly
  • Monitor disk space for music library
  • Review and rotate log files
  • Backup configuration files
  • Test streaming functionality

Updates and Upgrades

  • Follow project release notes
  • Test updates in development environment first
  • Backup before major upgrades
  • Monitor service status after updates

This installation guide provides comprehensive setup instructions for Asteroid Radio. For development-specific setup, see the Development Guide.