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/STRUCTURE.md
+++ b/asf-cloud-server/TBM_devbench/docs/STRUCTURE.md
@@ -0,0 +1,530 @@
+# DevBench Manager - Project Structure
+
+## Directory Tree
+
+```
+ASF_devbench/
+├── docs/                           # Documentation
+│   ├── ARCHITECTURE.md            # System architecture
+│   ├── STRUCTURE.md               # This file
+│   ├── DEPLOYMENT.md              # Deployment guide
+│   └── API.md                     # API documentation
+│
+├── public/                         # Static assets
+│   ├── css/
+│   │   └── style.css              # Custom styles + dark theme
+│   ├── images/
+│   │   ├── nabd-logo.svg          # Company logo (light)
+│   │   ├── nabd-logo-white.svg    # Company logo (dark)
+│   │   └── tbm-icon.png           # TBM branding icon
+│   └── downloads/
+│       └── db_vm_ssh_config_manager.exe  # SSH config tool
+│
+├── views/                          # EJS templates
+│   ├── layout.ejs                 # Base layout with navbar
+│   ├── login.ejs                  # Login page
+│   ├── dashboard.ejs              # User dashboard
+│   ├── admin.ejs                  # Admin panel
+│   └── help.ejs                   # Help/documentation page
+│
+├── data/                           # Database storage (created on deploy)
+│   └── devbench.db                # SQLite database
+│
+├── logs/                           # Application logs (created on deploy)
+│   └── *.log                      # Log files
+│
+├── server.js                       # Main application server
+├── config.js                       # Configuration settings
+├── package.json                    # Node.js dependencies
+├── provision_vm.sh                 # VM provisioning script
+│
+├── Dockerfile                      # Docker image definition
+├── docker-compose.yml              # Container orchestration
+├── .dockerignore                   # Docker build exclusions
+│
+├── deploy.sh                       # Deployment script
+├── install.sh                      # Local installation script
+├── start.sh                        # Start script (Docker/Node)
+├── cleanup.sh                      # Cleanup script
+│
+├── .env.example                    # Environment variables template
+├── .gitignore                      # Git exclusions
+├── README.md                       # Main documentation
+└── CHANGELOG.md                    # Change history
+```
+
+## File Descriptions
+
+### Core Application Files
+
+#### `server.js`
+**Purpose**: Main Express.js application server
+
+**Key Components**:
+- Express app initialization
+- Database setup and schema
+- Route definitions
+- WebSocket server
+- Authentication middleware
+- DevBench management logic
+- Provision script executor
+- Status monitoring (60-second interval)
+
+**Dependencies**:
+- express
+- express-session
+- sqlite3
+- bcryptjs
+- ws (WebSocket)
+- child_process (for script execution)
+
+**Key Functions**:
+```javascript
+- requireAuth()           // Authentication middleware
+- requireAdmin()          // Admin authorization middleware
+- executeProvisionScript() // Execute VM provisioning
+- broadcastToUser()       // WebSocket messaging
+```
+
+#### `config.js`
+**Purpose**: Centralized configuration
+
+**Settings**:
+- Server port
+- Database path
+- Session configuration
+- Default admin credentials
+- Validation patterns
+- Provision script settings
+
+#### `provision_vm.sh`
+**Purpose**: VM provisioning and management
+
+**Commands**:
+- `create <vm_name>`: Create new VM
+- `status <vm_name>`: Check VM status
+- `delete <vm_name>`: Delete VM
+- `activate <vm_name>`: Activate VM
+- `start <vm_name>`: Start VM
+- `stop <vm_name>`: Stop VM
+
+**Features**:
+- SSH connection to remote host
+- Output logging
+- Connection info extraction
+- Error handling
+- Timeout management (30 minutes)
+
+### Frontend Files
+
+#### `views/layout.ejs`
+**Purpose**: Base template for all pages
+
+**Features**:
+- Navigation bar with logo
+- Help link
+- Theme toggle button
+- WebSocket initialization
+- Bootstrap and Font Awesome imports
+- Dark theme JavaScript
+
+#### `views/dashboard.ejs`
+**Purpose**: User dashboard
+
+**Features**:
+- DevBench list with cards
+- Create DevBench modal
+- Connection info display (SSH/VNC ports)
+- Real-time log output
+- Status indicators
+- Copy-to-clipboard functionality
+
+#### `views/admin.ejs`
+**Purpose**: Admin panel
+
+**Features**:
+- User management table
+- Add user modal
+- DevBench overview table
+- Password reset
+- User deletion
+- DevBench deletion
+
+#### `views/help.ejs`
+**Purpose**: Help and documentation
+
+**Features**:
+- SSH Config Manager guide
+- Step-by-step instructions
+- Download link for tool
+- Connection information
+- Important notes
+
+#### `views/login.ejs`
+**Purpose**: Authentication page
+
+**Features**:
+- Login form
+- Error messages
+- Branding
+
+### Static Assets
+
+#### `public/css/style.css`
+**Purpose**: Custom styling
+
+**Features**:
+- NABD brand colors
+- Dark theme styles
+- Component styling
+- Responsive design
+- Smooth transitions
+
+#### `public/images/`
+**Purpose**: Image assets
+
+**Files**:
+- `nabd-logo.svg`: Light theme logo
+- `nabd-logo-white.svg`: Dark theme logo
+- `tbm-icon.png`: Branding icon and favicon
+
+#### `public/downloads/`
+**Purpose**: Downloadable files
+
+**Files**:
+- `db_vm_ssh_config_manager.exe`: SSH configuration tool
+
+### Deployment Files
+
+#### `Dockerfile`
+**Purpose**: Docker image definition
+
+**Base Image**: node:18-alpine
+
+**Steps**:
+1. Set working directory
+2. Copy package files
+3. Install dependencies
+4. Copy application files
+5. Create data/logs directories
+6. Expose port 3001
+7. Set start command
+
+#### `docker-compose.yml`
+**Purpose**: Container orchestration
+
+**Configuration**:
+- Service: devbench-manager
+- Port mapping: 9090:3001
+- Volumes: data, logs, provision script
+- Networks: app-network, caddy_network
+- Health check: /health endpoint
+- Restart policy: unless-stopped
+
+#### `deploy.sh`
+**Purpose**: Automated deployment
+
+**Steps**:
+1. Create directories
+2. Set permissions
+3. Clean up old containers
+4. Create Docker network
+5. Build and start container
+6. Wait for startup
+7. Verify health
+8. Display access information
+
+### Configuration Files
+
+#### `package.json`
+**Purpose**: Node.js project configuration
+
+**Scripts**:
+- `start`: Run production server
+- `dev`: Run with nodemon (auto-reload)
+
+**Dependencies**:
+- express: Web framework
+- express-session: Session management
+- bcryptjs: Password hashing
+- sqlite3: Database
+- body-parser: Request parsing
+- ejs: Template engine
+- ws: WebSocket
+- child_process: Script execution
+
+#### `.env.example`
+**Purpose**: Environment variables template
+
+**Variables**:
+- NODE_ENV
+- PORT
+- SECRET_KEY
+- ADMIN_EMAIL
+- ADMIN_PASSWORD
+
+#### `.gitignore`
+**Purpose**: Git exclusions
+
+**Excluded**:
+- node_modules/
+- data/
+- logs/
+- .env
+- *.log
+- .DS_Store
+
+### Utility Scripts
+
+#### `install.sh`
+**Purpose**: Local installation
+
+**Actions**:
+- Check Node.js version
+- Install npm dependencies
+- Display start instructions
+
+#### `start.sh`
+**Purpose**: Start application
+
+**Logic**:
+- Check for Docker
+- Start with Docker Compose if available
+- Fall back to Node.js
+- Install dependencies if needed
+
+#### `cleanup.sh`
+**Purpose**: Clean up containers
+
+**Actions**:
+- Stop containers
+- Remove containers
+- Prune dangling containers
+- List volumes
+
+### Documentation Files
+
+#### `README.md`
+**Purpose**: Main project documentation
+
+**Sections**:
+- Features overview
+- Installation instructions
+- Configuration guide
+- Usage instructions
+- API endpoints
+- Troubleshooting
+
+#### `CHANGELOG.md`
+**Purpose**: Change history
+
+**Content**:
+- Recent updates
+- SSH configuration changes
+- Output format changes
+- New features
+- Migration notes
+
+#### `docs/ARCHITECTURE.md`
+**Purpose**: System architecture
+
+**Content**:
+- Architecture diagrams
+- Component descriptions
+- Data flow
+- Security architecture
+- Technology stack
+
+#### `docs/DEPLOYMENT.md`
+**Purpose**: Deployment guide
+
+**Content**:
+- Prerequisites
+- Deployment steps
+- Configuration
+- Troubleshooting
+- Maintenance
+
+## Data Flow Through Files
+
+### DevBench Creation
+```
+1. views/dashboard.ejs
+   ↓ (User clicks Create)
+2. server.js (POST /create-devbench)
+   ↓ (Validates and creates DB record)
+3. server.js (executeProvisionScript)
+   ↓ (Spawns child process)
+4. provision_vm.sh
+   ↓ (SSH to remote host)
+5. Remote VM Host
+   ↓ (Creates VM, returns info)
+6. provision_vm.sh
+   ↓ (Parses output)
+7. server.js
+   ↓ (Updates database)
+8. WebSocket
+   ↓ (Broadcasts to user)
+9. views/dashboard.ejs
+   ↓ (Updates UI)
+```
+
+### Authentication
+```
+1. views/login.ejs
+   ↓ (User submits form)
+2. server.js (POST /login)
+   ↓ (Validates credentials)
+3. config.js (validation patterns)
+   ↓
+4. server.js (bcrypt compare)
+   ↓ (Creates session)
+5. express-session
+   ↓ (Stores session)
+6. server.js (redirect)
+   ↓
+7. views/dashboard.ejs or views/admin.ejs
+```
+
+### Theme Toggle
+```
+1. views/layout.ejs (Theme toggle button)
+   ↓ (User clicks)
+2. JavaScript (theme toggle handler)
+   ↓ (Toggles class)
+3. public/css/style.css (dark-theme styles)
+   ↓ (Applies styles)
+4. localStorage
+   ↓ (Saves preference)
+```
+
+## Key Directories
+
+### `/data`
+- **Created**: On first deployment
+- **Purpose**: SQLite database storage
+- **Persistence**: Docker volume
+- **Backup**: Copy devbench.db file
+
+### `/logs`
+- **Created**: On first deployment
+- **Purpose**: Application logs
+- **Persistence**: Docker volume
+- **Rotation**: Manual
+
+### `/public`
+- **Purpose**: Static assets served by Express
+- **Access**: Direct URL paths
+- **Caching**: Browser caching enabled
+
+### `/views`
+- **Purpose**: EJS templates
+- **Rendering**: Server-side
+- **Access**: Via routes only
+
+### `/docs`
+- **Purpose**: Project documentation
+- **Format**: Markdown
+- **Access**: File system only
+
+## Configuration Hierarchy
+
+```
+1. Environment Variables (.env)
+   ↓
+2. config.js (defaults)
+   ↓
+3. docker-compose.yml (container env)
+   ↓
+4. Application runtime
+```
+
+## Port Mapping
+
+```
+External → Container → Application
+9090    → 3001      → Express Server
+```
+
+## Network Architecture
+
+```
+Internet
+   ↓
+Caddy (caddy_network)
+   ↓
+DevBench Manager (caddy_network + app-network)
+   ↓
+SQLite (local file)
+   ↓
+SSH (external)
+   ↓
+Remote VM Host
+```
+
+## File Permissions
+
+### Scripts
+- `provision_vm.sh`: 755 (executable)
+- `deploy.sh`: 755 (executable)
+- `install.sh`: 755 (executable)
+- `start.sh`: 755 (executable)
+- `cleanup.sh`: 755 (executable)
+
+### Directories
+- `data/`: 755
+- `logs/`: 755
+- `public/`: 755
+
+### Database
+- `devbench.db`: 644 (read/write for owner)
+
+## Build Process
+
+### Docker Build
+```
+1. Read Dockerfile
+2. Pull node:18-alpine
+3. Copy package.json
+4. npm install
+5. Copy application files
+6. Set permissions
+7. Create image
+```
+
+### Docker Compose
+```
+1. Read docker-compose.yml
+2. Create networks
+3. Build image (if needed)
+4. Create container
+5. Mount volumes
+6. Start container
+7. Run health checks
+```
+
+## Runtime Process
+
+### Container Startup
+```
+1. Docker starts container
+2. Node.js starts
+3. server.js executes
+4. Database initialized
+5. Express server starts
+6. WebSocket server starts
+7. Health check passes
+8. Ready for connections
+```
+
+### Request Handling
+```
+1. Request arrives at Caddy
+2. Proxied to container
+3. Express routes request
+4. Middleware checks auth
+5. Controller handles logic
+6. Database query (if needed)
+7. Template rendered
+8. Response sent
+```