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.

chore: create Milestone 2 - Multi-Environment WordPress & Community Features

Juan Denis99291eb13b74
diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index f37f5764..64bb3456 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -11,21 +11,216 @@ Completed 2026-01-19 | 9 phases | 109 commits | +14,667/-2,836 lines
## Current Milestone
-*No active milestone. Run `/gsd:new-milestone` to plan the next version.*
+> **Milestone 2**: Multi-Environment WordPress & Community Features
+> **Version**: v1.1
+> **Started**: 2026-01-19
+> **Status**: In Progress
+
+---
+
+## Phase Overview
+
+| Phase | Name | Status | Goal |
+|-------|------|--------|------|
+| 11 | Shared Database WordPress Template | pending | Create WordPress template with external DB support |
+| 12 | Multi-Environment App Linking | pending | Link prod/dev apps to share database |
+| 13 | Environment Switching UI | pending | UI to manage prod/dev environments |
+| 14 | GitHub & Community Links | pending | Add GitHub link, community resources to app |
+| 15 | WordPress Dev Workflow Testing | pending | End-to-end testing of the dev workflow |
+
+---
+
+## Phase 11: Shared Database WordPress Template
+**Goal**: Create a WordPress template variant that connects to an external database instead of its own
+
+### Research Needed
+- [ ] How WordPress handles external MySQL connections
+- [ ] Best practices for shared database credentials
+
+### Tasks
+1. **Create WordPress-External-DB template**
+ - New template in templates marketplace
+ - Docker Compose without MySQL container
+ - Environment variables for external DB connection (DB_HOST, DB_NAME, DB_USER, DB_PASSWORD)
+ - Documentation for connecting to existing database
+
+2. **Add database connection validation**
+ - Test database connection on template installation
+ - Show clear error if database is unreachable
+ - Validate WordPress tables exist or can be created
+
+3. **Add table prefix support**
+ - Allow custom table prefix (e.g., `wp_dev_`, `wp_prod_`)
+ - Enable multiple WordPress instances on same database
+ - Prevent table collision
+
+### Success Criteria
+- [ ] WordPress template can connect to external MySQL
+- [ ] Connection errors shown clearly during install
+- [ ] Table prefix configurable
+
+---
+
+## Phase 12: Multi-Environment App Linking
+**Goal**: Allow apps to be linked as prod/dev pairs sharing a database
+
+### Tasks
+1. **Database schema updates**
+ - Add `linked_app_id` field to Application model
+ - Add `environment_type` field (prod/dev/staging)
+ - Add `shared_resource_config` JSON field for shared resources
+
+2. **App linking API**
+ - `POST /api/v1/apps/{id}/link` - Link two apps
+ - `GET /api/v1/apps/{id}/linked` - Get linked apps
+ - `DELETE /api/v1/apps/{id}/link` - Unlink apps
+ - Validation: only same-type apps can link
+
+3. **Shared database configuration**
+ - When linking, propagate database credentials
+ - Auto-configure table prefixes to avoid collision
+ - Show shared resources in app detail
+
+### Success Criteria
+- [ ] Apps can be linked as prod/dev pairs
+- [ ] Linked apps share database credentials automatically
+- [ ] Table prefixes prevent collision
+
+---
+
+## Phase 13: Environment Switching UI
+**Goal**: UI to manage and switch between prod/dev environments
+
+### Tasks
+1. **Environment badge in app list**
+ - Show "PROD" / "DEV" / "STAGING" badge
+ - Color coding (green=prod, blue=dev, yellow=staging)
+ - Filter apps by environment type
+
+2. **Linked apps section in app detail**
+ - Show linked apps with quick navigation
+ - Environment comparison (running status, version, etc.)
+ - Quick action: "Copy theme from dev to prod"
+
+3. **Environment configuration panel**
+ - Set environment type for existing apps
+ - Link/unlink apps UI
+ - Shared resource visualization
+
+4. **Theme sync feature (WordPress-specific)**
+ - Copy theme files from dev to prod
+ - Preview changes before sync
+ - Rollback capability
+
+### Success Criteria
+- [ ] Environment type visible in UI
+- [ ] Easy navigation between linked apps
+- [ ] Theme sync works for WordPress apps
+
+---
+
+## Phase 14: GitHub & Community Links
+**Goal**: Add GitHub repository link and community resources to the application
+
+### Tasks
+1. **Add GitHub link to UI**
+ - GitHub icon in header/footer
+ - Link to repository (github.com/jhd3197/ServerKit)
+ - "Star on GitHub" prompt for new users
+
+2. **Add documentation links**
+ - Link to README/Wiki
+ - Quick start guide link
+ - API documentation link (if available)
+
+3. **Add community section to Settings page**
+ - GitHub Issues link for bug reports
+ - Discussions link for questions
+ - Contributing guidelines link
+
+4. **Add version info with update check**
+ - Show current version in Settings
+ - Check for new releases via GitHub API
+ - "Update available" notification
+
+### Success Criteria
+- [ ] GitHub link visible in main UI
+- [ ] Documentation accessible from Settings
+- [ ] Version check shows update availability
+
+---
+
+## Phase 15: WordPress Dev Workflow Testing
+**Goal**: End-to-end testing of the complete dev workflow
+
+### Tasks
+1. **Create test plan**
+ - Document full workflow steps
+ - Define success criteria for each step
+ - Prepare test data
+
+2. **Test: Deploy prod WordPress**
+ - Install WordPress with standard template
+ - Configure domain
+ - Create sample content
+
+3. **Test: Deploy dev WordPress (shared DB)**
+ - Install WordPress-External-DB template
+ - Link to prod app
+ - Verify shared database connection
+ - Verify separate table prefixes
+
+4. **Test: Theme development workflow**
+ - Install different theme on dev
+ - Make theme customizations
+ - Sync theme to prod
+ - Verify prod unchanged until sync
+
+5. **Document workflow**
+ - Create user guide for multi-environment setup
+ - Add examples to documentation
+ - Note any limitations or gotchas
+
+### Success Criteria
+- [ ] Full workflow completes without errors
+- [ ] Data isolation works correctly
+- [ ] Theme sync works as expected
+- [ ] Documentation is complete
---
## Dependencies
```
-(Previous milestone dependencies archived)
+Phase 11 (Shared DB Template) ──► Phase 12 (App Linking)
+ │
+ ▼
+Phase 12 ────────────────────► Phase 13 (Environment UI)
+ │
+ ▼
+Phase 13 ────────────────────► Phase 15 (Testing)
+
+Phase 14 (GitHub Links) ─────► Phase 15 (Testing)
```
---
## Notes
-- Milestone 1 archived to `milestones/v1.0-ROADMAP.md`
-- All critical infrastructure fixes shipped
-- Private URL system fully functional
-- Dashboard, Templates, Applications, FileManager UI all polished
+- Phases 11-13 are the core multi-environment feature
+- Phase 14 (GitHub links) can be done independently
+- Phase 15 should run last after all features implemented
+- Table prefix approach avoids complexity of separate databases
+- Consider backup strategy before theme sync operations
+
+---
+
+## Estimated Complexity
+
+| Phase | Complexity | Files Changed |
+|-------|------------|---------------|
+| 11 | Medium | 3-5 (template + validation) |
+| 12 | High | 6-8 (model, API, service) |
+| 13 | High | 5-7 (UI components) |
+| 14 | Low | 2-4 (UI only) |
+| 15 | Low | 0 (testing + docs) |
diff --git a/.planning/STATE.md b/.planning/STATE.md
index fdfa273f..0ecb084d 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -1,112 +1,39 @@
# ServerKit Enhancement - State
## Current Status
-- **Milestone**: 1 - Infrastructure Fixes, Private URLs & UI Polish
-- **Current Phase**: Complete
-- **Phase Status**: Milestone Complete
+- **Milestone**: 2 - Multi-Environment WordPress & Community Features
+- **Current Phase**: 11 - Shared Database WordPress Template
+- **Phase Status**: Pending
- **Last Updated**: 2026-01-19
## Phase Progress
| Phase | Status | Started | Completed |
|-------|--------|---------|-----------|
-| 1 | completed | 2026-01-19 | 2026-01-19 |
-| 2 | completed | 2026-01-19 | 2026-01-19 |
-| 3 | completed | 2026-01-19 | 2026-01-19 |
-| 4 | skipped | - | - |
-| 5 | completed | 2026-01-19 | 2026-01-19 |
-| 6 | completed | 2026-01-19 | 2026-01-19 |
-| 7 | completed | 2026-01-19 | 2026-01-19 |
-| 8 | completed | 2026-01-19 | 2026-01-19 |
-| 9 | completed | 2026-01-19 | 2026-01-19 |
-| 10 | skipped | - | - |
+| 11 | pending | - | - |
+| 12 | pending | - | - |
+| 13 | pending | - | - |
+| 14 | pending | - | - |
+| 15 | pending | - | - |
-## Phase 9 Summary
-FileManager disk usage UI fully implemented:
-- Backend: analyze_directory_sizes, get_file_type_breakdown, get_all_disk_mounts
-- Multi-mount disk usage widget with color-coded progress bars
-- Directory analysis panel with horizontal bar charts
-- File type breakdown with Recharts PieChart
-- Largest files list with navigation
-- Collapsible sidebar with localStorage persistence
-- Lucide icons replacing all emoji file icons
-- Responsive layout with mobile sidebar slide-in
+## Milestone 2 Overview
+Multi-Environment WordPress & Community Features (v1.1)
-## Phase 8 Summary
-Applications UI polish fully implemented:
-- Lucide icons replacing all inline SVGs
-- Sorting options (name A-Z/Z-A, status, type, created)
-- Grid/list view toggle with localStorage persistence
-- Bulk selection with checkboxes and action bar
-- ConfirmModal component for destructive actions
-- Enhanced status badges with animated pulse for running apps
-- Search filter with URL param persistence
-- Improved app cards with port, domain count, container info
-- Mobile responsive design
-
-## Phase 7 Summary
-Templates page polish fully implemented:
-- Lucide icon mappings for 60+ templates as fallbacks
-- Icon error handling with graceful fallback to Lucide icons
-- URL param persistence for category, search, and sort filters
-- Active filter chips with remove buttons and "Clear All"
-- Featured badge for 10 curated templates
-- Enhanced cards with version styling and link indicators
-- Improved modal with requirements section and icons
-- Search input with icon and clear button
-- Results count and sort dropdown (A-Z, Z-A, Featured)
-
-## Phase 6 Summary
-Dashboard historical metrics fully implemented:
-- MetricsHistory model with minute/hour/day aggregation levels
-- MetricsHistoryService with background collection every 60 seconds
-- Auto-aggregation (minute→hour→day) and cleanup per retention policy
-- REST API endpoints for history, stats, and collection control
-- MetricsGraph component with Recharts LineChart
-- Period selector (1h, 6h, 24h, 7d, 30d)
-- Integrated into Dashboard below real-time metrics
-
-## Phase 5 Summary
-Private URL system fully implemented:
-- Database schema with private_slug and private_url_enabled fields
-- PrivateURLService for secure slug generation and validation
-- API endpoints for enable/disable/update/regenerate
-- Nginx integration for /p/{slug} routing
-- Frontend component with copy, regenerate, custom slug support
-- Visual indicator in applications list
-
-## 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
-- Added Nginx config diagnostics
-- Created debug API endpoints for routing diagnosis
-- Added port validation on domain creation
-- Added port verification after template installation
-- Enhanced app status API with port info
-- Added routing diagnostics UI to frontend
-- Created test-routing.sh script
+**Goals:**
+- Create WordPress template with external database support
+- Enable prod/dev environment linking with shared database
+- Add environment switching UI with theme sync
+- Add GitHub and community resource links
## Blockers
None currently identified.
## Notes
-- Phase 9 complete - FileManager now has comprehensive disk visualization
-- All UI pages polished: Dashboard, Templates, Applications, FileManager
-- Ready for Phase 10 (Integration Testing)
-- Milestone 1 nearly complete - only testing phase remains
+- Milestone 1 (v1.0) completed 2026-01-19
+- Phase numbering continues from Milestone 1 (11-15)
+- Phase 14 (GitHub Links) can be done independently of 11-13
## Quick Links
- [ROADMAP.md](./ROADMAP.md)
- [PROJECT.md](./PROJECT.md)
-- [Phase 1 Summary](./phases/01-docker-domain-debugging/SUMMARY.md)
-- [Phase 5 Summary](./phases/05-private-urls/SUMMARY.md)
-- [Phase 6 Summary](./phases/06-dashboard-historical-metrics/SUMMARY.md)
-- [Phase 7 Summary](./phases/07-templates-page-polish/SUMMARY.md)
-- [Phase 8 Summary](./phases/08-applications-ui-polish/SUMMARY.md)
-- [Phase 9 Summary](./phases/09-filemanager-disk-usage/SUMMARY.md)
+- [Milestone 1 Archive](./milestones/v1.0-ROADMAP.md)