ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
Add Phase 1 execution plan for Docker & Domain debugging
Juan Denisba4f4213c959
diff --git a/.planning/STATE.md b/.planning/STATE.mdindex 563b9671..a46a89e2 100644--- a/.planning/STATE.md+++ b/.planning/STATE.md@@ -3,14 +3,14 @@## Current Status- **Milestone**: 1 - Infrastructure Fixes, Private URLs & UI Polish- **Current Phase**: 1 - Docker & Domain Debugging-- **Phase Status**: Not Started+- **Phase Status**: Planned (Ready for Execution)- **Last Updated**: 2026-01-19## Phase Progress| Phase | Status | Started | Completed ||-------|--------|---------|-----------|-| 1 | pending | - | - |+| 1 | planned | 2026-01-19 | - || 2 | pending | - | - || 3 | pending | - | - || 4 | pending | - | - |diff --git a/.planning/phases/01-docker-domain-debugging/phase-1-PLAN.md b/.planning/phases/01-docker-domain-debugging/phase-1-PLAN.mdnew file mode 100644index 00000000..c856e420--- /dev/null+++ b/.planning/phases/01-docker-domain-debugging/phase-1-PLAN.md@@ -0,0 +1,434 @@+# Phase 1: Docker & Domain Debugging - Execution Plan++## Objective+Fix the critical issue where Docker apps are not accessible via connected domains. Traffic should flow: **Browser → Domain → Nginx → localhost:{port} → Docker Container**++## Problem Analysis++After reviewing the codebase, I identified the following potential issues:++### Issue 1: Port Mapping in Docker Compose+**Location**: `template_service.py:377-508` (install_template method)++The template service:+1. Generates `docker-compose.yml` from template+2. Stores port in Application model from variables (`PORT`, `HTTP_PORT`, `WEB_PORT`)+3. Runs `docker compose up`++**Problem**: The port stored in the Application model is the **host port** (good), but we need to verify the docker-compose.yml actually maps `host:container` correctly.++### Issue 2: Nginx Config Generation+**Location**: `nginx_service.py:115-138` (DOCKER_SITE_TEMPLATE)++```nginx+location / {+ proxy_pass http://127.0.0.1:{port};+ ...+}+```++**Current flow**:+1. User creates domain via `POST /api/v1/domains`+2. `domains.py:106-124` calls `NginxService.create_site()` for Docker apps+3. Creates config in `/etc/nginx/sites-available/{app_name}`+4. Enables site (symlink to `sites-enabled`)+5. Reloads Nginx++**Potential Issues**:+- Config might fail silently+- Port from Application model might be None or wrong+- Symlink might not be created+- Nginx reload might fail++### Issue 3: Missing Diagnostic Information+There's no way to:+- Check if a port is accessible on localhost+- View the generated Nginx config+- Test the proxy connection+- See container port bindings in the UI++---++## Execution Context++### Files to Modify+```+backend/app/services/nginx_service.py # Add diagnostic methods+backend/app/services/docker_service.py # Add port inspection+backend/app/api/domains.py # Add debug endpoints+backend/app/api/apps.py # Enhance status with port info+frontend/src/pages/ApplicationDetail.jsx # Add diagnostic UI+```++### Dependencies+- Python: socket, subprocess (already available)+- Frontend: Existing API service++---++## Tasks++### Task 1: Add Port Accessibility Check+**File**: `backend/app/services/docker_service.py`++Add method to check if a port is accessible:++```python+@staticmethod+def check_port_accessible(port: int, host: str = '127.0.0.1') -> Dict:+ """Check if a port is accessible (something is listening)."""+ import socket+ try:+ sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)+ sock.settimeout(2)+ result = sock.connect_ex((host, port))+ sock.close()+ return {+ 'accessible': result == 0,+ 'port': port,+ 'host': host+ }+ except Exception as e:+ return {'accessible': False, 'error': str(e)}++@staticmethod+def get_container_port_bindings(container_name: str) -> Dict:+ """Get port bindings for a container."""+ try:+ result = subprocess.run(+ ['docker', 'inspect', '--format', '{{json .NetworkSettings.Ports}}', container_name],+ capture_output=True, text=True+ )+ if result.returncode == 0:+ ports = json.loads(result.stdout.strip())+ return {'success': True, 'ports': ports}+ return {'success': False, 'error': result.stderr}+ except Exception as e:+ return {'success': False, 'error': str(e)}+```++**Verification**: Unit test with a known running container++---++### Task 2: Add Nginx Config Diagnostics+**File**: `backend/app/services/nginx_service.py`++Add methods to diagnose Nginx configuration:++```python+@classmethod+def get_site_config(cls, name: str) -> Dict:+ """Get the content of a site configuration file."""+ config_path = os.path.join(cls.SITES_AVAILABLE, name)+ if not os.path.exists(config_path):+ return {'exists': False, 'error': 'Config file not found'}++ try:+ with open(config_path, 'r') as f:+ content = f.read()++ enabled_path = os.path.join(cls.SITES_ENABLED, name)+ is_enabled = os.path.exists(enabled_path) or os.path.islink(enabled_path)++ return {+ 'exists': True,+ 'enabled': is_enabled,+ 'content': content,+ 'path': config_path+ }+ except Exception as e:+ return {'exists': True, 'error': str(e)}++@classmethod+def diagnose_site(cls, name: str, port: int = None) -> Dict:+ """Full diagnostic for a site configuration."""+ diagnosis = {+ 'config': cls.get_site_config(name),+ 'nginx_running': cls.get_status().get('running', False),+ 'config_valid': cls.test_config()+ }++ if port:+ from app.services.docker_service import DockerService+ diagnosis['port_accessible'] = DockerService.check_port_accessible(port)++ return diagnosis+```++**Verification**: Test with an existing app++---++### Task 3: Add Debug API Endpoints+**File**: `backend/app/api/domains.py`++Add diagnostic endpoints:++```python+@domains_bp.route('/debug/diagnose/<int:app_id>', methods=['GET'])+@jwt_required()+@admin_required+def diagnose_app_routing(app_id):+ """Diagnose routing issues for an application."""+ app = Application.query.get(app_id)+ if not app:+ return jsonify({'error': 'Application not found'}), 404++ diagnosis = {+ 'app': {+ 'id': app.id,+ 'name': app.name,+ 'type': app.app_type,+ 'port': app.port,+ 'root_path': app.root_path,+ 'status': app.status+ },+ 'domains': [],+ 'nginx': None,+ 'docker': None+ }++ # Get domains+ domains = Domain.query.filter_by(application_id=app_id).all()+ diagnosis['domains'] = [d.to_dict() for d in domains]++ # Nginx diagnosis+ diagnosis['nginx'] = NginxService.diagnose_site(app.name, app.port)++ # Docker diagnosis (if docker app)+ if app.app_type == 'docker':+ from app.services.docker_service import DockerService++ # Check port accessibility+ if app.port:+ diagnosis['docker'] = {+ 'port_check': DockerService.check_port_accessible(app.port),+ }++ # Get container info+ if app.root_path:+ containers = DockerService.compose_ps(app.root_path)+ diagnosis['docker']['containers'] = containers++ # Get port bindings for each container+ for container in containers:+ if container.get('Name'):+ bindings = DockerService.get_container_port_bindings(container['Name'])+ container['port_bindings'] = bindings++ return jsonify(diagnosis), 200+```++**Verification**: Call endpoint and verify all data is returned++---++### Task 4: Fix Domain Creation to Validate Port+**File**: `backend/app/api/domains.py`++Enhance domain creation to validate the port is accessible before creating Nginx config:++```python+# In create_domain(), after getting the app:+if app.app_type == 'docker':+ if not app.port:+ return jsonify({+ 'error': 'Docker app must have a port configured before adding domains',+ 'hint': 'Update the application with a valid port number'+ }), 400++ # Check if port is accessible+ from app.services.docker_service import DockerService+ port_check = DockerService.check_port_accessible(app.port)++ # Add warning if port not accessible (but still allow creation)+ port_warning = None+ if not port_check.get('accessible'):+ port_warning = f"Warning: Port {app.port} is not currently accessible. Make sure the container is running."+```++Then include `port_warning` in the response.++**Verification**: Create domain for stopped app, verify warning appears++---++### Task 5: Add Container Port Discovery+**File**: `backend/app/services/template_service.py`++After starting containers, verify the actual port mapping:++```python+# In install_template(), after compose_up succeeds (around line 458):++# Verify container is actually running and port is mapped+import time+time.sleep(2) # Give container time to start++if app_port:+ from app.services.docker_service import DockerService+ port_check = DockerService.check_port_accessible(app_port)+ if not port_check.get('accessible'):+ # Log warning but don't fail - container might need more startup time+ print(f"Warning: Port {app_port} not accessible immediately after start")+```++**Verification**: Install a template and check logs++---++### Task 6: Enhance App Status API with Port Info+**File**: `backend/app/api/apps.py`++Modify `get_app_status` to include port accessibility:++```python+# In get_app_status(), add after getting containers:++# Add port check+port_status = None+if app.port:+ port_status = DockerService.check_port_accessible(app.port)++return jsonify({+ 'status': actual_status,+ 'containers': containers,+ 'running': running_count,+ 'total': total_count,+ 'port': app.port,+ 'port_accessible': port_status.get('accessible') if port_status else None+}), 200+```++**Verification**: Call `/api/v1/apps/{id}/status` and verify port_accessible field++---++### Task 7: Add Frontend Diagnostic Display+**File**: `frontend/src/pages/ApplicationDetail.jsx`++Add a diagnostic section that shows:+- Port configuration and accessibility+- Nginx config status (exists, enabled)+- Container port bindings+- "Test Connection" button++```jsx+// Add new component or section:+<div className="diagnostic-section">+ <h3>Routing Diagnostics</h3>++ <div className="diagnostic-item">+ <label>Port:</label>+ <span>{app.port || 'Not configured'}</span>+ {portAccessible !== null && (+ <span className={portAccessible ? 'status-ok' : 'status-error'}>+ {portAccessible ? '✓ Accessible' : '✗ Not accessible'}+ </span>+ )}+ </div>++ <div className="diagnostic-item">+ <label>Nginx Config:</label>+ <span className={nginxStatus?.exists ? 'status-ok' : 'status-error'}>+ {nginxStatus?.exists ? 'Created' : 'Missing'}+ </span>+ {nginxStatus?.enabled && <span className="badge">Enabled</span>}+ </div>++ <button onClick={runDiagnostics}>Run Full Diagnostics</button>+</div>+```++**Verification**: View app detail page and verify diagnostics display++---++### Task 8: Create Test Script+**File**: `scripts/test-routing.sh` (new file)++Create a script to test the full routing chain:++```bash+#!/bin/bash+# Test Docker app routing++APP_NAME=$1+PORT=$2+DOMAIN=$3++echo "=== Testing routing for $APP_NAME ==="++echo "1. Checking if port $PORT is accessible on localhost..."+nc -z 127.0.0.1 $PORT && echo " ✓ Port accessible" || echo " ✗ Port NOT accessible"++echo "2. Checking Nginx config..."+[ -f /etc/nginx/sites-available/$APP_NAME ] && echo " ✓ Config exists" || echo " ✗ Config missing"+[ -L /etc/nginx/sites-enabled/$APP_NAME ] && echo " ✓ Config enabled" || echo " ✗ Config NOT enabled"++echo "3. Testing Nginx config syntax..."+sudo nginx -t 2>&1 | grep -q "successful" && echo " ✓ Config valid" || echo " ✗ Config INVALID"++echo "4. Testing HTTP request to localhost:$PORT..."+curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:$PORT/ | grep -q "200\|301\|302" && echo " ✓ Container responds" || echo " ✗ Container NOT responding"++if [ -n "$DOMAIN" ]; then+ echo "5. Testing HTTP request via domain $DOMAIN..."+ curl -s -o /dev/null -w "%{http_code}" -H "Host: $DOMAIN" http://127.0.0.1/ | grep -q "200\|301\|302" && echo " ✓ Domain routing works" || echo " ✗ Domain routing FAILED"+fi++echo "=== Done ==="+```++**Verification**: Run script with a test app++---++## Verification++### Integration Test Checklist+After all tasks complete:++1. [ ] Deploy a Docker template (e.g., nginx, whoami)+2. [ ] Verify Application record has correct port+3. [ ] Check port is accessible: `curl http://127.0.0.1:{port}`+4. [ ] Add domain to the application+5. [ ] Verify Nginx config created in `/etc/nginx/sites-available/`+6. [ ] Verify symlink in `/etc/nginx/sites-enabled/`+7. [ ] Test domain access: `curl -H "Host: yourdomain.com" http://127.0.0.1/`+8. [ ] Check diagnostic endpoint returns all data+9. [ ] Verify frontend shows diagnostic info++### Expected Results+- Port accessibility shows green checkmark when container is running+- Nginx config status shows "Created" and "Enabled"+- Domain resolves to the correct container+- Diagnostic endpoint provides actionable information++---++## Success Criteria+- [ ] Docker containers expose ports to localhost correctly+- [ ] Nginx configs are created and enabled automatically+- [ ] Domains route traffic to Docker containers+- [ ] Diagnostic info visible in UI+- [ ] Debug endpoint provides full routing diagnosis+- [ ] Clear error messages when something is misconfigured++---++## Rollback Plan+All changes are additive (new methods, new endpoints). No breaking changes to existing functionality. If issues arise:+1. Revert the specific file changes+2. Existing functionality remains unchanged++---++## Output+After execution:+- New diagnostic methods in DockerService and NginxService+- New `/api/v1/domains/debug/diagnose/{app_id}` endpoint+- Enhanced app status with port information+- Frontend diagnostic section in ApplicationDetail+- Test script for manual verification