@polymorphism-tech/morph-spec 7.4.0 → 7.6.0

package/framework/standards/infrastructure/docker/{easypanel-deploy.md → coolify-deploy.md}

@@ -1,23 +1,39 @@
-# EasyPanel Deployment Standard
+# Coolify Deployment Standard
 
 > **Scope:** nextjs-neon
 > **Layer:** 2 (on keyword)
-> **Keywords:** easypanel, docker, deploy, deployment, container
-> **Load When:** easypanel or docker deployment keywords detected
+> **Keywords:** coolify, docker, deploy, deployment, container, vps, ssh
+> **Load When:** coolify or docker deployment keywords detected
 
-**Verified against:** .NET 10 + Next.js 15 + Node 22 (Docker base images). Last-verified: 2026-05-20.
+**Verified against:** .NET 10 + Next.js 15 + Node 22 (Docker base images). Last-verified: 2026-07-07.
 
 ---
 
 Stack: Next.js 15 + Neon PostgreSQL + .NET Backend
 
+## What is Coolify and why we use it
+
+[Coolify](https://coolify.io) is a self-hosted, open-source PaaS -- an alternative to Heroku/Vercel/Railway that runs on your own VPS. It manages Docker-based deployments end-to-end: builds from a Dockerfile or docker-compose, reverse-proxies traffic (Traefik under the hood), issues and renews Let's Encrypt SSL certificates, and exposes a REST API for automation.
+
+Coolify is Polymorphism Tech's standard self-hosted deployment platform for Docker workloads.
+
+There is no MCP server or CLI tool for Coolify. All access is via **SSH into the VPS**, from which the Coolify API is reached at `http://localhost:8000/api/v1/` (it is not exposed publicly). The API token lives server-side only (e.g. `~/.coolify-token`, `chmod 600`) -- never print it, never commit it, never let it leave the SSH session.
+
+```bash
+# Canonical access pattern — token is read and used entirely server-side
+ssh <vps-ssh-alias> 'T=$(cat ~/.coolify-token); curl -s -H "Authorization: Bearer $T" http://localhost:8000/api/v1/projects'
+```
+
+Useful endpoints: `/version`, `/projects`, `/servers`, `/applications`, `/deploy?uuid={uuid}`. Changing a domain: `PATCH /applications/{uuid}` with `{"domains":"https://x,https://www.x"}`, then `GET /deploy?uuid={uuid}` to redeploy.
+
 ## Core Rules
 
 - ALWAYS use multi-stage Docker builds for minimal image size
 - ALWAYS configure health checks for zero-downtime deploys
-- NEVER hardcode secrets in Dockerfiles -- use EasyPanel environment variables
+- NEVER hardcode secrets in Dockerfiles -- use Coolify environment variables
 - ALWAYS use `.dockerignore` to exclude node_modules, .git, .env files
 - SSL is automatic via Let's Encrypt -- no manual certificate management
+- NEVER call the Coolify API directly from your local machine or from CI without going through SSH -- the API port is not publicly reachable and the token must stay server-side
 
 ## .NET 10 Dockerfile
 
@@ -85,7 +101,7 @@ test
 __tests__
 ```
 
-## EasyPanel Service Config
+## Coolify Service Config
 
 | Setting | .NET Backend | Next.js Frontend |
 |---------|-------------|-----------------|
@@ -97,20 +113,22 @@ __tests__
 
 ### GitHub Integration
 
-1. Generate GitHub PAT with `repo` scope
-2. EasyPanel: Settings > GitHub > Add token
-3. Select repository and branch
-4. Enable "Auto Deploy" for webhook-triggered deploys
+Coolify deploys straight from a GitHub repo (via GitHub App install or a deploy key) and redeploys automatically on push when auto-deploy is enabled for the application.
+
+1. In Coolify, add the GitHub source (GitHub App install or deploy key)
+2. Create the Application, pointing it at the repo/branch and the Dockerfile path
+3. Enable "Auto Deploy" for webhook-triggered deploys on push to the tracked branch
+4. Record the application's `uuid` -- every subsequent API call (`/deploy?uuid=`) targets it
 
 ### Domain and SSL
 
-DNS setup (CNAME to EasyPanel server):
+DNS setup (A record to the Coolify server):
 ```
-app.example.com  CNAME  your-server.easypanel.host
-api.example.com  CNAME  your-server.easypanel.host
+app.example.com  A      <vps-ip>
+api.example.com  A      <vps-ip>
 ```
 
-SSL via Let's Encrypt is automatic. Force HTTPS enabled by default.
+SSL via Let's Encrypt is automatic (Coolify runs Traefik as the reverse proxy). Force HTTPS enabled by default.
 
 ## Environment Variables
 
@@ -147,11 +165,11 @@ export async function GET() {
 
 ## Zero-Downtime Deploys
 
-EasyPanel uses Docker HEALTHCHECK to determine container readiness:
+Coolify uses the same Docker HEALTHCHECK contract to determine container readiness:
 
 1. New container starts alongside old container
 2. Health check passes after start-period + retries
-3. Traffic shifts to new container
+3. Traffic shifts to new container (Traefik)
 4. Old container stopped
 
 | HEALTHCHECK Param | Value | Purpose |
@@ -163,8 +181,8 @@ EasyPanel uses Docker HEALTHCHECK to determine container readiness:
 
 ## Monitoring
 
-- **Logs**: Real-time in EasyPanel UI
-- **Metrics**: CPU, memory, network via dashboard
+- **Logs**: `docker logs <container>` over SSH, or Coolify's live log viewer in the UI
+- **Metrics**: CPU, memory, network via Coolify's dashboard, or `docker stats` over SSH
 - **Restart**: Auto-restart on crash (default)
 
 Structured logging:
@@ -182,6 +200,17 @@ import pino from "pino";
 const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
 ```
 
+## Triggering a Deploy via SSH + API
+
+Since there is no MCP server or CLI for Coolify, every deploy operation (manual redeploy, CI/CD, or troubleshooting) goes through the same SSH + curl pattern used for all other Coolify access:
+
+```bash
+# Redeploy an existing application after a new image/commit is ready
+ssh <vps-ssh-alias> 'T=$(cat ~/.coolify-token); curl -s -X GET -H "Authorization: Bearer $T" "http://localhost:8000/api/v1/deploy?uuid=<application-uuid>"'
+```
+
+In GitHub Actions this becomes an SSH step using a deploy key stored as a secret (see the `github-workflow-deploy-coolify` template) -- never a direct HTTP call to the Coolify API from the runner, since the API port is not reachable outside the VPS.
+
 ## Deployment Checklist
 
 | Step | Action |
@@ -189,8 +218,8 @@ const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
 | 1 | Verify `output: "standalone"` in next.config.ts |
 | 2 | Test Docker build locally |
 | 3 | Test health endpoint |
-| 4 | Configure env vars in EasyPanel |
+| 4 | Configure env vars in Coolify (UI or API) |
 | 5 | Set up custom domain + DNS |
 | 6 | Verify SSL certificate |
 | 7 | Enable auto-deploy from GitHub |
-| 8 | Push to main, verify deployment |
+| 8 | Push to main, verify deployment via SSH (`docker ps` / Coolify logs) |

package/framework/templates/README.md

@@ -54,18 +54,18 @@ framework/templates/
 │       └── postgresql-rls-policy.sql                  # Row-level security
 │
 ├── infrastructure/
-│   ├── docker/        # Docker & EasyPanel
+│   ├── docker/        # Docker & Coolify
 │   │   ├── dockerfile-api.dockerfile       # .NET API
 │   │   ├── dockerfile-web.dockerfile       # Next.js web
 │   │   ├── Dockerfile.template             # Generic
 │   │   ├── docker-compose.template.yml     # Compose
-│   │   └── easypanel.template.json         # EasyPanel config
+│   │   └── coolify.template.json           # Coolify config
 │   │
 │   └── github/        # GitHub Actions CI/CD
 │       ├── workflows/                      # Reusable workflow templates
 │       │   ├── dotnet-build.yml.hbs       # .NET restore, build, test
 │       │   ├── docker-build-push.yml.hbs  # Docker build & push
-│       │   └── deploy-easypanel.yml.hbs   # EasyPanel deployment
+│       │   └── deploy-coolify.yml.hbs     # Coolify deployment (via SSH)
 │       │
 │       ├── actions/                        # Composite action templates
 │       │   ├── docker-build-push/action.yml.hbs
@@ -313,7 +313,7 @@ infrastructure/github/
 ├── workflows/                      # Reusable workflow templates
 │   ├── dotnet-build.yml.hbs       # .NET restore, build, test
 │   ├── docker-build-push.yml.hbs  # Docker build & push
-│   └── deploy-easypanel.yml.hbs   # EasyPanel deployment
+│   └── deploy-coolify.yml.hbs     # Coolify deployment via SSH
 │
 └── actions/                        # Composite action templates
     ├── docker-build-push/action.yml.hbs
@@ -329,8 +329,8 @@ infrastructure/github/
 
 ### Deployment Strategy Difference
 
-**NextJS-Neon:** Docker containers to EasyPanel
-- `docker build` → `docker push` → EasyPanel webhook
+**NextJS-Neon:** Docker containers to Coolify
+- `docker build` → `docker push` → Coolify deploy triggered via SSH (Coolify's API is not publicly exposed — the runner SSHes into the VPS and calls `localhost:8000/api/v1/deploy` there)
 - Multi-service deployment (API + Web)
 - Registry: GitHub Container Registry (ghcr.io)
 
@@ -368,7 +368,7 @@ infrastructure/github/
 ```
 
 **GitHub Secrets to Configure:**
-- NextJS-Neon: `GITHUB_TOKEN` (auto), `EASYPANEL_API_TOKEN`
+- NextJS-Neon: `GITHUB_TOKEN` (auto), `COOLIFY_SSH_HOST`, `COOLIFY_SSH_USER`, `COOLIFY_SSH_KEY`, `COOLIFY_APPLICATION_UUID`
 
 ### Stack-Specific Overrides
 

package/framework/templates/REGISTRY.json

@@ -127,6 +127,8 @@
         "APP_INSIGHTS",
         "AZURE_LOCATION",
         "CONTAINER_ENV",
+        "COOLIFY_APP_URL",
+        "COOLIFY_SERVER",
         "DEVOPS_AREA_PATH",
         "DEVOPS_BUILD_PIPELINE",
         "DEVOPS_ORG",
@@ -134,8 +136,6 @@
         "DEVOPS_RELEASE_PIPELINE",
         "DEVOPS_WIKI_NAME",
         "DOTNET_VERSION",
-        "EASYPANEL_API_URL",
-        "EASYPANEL_WEB_URL",
         "EF_VERSION",
         "INFERRED_STANDARDS",
         "MORPH_VERSION",
@@ -193,7 +193,6 @@
         "COMPLEXITY",
         "CONTRACTS_PATH",
         "CURRENT_TASK",
-        "CURRENT_TASK_ID",
         "DECISIONS_PATH",
         "DESCRIPTION",
         "FEATURE_ID",
@@ -213,8 +212,7 @@
         "TASKS_TOTAL",
         "TEAM_LEAD",
         "TIMESTAMP",
-        "VALIDATION_TIMESTAMP",
-        "VALIDATOR"
+        "VALIDATION_TIMESTAMP"
       ],
       "stackSpecific": false,
       "engine": "handlebars",
@@ -521,7 +519,7 @@
       "category": "infrastructure",
       "phase": "implement",
       "required": false,
-      "description": ".NET API Dockerfile for EasyPanel/Docker",
+      "description": ".NET API Dockerfile for Coolify/Docker",
       "outputName": "Dockerfile.api",
       "placeholders": [],
       "stackSpecific": false,
@@ -542,7 +540,7 @@
       "category": "infrastructure",
       "phase": "implement",
       "required": false,
-      "description": "Next.js web Dockerfile for EasyPanel/Docker",
+      "description": "Next.js web Dockerfile for Coolify/Docker",
       "outputName": "Dockerfile.web",
       "placeholders": [],
       "stackSpecific": false,
@@ -597,16 +595,16 @@
       "validatePlaceholders": true
     },
     {
-      "id": "easypanel-config",
+      "id": "coolify-config",
       "kind": "template",
-      "name": "EasyPanel Configuration",
-      "path": "infrastructure/docker/easypanel.template.json",
+      "name": "Coolify Configuration",
+      "path": "infrastructure/docker/coolify.template.json",
       "location": "framework",
       "category": "infrastructure",
       "phase": "implement",
       "required": false,
-      "description": "EasyPanel deployment configuration",
-      "outputName": "easypanel.json",
+      "description": "Coolify deployment configuration — accessed via SSH + API, no MCP/CLI",
+      "outputName": "coolify.json",
       "placeholders": [
         "GITHUB_OWNER",
         "GITHUB_REPO"
@@ -837,17 +835,17 @@
       "validatePlaceholders": true
     },
     {
-      "id": "github-workflow-deploy-easypanel",
+      "id": "github-workflow-deploy-coolify",
       "kind": "template",
-      "name": "GitHub Actions - Deploy to EasyPanel",
-      "path": "infrastructure/github/workflows/deploy-easypanel.yml.hbs",
+      "name": "GitHub Actions - Deploy to Coolify",
+      "path": "infrastructure/github/workflows/deploy-coolify.yml.hbs",
       "location": "framework",
       "category": "infrastructure",
       "technology": "github-actions",
       "phase": "deploy",
       "required": false,
-      "description": "Reusable workflow for deploying to EasyPanel via webhook",
-      "outputName": "deploy-easypanel.yml",
+      "description": "Reusable workflow for deploying to Coolify via SSH (API is not publicly exposed)",
+      "outputName": "deploy-coolify.yml",
       "placeholders": [],
       "stackSpecific": false,
       "applicableStacks": [

package/framework/templates/context/CONTEXT-FEATURE.md

@@ -229,21 +229,17 @@ No validation runs yet. Validators run automatically via checkpoints.
 ## Quick Actions
 
 ### Continue Implementation
-```bash
-# Start a task (dispatch gate + state tracking)
-morph-spec task start {{FEATURE_NAME}} <task-id>
-
-# Complete current task (runs validators)
-morph-spec task done {{FEATURE_NAME}} {{CURRENT_TASK_ID}}
-
-# Generate recap after task completion
-morph-spec generate recap {{FEATURE_NAME}}
-```
+During the implement phase, track your work with the native `TaskCreate`/`TaskUpdate`
+tools. Persist progress by writing `tasks.json` (`2-plan/tasks.json`), touching ONLY
+the mutable fields `status`, `outputs`, and `notes` — via the `Write` tool or an `Edit`
+that touches only those fields. The plan contract (`title`, `description`,
+`dependencies`, `effort`, `doneCriteria`, `group`) is frozen after Gate 2. The recap is
+written by the implement skill; state syncs automatically via the `state-sync` hook.
 
 ### Advance Phase
 ```bash
-# Check prerequisites and advance
-morph-spec phase advance {{FEATURE_NAME}}
+# Approve the current gate and scaffold the next phase folder in one step
+morph-spec advance {{FEATURE_NAME}}
 
 # Validate feature outputs
 morph-spec validate-feature {{FEATURE_NAME}}
@@ -251,11 +247,8 @@ morph-spec validate-feature {{FEATURE_NAME}}
 
 ### Validation
 ```bash
-# Run all validators for active agents
-morph-spec validate {{FEATURE_NAME}}
-
-# Run specific validator
-morph-spec validate-{{VALIDATOR}} {{FEATURE_NAME}}
+# Validate this feature's outputs against active standards
+morph-spec validate-feature {{FEATURE_NAME}}
 ```
 
 ---