Skip to content

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.

docs(2): complete WordPress template testing plan

Juan Denis84576b01b174
diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index 91b8a480..a4f82453 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -11,7 +11,7 @@
| Phase | Name | Status | Goal |
|-------|------|--------|------|
| 1 | Docker & Domain Debugging | **completed** | Fix port mapping and domain routing for Docker apps |
-| 2 | WordPress Template Testing | pending | Deploy and verify WordPress works end-to-end |
+| 2 | WordPress Template Testing | **completed** | Deploy and verify WordPress works end-to-end |
| 3 | PHP App Template Testing | pending | Deploy and verify PHP/Laravel apps work correctly |
| 4 | Flask/Python Template Testing | pending | Deploy and verify Python apps route correctly |
| 5 | Private URL System | pending | Add private URL generation and custom slugs |
@@ -94,10 +94,17 @@ Phase 1 added diagnostic tools to identify and debug routing issues. See `.plann
- Update template if issues are template-specific
### Success Criteria
-- [ ] WordPress container starts successfully
-- [ ] Database connection works
-- [ ] Domain routes to WordPress
-- [ ] Installation wizard accessible
+- [x] WordPress container starts successfully
+- [x] Database connection works
+- [x] Domain routes to WordPress
+- [x] Installation wizard accessible
+
+### Completed
+Phase 2 testing passed. Found and fixed 2 bugs:
+- NDJSON parsing in compose_ps (critical)
+- CLI .env loading
+
+See `.planning/phases/02-wordpress-testing/SUMMARY.md` for details.
---
diff --git a/.planning/STATE.md b/.planning/STATE.md
index 63d49441..e1753583 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -2,7 +2,7 @@
## Current Status
- **Milestone**: 1 - Infrastructure Fixes, Private URLs & UI Polish
-- **Current Phase**: 2 - WordPress Template Testing
+- **Current Phase**: 3 - PHP App Template Testing
- **Phase Status**: Not Started
- **Last Updated**: 2026-01-19
@@ -11,7 +11,7 @@
| Phase | Status | Started | Completed |
|-------|--------|---------|-----------|
| 1 | completed | 2026-01-19 | 2026-01-19 |
-| 2 | planned | 2026-01-19 | - |
+| 2 | completed | 2026-01-19 | 2026-01-19 |
| 3 | pending | - | - |
| 4 | pending | - | - |
| 5 | pending | - | - |
@@ -21,6 +21,12 @@
| 9 | pending | - | - |
| 10 | pending | - | - |
+## Phase 2 Summary
+WordPress deployment tested successfully. Found and fixed 2 critical bugs:
+- Bug 1: NDJSON parsing in compose_ps (affected container detection)
+- Bug 2: CLI .env loading (affected CLI commands)
+- Bug 3: Consequence of Bug 1, resolved by same fix
+
## Phase 1 Summary
Completed all 8 tasks:
- Added port accessibility checks to DockerService
diff --git a/.planning/phases/02-wordpress-testing/SUMMARY.md b/.planning/phases/02-wordpress-testing/SUMMARY.md
new file mode 100644
index 00000000..fb17a8c5
--- /dev/null
+++ b/.planning/phases/02-wordpress-testing/SUMMARY.md
@@ -0,0 +1,112 @@
+# Phase 2: WordPress Template Testing - Summary
+
+## Completion Status
+**Completed**: 2026-01-19
+**Result**: WordPress deployment works; 2 bugs found and fixed
+
+## Test Results
+
+### What Works Correctly
+- Template listing and fetching
+- Template installation with docker-compose
+- Port allocation and accessibility
+- Nginx reverse proxy configuration
+- Domain management
+- WordPress container runs properly
+- Domain routing through Nginx works
+- `curl http://test-wordpress.local/` returns WordPress
+
+### Verification Checklist
+
+| Check | Result |
+|-------|--------|
+| WordPress template loads from API | PASS |
+| Template installs without errors | PASS |
+| Both containers (wordpress, db) running | PASS |
+| Port is accessible on localhost | PASS |
+| Domain created without errors | PASS |
+| Nginx config exists and is enabled | PASS |
+| Direct port access returns HTTP response | PASS |
+| Domain routing works via Nginx | PASS |
+| WordPress installation wizard loads | PASS |
+
+## Bugs Found and Fixed
+
+### Bug 1: Container Detection Fails (Critical)
+**Location**: `docker_service.py:539-551` (`compose_ps` method)
+
+**Root Cause**: `docker compose ps --format json` outputs NDJSON (one JSON object per line), not a JSON array. The code did:
+```python
+return json.loads(result.stdout) # Fails on NDJSON
+```
+This threw `JSONDecodeError`, which was caught and returned `[]`.
+
+**Fix**: Parse each line separately:
+```python
+containers = []
+for line in result.stdout.strip().split('\n'):
+ if line.strip():
+ containers.append(json.loads(line))
+return containers
+```
+
+**Commit**: `3f9884c`
+
+### Bug 2: CLI Database Path Issue
+**Location**: `cli.py`
+
+**Root Cause**: CLI commands (like `list-users`, `reset-password`) failed with "unable to open database file" because they didn't load the `.env` file from `/opt/serverkit/.env`. The code used the default path `sqlite:////app/instance/serverkit.db` instead of the configured path.
+
+**Fix**: Load `.env` file before `create_app()` is called:
+```python
+from dotenv import load_dotenv
+# Check multiple locations: ./env, ../env, /opt/serverkit/.env
+```
+
+**Commit**: `4ba0afe`
+
+### Bug 3: Database Status Not Updated (Consequence of Bug 1)
+**Location**: `apps.py:313-325`
+
+**Root Cause**: When `compose_ps` returned empty `[]` (due to Bug 1), the status endpoint saw `total_count == 0` and set `actual_status = 'stopped'`, then updated the database.
+
+**Fix**: Bug 1 fix resolves this. Now `compose_ps` correctly returns container list.
+
+**Note**: The `container_id` field is intentionally not populated for Docker Compose apps because they have multiple containers with auto-generated names.
+
+## Commits
+
+| Hash | Type | Description |
+|------|------|-------------|
+| `3f9884c` | fix | Parse NDJSON output from docker compose ps |
+| `4ba0afe` | fix | Load .env file in CLI before app initialization |
+
+## Success Criteria
+
+- [x] WordPress container starts successfully
+- [x] Database connection works
+- [x] Domain routes to WordPress
+- [x] Installation wizard accessible
+
+## Impact of Fixes
+
+The Bug 1 fix is **critical** because it affects:
+1. App status endpoint (`/api/v1/apps/{id}/status`)
+2. Routing diagnostics (`/api/v1/domains/debug/diagnose/{app_id}`)
+3. Any code using `DockerService.compose_ps()`
+
+The Bug 2 fix enables CLI commands to work in production environments.
+
+## Recommendations
+
+1. **Test on server**: Re-run the diagnostics endpoint after deploying these fixes
+2. **Verify status**: Check that app status now shows 'running' correctly
+3. **CLI test**: Run `python cli.py --debug list-users` to verify .env loading
+
+## Next Steps
+
+With WordPress working:
+- **Phase 3**: PHP App Template Testing
+- **Phase 4**: Flask/Python Template Testing
+
+Both should benefit from the Bug 1 fix.