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(12): Complete Phase 12 - Multi-Environment App Linking

Juan Denisda014edba0a2
diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index e0e5f224..8445048d 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -23,7 +23,7 @@ Completed 2026-01-19 | 9 phases | 109 commits | +14,667/-2,836 lines
| Phase | Name | Status | Goal |
|-------|------|--------|------|
| 11 | Shared Database WordPress Template | **completed** | Create WordPress template with external DB support |
-| 12 | Multi-Environment App Linking | pending | Link prod/dev apps to share database |
+| 12 | Multi-Environment App Linking | **completed** | Link prod/dev apps to share database |
| 13 | Environment Switching UI | pending | UI to manage prod/dev environments |
| 14 | GitHub & Community Links | **completed** | Add GitHub link, community resources to app |
| 15 | WordPress Dev Workflow Testing | pending | End-to-end testing of the dev workflow |
@@ -50,30 +50,24 @@ Completed 2026-01-19 | 9 phases | 109 commits | +14,667/-2,836 lines
---
-## Phase 12: Multi-Environment App Linking
+## 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
+**Status**: Completed 2026-01-19
+
+### What Was Built
+- Application model with `environment_type`, `linked_app_id`, `shared_config` fields
+- App linking API: POST/GET/DELETE `/apps/{id}/link`, PUT `/apps/{id}/environment`
+- `propagate_db_credentials()` for sharing DB credentials with different table prefixes
+- Frontend API methods: `linkApp`, `getLinkedApps`, `unlinkApp`, `updateAppEnvironment`
+- GET /apps with environment filtering and include_linked option
### Success Criteria
-- [ ] Apps can be linked as prod/dev pairs
-- [ ] Linked apps share database credentials automatically
-- [ ] Table prefixes prevent collision
+- [x] Apps can be linked as prod/dev pairs
+- [x] Linked apps share database credentials automatically
+- [x] Table prefixes prevent collision
+
+[Full Summary](./phases/12-multi-environment-app-linking/SUMMARY.md)
---
diff --git a/.planning/STATE.md b/.planning/STATE.md
index ead51c3a..51e7d605 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -2,7 +2,7 @@
## Current Status
- **Milestone**: 2 - Multi-Environment WordPress & Community Features
-- **Current Phase**: 12 - Multi-Environment App Linking
+- **Current Phase**: 13 - Environment Switching UI
- **Phase Status**: Pending
- **Last Updated**: 2026-01-19
@@ -11,11 +11,19 @@
| Phase | Status | Started | Completed |
|-------|--------|---------|-----------|
| 11 | completed | 2026-01-19 | 2026-01-19 |
-| 12 | pending | - | - |
+| 12 | completed | 2026-01-19 | 2026-01-19 |
| 13 | pending | - | - |
| 14 | completed | 2026-01-19 | 2026-01-19 |
| 15 | pending | - | - |
+## Phase 12 Summary
+Multi-Environment App Linking implemented:
+- Added `environment_type`, `linked_app_id`, `shared_config` fields to Application model
+- Added app linking API endpoints (POST/GET/DELETE `/apps/{id}/link`, PUT `/apps/{id}/environment`)
+- Added `propagate_db_credentials()` for sharing DB credentials with different table prefixes
+- Added frontend API methods (`linkApp`, `getLinkedApps`, `unlinkApp`, `updateAppEnvironment`)
+- Updated GET /apps with environment filtering and include_linked option
+
## Phase 11 Summary
Shared Database WordPress Template implemented:
- Created `wordpress-external-db.yaml` template for external MySQL connections
@@ -47,12 +55,13 @@ None currently identified.
## Notes
- Milestone 1 (v1.0) completed 2026-01-19
- Phase numbering continues from Milestone 1 (11-15)
-- Phases 11 and 14 completed - core template and community features done
-- Next: Phase 12 (Multi-Environment App Linking) to enable prod/dev linking
+- Phases 11, 12, and 14 completed - template, linking API, and community features done
+- Next: Phase 13 (Environment Switching UI) to add UI for managing linked apps
## Quick Links
- [ROADMAP.md](./ROADMAP.md)
- [PROJECT.md](./PROJECT.md)
- [Milestone 1 Archive](./milestones/v1.0-ROADMAP.md)
- [Phase 11 Summary](./phases/11-shared-database-wordpress-template/SUMMARY.md)
+- [Phase 12 Summary](./phases/12-multi-environment-app-linking/SUMMARY.md)
- [Phase 14 Summary](./phases/14-github-community-links/SUMMARY.md)
diff --git a/.planning/phases/12-multi-environment-app-linking/SUMMARY.md b/.planning/phases/12-multi-environment-app-linking/SUMMARY.md
new file mode 100644
index 00000000..52c2a9d1
--- /dev/null
+++ b/.planning/phases/12-multi-environment-app-linking/SUMMARY.md
@@ -0,0 +1,84 @@
+# Phase 12: Multi-Environment App Linking — Summary
+
+## Outcome
+**Completed** — Apps can now be linked as prod/dev pairs with shared database credentials automatically propagated.
+
+## What Was Built
+
+### 1. Application Model Updates
+**File:** `backend/app/models/application.py`
+- Added `environment_type` column (production/development/staging/standalone)
+- Added `linked_app_id` for bidirectional app linking
+- Added `shared_config` JSON field for storing shared resource info
+- Added `linked_app` self-referential relationship
+- Updated `to_dict()` with optional `include_linked` parameter
+
+### 2. App Linking API Endpoints
+**File:** `backend/app/api/apps.py`
+- `POST /apps/{id}/link` — Link two apps as prod/dev pair
+- `GET /apps/{id}/linked` — Get all linked apps
+- `DELETE /apps/{id}/link` — Unlink apps
+- `PUT /apps/{id}/environment` — Update environment type only
+- Updated `GET /apps` with environment filtering and `include_linked` param
+- Updated `GET /apps/{id}` to include linked app info by default
+
+### 3. Database Credential Propagation
+**File:** `backend/app/services/template_service.py`
+- Added `propagate_db_credentials()` method
+- Reads source app's `.env` for DB credentials (DB_HOST, DB_NAME, etc.)
+- Updates target app's `.env` with same credentials but different table prefix
+- Auto-assigns table prefixes (wp_ for prod, wp_dev_ for dev)
+- Optionally updates docker-compose.yml environment variables
+
+### 4. Frontend API Methods
+**File:** `frontend/src/services/api.js`
+- `linkApp(appId, targetAppId, asEnvironment, options)` — Link apps with optional credential propagation
+- `getLinkedApps(appId)` — Get linked apps
+- `unlinkApp(appId)` — Unlink apps
+- `updateAppEnvironment(appId, environmentType)` — Set environment type
+
+## Commits
+1. `34bee0e` — feat(12): Add environment linking fields to Application model
+2. `3e4ba70` — feat(12): Add app linking API endpoints
+3. `7485771` — feat(12): Add database credential propagation for linked apps
+4. `46f6f3a` — feat(12): Add frontend API methods for app linking
+5. `65d1fbe` — feat(12): Update app list response to include environment info and filtering
+
+## API Reference
+
+### Link Apps
+```bash
+POST /apps/{id}/link
+{
+ "target_app_id": 2,
+ "as_environment": "development",
+ "propagate_credentials": true,
+ "table_prefix": "wp_dev_"
+}
+```
+
+### Get Linked Apps
+```bash
+GET /apps/{id}/linked
+```
+
+### Filter by Environment
+```bash
+GET /apps?environment=production
+GET /apps?include_linked=true
+```
+
+## Key Decisions
+- **Bidirectional linking**: Both apps store reference to each other
+- **Auto table prefix**: Prevents collision when sharing database (wp_ vs wp_dev_)
+- **Optional credential propagation**: Can be disabled via `propagate_credentials: false`
+- **Environment types**: production, development, staging, standalone (default)
+
+## Files Changed
+- `backend/app/models/application.py`
+- `backend/app/api/apps.py`
+- `backend/app/services/template_service.py`
+- `frontend/src/services/api.js`
+
+## Next Steps
+Phase 13 will add the UI for managing linked apps and environment switching.