init tools repo

2025-11-23 19:57:05 +01:00
commit d778206940
35 changed files with 6197 additions and 0 deletions
--- a/asf-cloud-server/TBM_devbench/docs/DEPLOYMENT.md
+++ b/asf-cloud-server/TBM_devbench/docs/DEPLOYMENT.md
@@ -0,0 +1,679 @@
+# DevBench Manager - Deployment Guide
+
+## Table of Contents
+1. [Prerequisites](#prerequisites)
+2. [Quick Start](#quick-start)
+3. [Detailed Deployment](#detailed-deployment)
+4. [Configuration](#configuration)
+5. [Verification](#verification)
+6. [Troubleshooting](#troubleshooting)
+7. [Maintenance](#maintenance)
+8. [Backup & Recovery](#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
+
+```bash
+# 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
+
+```bash
+git clone <repository-url>
+cd ASF_devbench
+```
+
+### Step 2: Review Configuration
+
+Check `config.js` for default settings:
+```javascript
+{
+  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:
+```bash
+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
+
+```bash
+# 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
+
+```bash
+# Create Caddy network (if using reverse proxy)
+docker network create caddy_network
+```
+
+### Step 6: Deploy with Docker Compose
+
+```bash
+# Build and start container
+docker-compose up -d --build
+
+# Check status
+docker-compose ps
+
+# View logs
+docker-compose logs -f
+```
+
+### Step 7: Verify Deployment
+
+```bash
+# 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`:
+
+```yaml
+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`:
+
+```bash
+# 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:
+```bash
+ssh -p 49152 asf@asf-server.duckdns.org
+```
+
+### Firewall Configuration
+
+Open required ports:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# Test health endpoint
+curl http://localhost:9090/health
+
+# Or with jq for formatted output
+curl -s http://localhost:9090/health | jq
+```
+
+### 3. Network Connectivity
+
+```bash
+# Check networks
+docker inspect devbench-manager --format='{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}'
+
+# Expected: app-network caddy_network
+```
+
+### 4. Database
+
+```bash
+# 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
+
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# Backup everything
+tar -czf devbench-backup-$(date +%Y%m%d).tar.gz \
+  data/ \
+  logs/ \
+  config.js \
+  .env \
+  docker-compose.yml
+```
+
+### Recovery
+
+#### Restore Database
+
+```bash
+# 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
+
+```bash
+# 1. Extract backup
+tar -xzf devbench-backup-20251123.tar.gz
+
+# 2. Deploy
+./deploy.sh
+
+# 3. Verify all services
+```
+
+### Disaster Recovery
+
+#### Complete System Failure
+
+```bash
+# 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
+
+```bash
+# 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`:
+```bash
+SECRET_KEY=$(openssl rand -base64 32)
+```
+
+Restart:
+```bash
+docker-compose restart
+```
+
+### Enable HTTPS
+
+Use Caddy for automatic HTTPS:
+```
+tbm.nabd-co.com {
+    reverse_proxy devbench-manager:3001
+}
+```
+
+### Restrict Access
+
+Use firewall:
+```bash
+# Allow only specific IPs
+sudo ufw allow from 192.168.1.0/24 to any port 9090
+```
+
+## Monitoring
+
+### Health Monitoring
+
+```bash
+# 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
+
+```bash
+# Watch for errors
+docker-compose logs -f | grep -i error
+
+# Count errors
+docker-compose logs | grep -i error | wc -l
+```
+
+### Resource Monitoring
+
+```bash
+# Container stats
+docker stats devbench-manager
+
+# Disk usage
+du -sh data/ logs/
+
+# Database size
+ls -lh data/devbench.db
+```
+
+## Performance Tuning
+
+### Database Optimization
+
+```bash
+# 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`:
+```yaml
+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