soundwave/docs/PRE_LAUNCH_CHECKLIST.md

🚀 Pre-Launch Checklist - SoundWave Deployment

✅ Required Steps Before Building Container

1. Create Environment File

Status: ⚠️ REQUIRED

Copy the example environment file and customize it:

cd /home/iulian/projects/zi-tube/soundwave
cp .env.example .env

Default Credentials:

• Username: admin
• Password: soundwave
• Elasticsearch Password: soundwave
• Port: 123456

Optional: Customize .env file

nano .env

Edit these values if needed:

• SW_HOST - Change if using different port or domain
• SW_USERNAME - Admin username (default: admin)
• SW_PASSWORD - Admin password (default: soundwave)
• ELASTIC_PASSWORD - Elasticsearch password (default: soundwave)
• TZ - Your timezone (default: UTC)

2. Create Database Migrations

Status: ⚠️ REQUIRED

The local audio files feature has new models that need migrations:

# Start only the database services first
docker compose up -d soundwave-es soundwave-redis

# Wait 30 seconds for Elasticsearch to initialize
sleep 30

# Create migrations (run from host or inside container)
cd backend
python manage.py makemigrations audio
python manage.py migrate

# OR if you prefer to do it after container starts:
docker compose up -d soundwave
docker exec -it soundwave python manage.py makemigrations audio
docker exec -it soundwave python manage.py migrate

3. Verify Python Dependencies

Status: ✅ ALREADY CONFIGURED

All required packages are in requirements.txt:

• ✅ mutagen>=1.47.0 - Audio metadata extraction (local files)
• ✅ pylast>=5.2.0 - Last.fm API client (artwork)
• ✅ All other dependencies present

4. Build Frontend

Status: ⚠️ REQUIRED

Build the React frontend before starting container:

cd frontend
npm install
npm run build

The build output goes to frontend/dist/ which will be served by Django.

5. Create Required Directories

Status: ⚠️ RECOMMENDED

Ensure volume directories exist with proper permissions:

cd /home/iulian/projects/zi-tube/soundwave
mkdir -p audio cache es redis
chmod -R 755 audio cache es redis

📋 Complete Setup Script

Run this complete setup script:

#!/bin/bash
set -e

echo "🚀 SoundWave - Pre-Launch Setup"
echo "================================"
echo ""

# Navigate to project directory
cd /home/iulian/projects/zi-tube/soundwave

# Step 1: Create .env file
echo "📝 Step 1/5: Creating environment file..."
if [ ! -f .env ]; then
    cp .env.example .env
    echo "✅ Created .env file with default settings"
else
    echo "ℹ️  .env file already exists"
fi

# Step 2: Create directories
echo ""
echo "📁 Step 2/5: Creating volume directories..."
mkdir -p audio cache es redis
chmod -R 755 audio cache es redis
echo "✅ Directories created"

# Step 3: Build frontend
echo ""
echo "⚛️  Step 3/5: Building React frontend..."
cd frontend
npm install
npm run build
cd ..
echo "✅ Frontend built successfully"

# Step 4: Start database services
echo ""
echo "🗄️  Step 4/5: Starting database services..."
docker compose up -d soundwave-es soundwave-redis
echo "⏳ Waiting 30 seconds for Elasticsearch to initialize..."
sleep 30
echo "✅ Database services ready"

# Step 5: Start main application
echo ""
echo "🚀 Step 5/5: Starting SoundWave application..."
docker compose up -d soundwave
echo "⏳ Waiting for application to start..."
sleep 10

# Run migrations
echo ""
echo "🔄 Running database migrations..."
docker exec -it soundwave python manage.py makemigrations audio
docker exec -it soundwave python manage.py migrate
echo "✅ Migrations completed"

# Create superuser (optional)
echo ""
echo "👤 Creating admin user..."
docker exec -it soundwave python manage.py shell -c "
from django.contrib.auth import get_user_model
User = get_user_model()
if not User.objects.filter(username='admin').exists():
    User.objects.create_superuser('admin', 'admin@soundwave.local', 'soundwave')
    print('✅ Admin user created')
else:
    print('ℹ️  Admin user already exists')
"

echo ""
echo "🎉 Setup Complete!"
echo "=================="
echo ""
echo "🌐 Application: http://localhost:123456"
echo "👤 Username: admin"
echo "🔑 Password: soundwave"
echo ""
echo "📊 To view logs:"
echo "   docker compose logs -f soundwave"
echo ""
echo "🛑 To stop:"
echo "   docker compose down"
echo ""

Save this as setup.sh and run:

chmod +x setup.sh
./setup.sh

🔐 Default Credentials

Admin User

• Username: admin
• Password: soundwave
• URL: http://localhost:123456

Elasticsearch

• Password: soundwave
• Port: 92000 (internal)
• URL: http://soundwave-es:92000 (internal)

Redis

• Port: 6379 (internal)
• No password required

📊 Port Configuration

Current ports in docker-compose.yml:

• Application: 123456 → 8888 (mapped to host)
• Elasticsearch: 92000 (internal only)
• Redis: 6379 (internal only)

To change the external port, edit docker-compose.yml:

ports:
  - "YOUR_PORT:8888"  # Change YOUR_PORT to desired port

🗂️ Volume Mounts

Data persisted in these directories:

• ./audio → User audio files, YouTube downloads
• ./cache → Application cache
• ./es → Elasticsearch data
• ./redis → Redis persistence

⚠️ Important: Don't delete these directories - they contain your data!

🔧 Environment Variables Reference

Required Variables

SW_HOST=http://localhost:123456          # Application URL
SW_USERNAME=admin                         # Admin username
SW_PASSWORD=soundwave                     # Admin password
ELASTIC_PASSWORD=soundwave                # Elasticsearch password
REDIS_HOST=soundwave-redis                # Redis hostname
ES_URL=http://soundwave-es:92000         # Elasticsearch URL
TZ=UTC                                   # Timezone

Optional Variables

SW_AUTO_UPDATE_YTDLP=true                # Auto-update yt-dlp
DJANGO_DEBUG=false                        # Debug mode (keep false in production)

# Last.fm API (for metadata and artwork)
LASTFM_API_KEY=6220a784c283f5df39fbf5fd9d9ffeb9
LASTFM_API_SECRET=                       # Your secret here

# Fanart.tv API (for high quality artwork)
FANART_API_KEY=73854834d14a5f351bb2233fc3c9d755

Getting API Keys

Last.fm API:

1. Visit: https://www.last.fm/api/account/create
2. Fill in application details
3. Copy API Key and Secret to .env

Fanart.tv API:

1. Visit: https://fanart.tv/get-an-api-key/
2. Register for personal API key
3. Copy API Key to .env

🧪 Testing Checklist

After starting the container, verify:

1. Container Health

docker compose ps
# All services should be "Up"

2. Application Logs

docker compose logs -f soundwave
# Should see "Starting development server at http://0.0.0.0:8888/"

3. Web Access

Visit http://localhost:123456

• ✅ Page loads
• ✅ Can login with admin/soundwave
• ✅ No console errors

4. Database Connection

docker exec -it soundwave python manage.py dbshell
# Should connect to database without errors

5. Elasticsearch Health

curl -u elastic:soundwave http://localhost:123456/api/health/
# Should return health status

6. Test Each Feature

Local Files Upload:

• Navigate to Local Files page
• Upload a test audio file
• Verify metadata extraction works
• Check file appears in list

PWA Features:

• Open Chrome DevTools > Application > Manifest
• Verify all icons load
• Check service worker registered
• Test offline mode

Media Controls:

• Play any audio
• Check native controls appear (notification tray)
• Test play/pause from system controls

🐛 Troubleshooting

Issue: .env file not found

cp .env.example .env

Issue: Port already in use

# Find what's using port 123456
sudo lsof -i :123456

# Change port in docker-compose.yml
nano docker-compose.yml
# Edit: "YOUR_PORT:8888"

Issue: Elasticsearch won't start

# Increase vm.max_map_count
sudo sysctl -w vm.max_map_count=262144

# Make permanent
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

Issue: Permission denied on volumes

sudo chown -R $USER:$USER audio cache es redis
chmod -R 755 audio cache es redis

Issue: Migrations fail

# Reset migrations (WARNING: loses data)
docker compose down -v
rm -rf backend/audio/migrations/00*.py
docker compose up -d
docker exec -it soundwave python manage.py makemigrations audio
docker exec -it soundwave python manage.py migrate

Issue: Frontend not loading

cd frontend
npm run build
docker compose restart soundwave

📝 Summary

Before running docker compose up:

1. ✅ Copy .env.example to .env
2. ✅ Create volume directories (audio, cache, es, redis)
3. ✅ Build frontend (cd frontend && npm install && npm run build)
4. ✅ Start database services first
5. ✅ Run migrations after containers start
6. ✅ Test application at http://localhost:123456

Quick Start (One Command):

cp .env.example .env && \
mkdir -p audio cache es redis && \
cd frontend && npm install && npm run build && cd .. && \
docker compose up -d

Then run migrations:

sleep 30  # Wait for services
docker exec -it soundwave python manage.py makemigrations audio
docker exec -it soundwave python manage.py migrate

Access the app:

• URL: http://localhost:123456
• Username: admin
• Password: soundwave

🎉 You're ready to launch!