ASF_tools/asf-cloud-server/TBM_devbench/docs/DEPLOYMENT.md

DevBench Manager - Deployment Guide

Table of Contents

1. Prerequisites
2. Quick Start
3. Detailed Deployment
4. Configuration
5. Verification
6. Troubleshooting
7. Maintenance
8. Backup & Recovery

Prerequisites

Required Software

• Docker: Version 20.10 or higher
• Docker Compose: Version 2.0 or higher
• Git: For cloning the repository
• SSH Access: To remote VM host (asf-server.duckdns.org:49152)

System Requirements

• OS: Linux (Ubuntu 20.04+ recommended), macOS, or Windows with WSL2
• RAM: Minimum 512MB for container
• Disk: Minimum 1GB free space
• Network: Internet connection for Docker images and SSH

Access Requirements

• SSH credentials for VM host
• Domain name configured (optional, for Caddy)
• Port 9090 available (or configure different port)

Quick Start

One-Command Deployment

# Clone the repository
git clone <repository-url>
cd ASF_devbench

# Run deployment script
chmod +x deploy.sh
./deploy.sh

That's it! The application will be available at:

• Direct: http://localhost:9090
• Via Caddy: https://tbm.nabd-co.com (if configured)

Default Credentials

• Username: admin
• Password: admin123

⚠️ Important: Change the default password after first login!

Detailed Deployment

Step 1: Clone Repository

git clone <repository-url>
cd ASF_devbench

Step 2: Review Configuration

Check config.js for default settings:

{
  port: 3001,
  database: { path: './data/devbench.db' },
  session: { secret: 'your-secret-key' },
  defaultAdmin: {
    username: 'admin',
    password: 'admin123',
    email: 'admin@nabd-co.com'
  }
}

Step 3: Set Environment Variables (Optional)

Create .env file:

NODE_ENV=production
PORT=3001
SECRET_KEY=your-secure-secret-key
ADMIN_EMAIL=admin@yourdomain.com
ADMIN_PASSWORD=your-secure-password

Step 4: Prepare Directories

# Create necessary directories
mkdir -p data logs public/downloads

# Set permissions
chmod 755 data logs
chmod +x provision_vm.sh deploy.sh

Step 5: Configure Docker Network

# Create Caddy network (if using reverse proxy)
docker network create caddy_network

Step 6: Deploy with Docker Compose

# Build and start container
docker-compose up -d --build

# Check status
docker-compose ps

# View logs
docker-compose logs -f

Step 7: Verify Deployment

# Check health endpoint
curl http://localhost:9090/health

# Expected response:
# {"status":"ok","timestamp":"2025-11-23T...","version":"1.0.0"}

Configuration

Docker Compose Configuration

Edit docker-compose.yml:

services:
  devbench-manager:
    ports:
      - "9090:3001"  # Change external port here
    environment:
      - NODE_ENV=production
      - SECRET_KEY=${SECRET_KEY:-dev-secret-key}
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
      - ./provision_vm.sh:/app/provision_vm.sh:ro

Caddy Reverse Proxy

Add to your Caddyfile:

tbm.nabd-co.com {
    reverse_proxy devbench-manager:3001
}

Ensure Caddy container is on caddy_network:

# Check Caddy network
docker network inspect caddy_network

# Connect Caddy to network if needed
docker network connect caddy_network caddy-container-name

SSH Configuration

The application connects to the VM host via SSH. Ensure:

1. Host: asf-server.duckdns.org
2. Port: 49152
3. User: asf
4. Password: ASF (configured in provision_vm.sh)

Test SSH connection:

ssh -p 49152 asf@asf-server.duckdns.org

Firewall Configuration

Open required ports:

# For direct access
sudo ufw allow 9090/tcp

# For Caddy (if using)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Verification

1. Container Status

# Check if container is running
docker ps | grep devbench-manager

# Expected output:
# CONTAINER ID   IMAGE                    STATUS         PORTS
# abc123...      devbench-manager:latest  Up 2 minutes   0.0.0.0:9090->3001/tcp

2. Health Check

# Test health endpoint
curl http://localhost:9090/health

# Or with jq for formatted output
curl -s http://localhost:9090/health | jq

3. Network Connectivity

# Check networks
docker inspect devbench-manager --format='{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}'

# Expected: app-network caddy_network

4. Database

# Check if database was created
ls -la data/devbench.db

# Connect to database
docker exec -it devbench-manager sqlite3 /app/data/devbench.db

# Run query
sqlite> SELECT * FROM users;

5. Logs

# View application logs
docker-compose logs -f

# View last 50 lines
docker-compose logs --tail=50

# View specific service
docker-compose logs devbench-manager

6. Web Interface

1. Open browser: http://localhost:9090
2. Login with admin credentials
3. Create a test DevBench
4. Verify real-time log output
5. Check connection information

Troubleshooting

Container Won't Start

Problem: Container exits immediately

Solution:

# Check logs
docker-compose logs

# Common issues:
# 1. Port already in use
sudo lsof -i :9090
# Kill process or change port in docker-compose.yml

# 2. Permission issues
sudo chown -R $USER:$USER data logs

# 3. Missing provision script
ls -la provision_vm.sh
chmod +x provision_vm.sh

Cannot Access Web Interface

Problem: Connection refused or timeout

Solution:

# 1. Check if container is running
docker ps | grep devbench-manager

# 2. Check port mapping
docker port devbench-manager

# 3. Test from inside container
docker exec devbench-manager wget -O- http://localhost:3001/health

# 4. Check firewall
sudo ufw status
sudo ufw allow 9090/tcp

# 5. Check if port is listening
sudo netstat -tlnp | grep 9090

Caddy Proxy Not Working

Problem: Cannot access via domain

Solution:

# 1. Check if both containers are on caddy_network
docker network inspect caddy_network

# 2. Connect devbench-manager to network
docker network connect caddy_network devbench-manager

# 3. Restart Caddy
docker restart caddy-container-name

# 4. Check Caddy logs
docker logs caddy-container-name

# 5. Test from Caddy container
docker exec caddy-container-name wget -O- http://devbench-manager:3001/health

SSH Connection Fails

Problem: Cannot connect to VM host

Solution:

# 1. Test SSH manually
ssh -p 49152 asf@asf-server.duckdns.org

# 2. Check if sshpass is installed in container
docker exec devbench-manager which sshpass

# 3. Check provision script
docker exec devbench-manager cat /app/provision_vm.sh | grep SSH_

# 4. Test from container
docker exec -it devbench-manager bash
./provision_vm.sh status test_vm

Database Errors

Problem: Database locked or corrupted

Solution:

# 1. Stop container
docker-compose down

# 2. Backup database
cp data/devbench.db data/devbench.db.backup

# 3. Check database integrity
sqlite3 data/devbench.db "PRAGMA integrity_check;"

# 4. If corrupted, restore from backup or recreate
rm data/devbench.db
docker-compose up -d

WebSocket Not Working

Problem: Real-time updates not appearing

Solution:

# 1. Check browser console for errors
# Open DevTools → Console

# 2. Verify WebSocket connection
# Look for "WebSocket connected" message

# 3. Check if behind proxy
# Ensure proxy supports WebSocket upgrade

# 4. Test WebSocket endpoint
wscat -c ws://localhost:9090

Maintenance

Regular Tasks

Daily

• Monitor logs for errors
• Check disk space
• Verify health endpoint

Weekly

• Review user activity
• Clean up old logs
• Check for updates

Monthly

• Backup database
• Review security
• Update dependencies

Updating the Application

# 1. Pull latest changes
git pull origin main

# 2. Backup database
cp data/devbench.db data/devbench.db.$(date +%Y%m%d)

# 3. Rebuild and restart
docker-compose down
docker-compose up -d --build

# 4. Verify
curl http://localhost:9090/health

Viewing Logs

# Real-time logs
docker-compose logs -f

# Last 100 lines
docker-compose logs --tail=100

# Specific time range
docker-compose logs --since 2h

# Save logs to file
docker-compose logs > logs/docker-$(date +%Y%m%d).log

Cleaning Up

# Remove stopped containers
docker container prune -f

# Remove unused images
docker image prune -a -f

# Remove unused volumes
docker volume prune -f

# Clean everything
docker system prune -a -f

Scaling (Future)

For multiple instances:

# Scale to 3 instances
docker-compose up -d --scale devbench-manager=3

# Use load balancer (nginx/haproxy)
# Configure session persistence

Backup & Recovery

Backup Strategy

Database Backup

# Manual backup
cp data/devbench.db backups/devbench-$(date +%Y%m%d-%H%M%S).db

# Automated backup script
#!/bin/bash
BACKUP_DIR="backups"
mkdir -p $BACKUP_DIR
cp data/devbench.db $BACKUP_DIR/devbench-$(date +%Y%m%d).db
# Keep only last 7 days
find $BACKUP_DIR -name "devbench-*.db" -mtime +7 -delete

Full Backup

# Backup everything
tar -czf devbench-backup-$(date +%Y%m%d).tar.gz \
  data/ \
  logs/ \
  config.js \
  .env \
  docker-compose.yml

Recovery

Restore Database

# 1. Stop container
docker-compose down

# 2. Restore database
cp backups/devbench-20251123.db data/devbench.db

# 3. Start container
docker-compose up -d

# 4. Verify
curl http://localhost:9090/health

Full Recovery

# 1. Extract backup
tar -xzf devbench-backup-20251123.tar.gz

# 2. Deploy
./deploy.sh

# 3. Verify all services

Disaster Recovery

Complete System Failure

# 1. Fresh installation
git clone <repository-url>
cd ASF_devbench

# 2. Restore backups
cp /backup/location/devbench.db data/
cp /backup/location/.env .

# 3. Deploy
./deploy.sh

# 4. Verify users and DevBenches

Security Hardening

Change Default Credentials

# 1. Login as admin
# 2. Go to admin panel
# 3. Reset admin password
# Or use API:
curl -X POST http://localhost:9090/admin/reset-password/1 \
  -H "Content-Type: application/json" \
  -d '{"newPassword":"new-secure-password"}'

Update Session Secret

Edit .env:

SECRET_KEY=$(openssl rand -base64 32)

Restart:

docker-compose restart

Enable HTTPS

Use Caddy for automatic HTTPS:

tbm.nabd-co.com {
    reverse_proxy devbench-manager:3001
}

Restrict Access

Use firewall:

# Allow only specific IPs
sudo ufw allow from 192.168.1.0/24 to any port 9090

Monitoring

Health Monitoring

# Simple health check script
#!/bin/bash
if curl -sf http://localhost:9090/health > /dev/null; then
  echo "OK"
else
  echo "FAILED"
  # Send alert
fi

Log Monitoring

# Watch for errors
docker-compose logs -f | grep -i error

# Count errors
docker-compose logs | grep -i error | wc -l

Resource Monitoring

# Container stats
docker stats devbench-manager

# Disk usage
du -sh data/ logs/

# Database size
ls -lh data/devbench.db

Performance Tuning

Database Optimization

# Vacuum database
docker exec devbench-manager sqlite3 /app/data/devbench.db "VACUUM;"

# Analyze database
docker exec devbench-manager sqlite3 /app/data/devbench.db "ANALYZE;"

Container Resources

Edit docker-compose.yml:

services:
  devbench-manager:
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

Support

Getting Help

1. Check logs: docker-compose logs
2. Review documentation in /docs
3. Check GitHub issues
4. Contact system administrator

Reporting Issues

Include:

• Docker version: docker --version
• Docker Compose version: docker-compose --version
• Container logs: docker-compose logs
• Error messages
• Steps to reproduce