From 968dc745558992a589ea580009d310e400188c45 Mon Sep 17 00:00:00 2001
From: Oussama Douhou <oussama.douhou@gmail.com>
Date: Tue, 13 Jan 2026 14:07:20 +0100
Subject: [PATCH] docs: add testing session 2026-01-13 findings

- Verified workflow separation and dollar sign escaping
- Retrieved shared project and environment IDs
- Tested local dev server health endpoint
- Documented Dokploy API token blocker (returns Forbidden)
- Added commands for resolving token issue
- Updated environment configuration requirements
---
 docs/TESTING.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)

diff --git a/docs/TESTING.md b/docs/TESTING.md
index 7d5f455..e4363a4 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -261,3 +261,113 @@ Authorization: token <your-api-token>
 |-----|---------|
 | `GITEA_API_TOKEN` | Gitea API access for workflow status |
 | `DOKPLOY_API_TOKEN` | Dokploy deployment API (BWS ID: `6b3618fc-ba02-49bc-bdc8-b3c9004087bc`) |
+
+---
+
+## Testing Session: 2026-01-13
+
+### Session Summary
+
+**Goal:** Verify multi-environment deployment setup and shared project configuration.
+
+### Completed Tasks
+
+| Task | Status | Evidence |
+|------|--------|----------|
+| Workflow separation (dev/staging/main) | ✅ | Committed as `eb2745d` |
+| Dollar sign escaping (`$${{project.VAR}}`) | ✅ | Verified in all docker-compose.*.yml |
+| Shared project exists | ✅ | `ai-stack-portal` (ID: `2y2Glhz5Wy0dBNf6BOR_-`) |
+| Environment IDs retrieved | ✅ | See below |
+| Local dev server health | ✅ | `/health` returns healthy |
+
+### Environment IDs
+
+```
+Project: ai-stack-portal
+ID: 2y2Glhz5Wy0dBNf6BOR_-
+
+Environments:
+- production: _dKAmxVcadqi-z73wKpEB (default)
+- deployments: RqE9OFMdLwkzN7pif1xN8 (for user stacks)
+- test: KVKn5fXGz10g7KVxPWOQj
+```
+
+### Blockers Identified
+
+#### BLOCKER: Dokploy API Token Permissions
+
+**Symptom:** All Dokploy API calls return `Forbidden`
+
+```bash
+# Previously working
+curl -s "https://app.flexinit.nl/api/project.all" -H "x-api-key: $DOKPLOY_API_TOKEN"
+# Now returns: Forbidden
+
+# Environment endpoint
+curl -s "https://app.flexinit.nl/api/environment.one?environmentId=RqE9OFMdLwkzN7pif1xN8" -H "x-api-key: $DOKPLOY_API_TOKEN"
+# Returns: Forbidden
+```
+
+**Root Cause:** The API token `app_deployment...` has been revoked or has limited scope.
+
+**Impact:**
+- Cannot verify Docker image exists in registry
+- Cannot test name availability (requires `environment.one`)
+- Cannot create applications or compose stacks
+- Cannot deploy portal to Dokploy
+
+**Resolution Required:**
+1. Log into Dokploy UI at https://app.flexinit.nl
+2. Navigate to Settings → API Keys
+3. Generate new API key with full permissions:
+   - Read/Write access to projects
+   - Read/Write access to applications
+   - Read/Write access to compose stacks
+   - Read/Write access to domains
+4. Update `.env` with new token
+5. Update BWS secret (ID: `6b3618fc-ba02-49bc-bdc8-b3c9004087bc`)
+
+### Local Testing Results
+
+```bash
+# Health check - WORKS
+curl -s "http://localhost:3000/health"
+# {"status":"healthy","timestamp":"2026-01-13T13:01:46.100Z","version":"0.2.0",...}
+
+# Name check - FAILS (API token issue)
+curl -s "http://localhost:3000/api/check/test-stack"
+# {"available":false,"valid":false,"error":"Failed to check availability"}
+```
+
+### Required .env Configuration
+
+```bash
+# Added for shared project deployment
+SHARED_PROJECT_ID=2y2Glhz5Wy0dBNf6BOR_-
+SHARED_ENVIRONMENT_ID=RqE9OFMdLwkzN7pif1xN8
+```
+
+### Next Steps After Token Fix
+
+1. Verify `project.all` API works with new token
+2. Deploy portal to Dokploy (docker-compose.dev.yml)
+3. Test end-to-end stack deployment
+4. Verify stacks deploy to shared project
+5. Clean up test deployments
+
+### Commands Reference
+
+```bash
+# Test API token
+source .env && curl -s "https://app.flexinit.nl/api/project.all" \
+  -H "x-api-key: $DOKPLOY_API_TOKEN" | jq '.[].name'
+
+# Get environment applications
+source .env && curl -s "https://app.flexinit.nl/api/environment.one?environmentId=RqE9OFMdLwkzN7pif1xN8" \
+  -H "x-api-key: $DOKPLOY_API_TOKEN" | jq '.applications'
+
+# Deploy test stack
+curl -X POST http://localhost:3000/api/deploy \
+  -H "Content-Type: application/json" \
+  -d '{"name":"test-'$(date +%s | tail -c 4)'"}'
+```