🚀 Quick Start Guide - AudioLab Services Stack¶

Pre-requisites¶

Docker Desktop running
.env file with POSTGRES_PASSWORD set

Step-by-Step Deployment¶

1. Clean Any Existing Containers¶

cd "C:\AudioDev\audio-lab\2 - FOUNDATION\03_INFRA\03_05_containerization\03_06_07_services_stack"

# Stop and remove any existing AudioLab containers
docker stop audiolab_mkdocs audiolab_postgres audiolab_fossflow 2>$null
docker rm audiolab_mkdocs audiolab_postgres audiolab_fossflow 2>$null

2. Build the Stack¶

# Build all services
docker-compose build

Expected output: - ✅ Building postgres - ✅ Building mkdocs - ✅ Pulling fossflow

3. Start the Stack¶

# Start all services in detached mode
docker-compose up -d

Expected output: - ✅ Creating network "audiolab_network" - ✅ Creating audiolab_postgres - ✅ Creating audiolab_mkdocs - ✅ Creating audiolab_fossflow

4. Verify Services¶

# Check running containers
docker ps

You should see 3 containers: - audiolab_postgres (port 5432) - audiolab_mkdocs (port 8000) - audiolab_fossflow (port 8080)

5. Check Health¶

# View logs
docker-compose logs -f

# Press Ctrl+C to exit logs

Look for: - ✅ PostgreSQL: database system is ready to accept connections - ✅ MkDocs: Serving on http://0.0.0.0:8000 - ✅ FossFLOW: Service started (check logs)

6. Access Services¶

Open in browser:

Documentation: http://localhost:8000
Diagrams: http://localhost:8080

Connect to database:

docker exec -it audiolab_postgres psql -U audiolab -d audiolab_main

Common Issues¶

Port Already in Use¶

Symptom: Bind for 0.0.0.0:8000 failed: port is already allocated

Solution:

# Find process using port 8000
netstat -ano | findstr :8000

# Kill process (replace PID with actual process ID)
taskkill /PID <PID> /F

# Or change port in .env file

Container Name Conflict¶

Symptom: Conflict. The container name "/audiolab_mkdocs" is already in use

Solution:

docker rm -f audiolab_mkdocs audiolab_postgres audiolab_fossflow
docker-compose up -d

MkDocs Won't Start¶

Symptom: mkdocs: command not found

Solution:

# Rebuild MkDocs service
docker-compose build mkdocs --no-cache
docker-compose up -d mkdocs

PostgreSQL Password Error¶

Symptom: POSTGRES_PASSWORD must be set

Solution:

# Check .env file exists
cat .env

# If not, create it:
echo "POSTGRES_PASSWORD=SecurePassword123" > .env
docker-compose up -d

Stopping the Stack¶

# Stop all services
docker-compose down

# Stop and remove volumes (⚠️ deletes data)
docker-compose down -v

Testing Database¶

# Enter PostgreSQL container
docker exec -it audiolab_postgres psql -U audiolab -d audiolab_main

# List schemas
\dn

# List tables
\dt audiolab.*

# Check project status view
SELECT * FROM audiolab.project_status;

# Exit
\q

Testing MkDocs¶

# Check MkDocs is running
curl http://localhost:8000

# View MkDocs logs
docker logs audiolab_mkdocs

# Rebuild documentation
docker exec audiolab_mkdocs mkdocs build

Next Steps¶

✅ Verify all 3 services are running
✅ Access MkDocs at http://localhost:8000
✅ Access FossFLOW at http://localhost:8080
✅ Test database connectivity
✅ Create your first diagram in FossFLOW
✅ Write documentation in MkDocs

Last Updated: 2025-10-04 Stack Version: 1.0.0