@polymorphism-tech/morph-spec 7.5.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",
@@ -519,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,
@@ -540,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,
@@ -595,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"
@@ -835,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.md

@@ -40,9 +40,9 @@
 {{#if MONITORING_ENABLED}}- **Application Insights** ({{APP_INSIGHTS}}){{/if}}
 {{/if}}
 
-{{#if EASYPANEL_ENABLED}}- **EasyPanel** (Docker Deployment)
-  - API: {{EASYPANEL_API_URL}}
-  - Web: {{EASYPANEL_WEB_URL}}
+{{#if COOLIFY_ENABLED}}- **Coolify** (Docker Deployment via SSH)
+  - Server: {{COOLIFY_SERVER}}
+  - App: {{COOLIFY_APP_URL}}
 {{/if}}
 
 ---

package/framework/templates/docs/proposal.md

@@ -70,7 +70,7 @@ Verifiable conditions that mean this feature is done:
 | **Database** | Neon (PostgreSQL + RLS) | {tables, policies, storage} |
 | **Backend API** | .NET 10 Minimal API | {endpoints, business logic} |
 | **Frontend** | Next.js 15 (App Router) | {pages, components, auth} |
-| **Infra** | EasyPanel + Docker | {deployment, SSL} |
+| **Infra** | Coolify + Docker | {deployment, SSL} |
 {{/if}}
 
 ### User Journey
@@ -90,7 +90,7 @@ Verifiable conditions that mean this feature is done:
 | Resource | Provider | Monthly Cost | Notes |
 |----------|----------|-------------|-------|
 | Neon | Free / Launch | $0 - $19 | {DB, Connection Pooling, Branching} |
-| VPS (EasyPanel) | {provider} | ${X} | {API + Web containers} |
+| VPS (Coolify) | {provider} | ${X} | {API + Web containers} |
 | External APIs | {provider} | ${X} | {if applicable} |
 | **Total** | | **${X}/month** | |
 

package/framework/templates/frontend/nextjs/Dockerfile.nextjs.hbs

@@ -1,4 +1,4 @@
-# Multi-stage Next.js production build for EasyPanel
+# Multi-stage Next.js production build for Coolify
 # Stage 1: Dependencies
 FROM node:20-alpine AS deps
 RUN apk add --no-cache libc6-compat

package/framework/templates/infrastructure/docker/coolify.template.json

@@ -0,0 +1,49 @@
+{
+  "name": "{{kebabCase FEATURE_NAME}}",
+  "provider": "coolify",
+  "access": {
+    "method": "ssh",
+    "note": "No MCP/CLI exists for Coolify — replace sshHost with the real SSH alias for the target VPS. The API is reached only from inside the VPS, at apiBaseUrl.",
+    "sshHost": "REPLACE_WITH_VPS_SSH_ALIAS",
+    "apiBaseUrl": "http://localhost:8000/api/v1",
+    "tokenPath": "~/.coolify-token"
+  },
+  "application": {
+    "uuid": "REPLACE_WITH_COOLIFY_APPLICATION_UUID",
+    "projectUuid": "REPLACE_WITH_COOLIFY_PROJECT_UUID",
+    "serverUuid": "REPLACE_WITH_COOLIFY_SERVER_UUID"
+  },
+  "source": {
+    "type": "github",
+    "owner": "{{GITHUB_OWNER}}",
+    "repo": "{{GITHUB_REPO}}",
+    "branch": "main",
+    "autoDeploy": true
+  },
+  "build": {
+    "type": "dockerfile",
+    "dockerfile": "Dockerfile"
+  },
+  "deploy": {
+    "replicas": 1,
+    "zeroDowntime": true
+  },
+  "env": [
+    {
+      "key": "NODE_ENV",
+      "value": "production"
+    },
+    {
+      "key": "DATABASE_URL",
+      "value": "${DATABASE_URL}"
+    }
+  ],
+  "domains": [
+    {
+      "host": "{{kebabCase FEATURE_NAME}}.example.com",
+      "port": 3000,
+      "https": true
+    }
+  ],
+  "deployCommand": "ssh REPLACE_WITH_VPS_SSH_ALIAS 'T=$(cat ~/.coolify-token); curl -s -X GET -H \"Authorization: Bearer $T\" \"http://localhost:8000/api/v1/deploy?uuid=REPLACE_WITH_COOLIFY_APPLICATION_UUID\"'"
+}

package/framework/templates/infrastructure/github/README.md

@@ -1,16 +1,16 @@
 # GitHub Actions Templates for MORPH-SPEC
 
-> **Framework-Level CI/CD Templates for EasyPanel/Docker Deployments**
+> **Framework-Level CI/CD Templates for Coolify/Docker Deployments**
 
 ## Overview
 
-Reusable GitHub Actions workflows and composite actions for the **nextjs-neon** stack (EasyPanel/Docker deployment).
+Reusable GitHub Actions workflows and composite actions for the **nextjs-neon** stack (Coolify/Docker deployment).
 
 **Key Features:**
 - Handlebars v2.0 templating with helpers
 - Composite actions for shared logic
 - Docker multi-stage builds (.NET API + Next.js Web)
-- EasyPanel webhook deployment
+- Coolify deployment via SSH (no MCP/CLI exists — the Coolify API is not publicly exposed, so the runner SSHes into the VPS to trigger it)
 
 ---
 
@@ -21,7 +21,7 @@ infrastructure/github/
 ├── workflows/
 │   ├── dotnet-build.yml.hbs       # .NET restore, build, test, coverage
 │   ├── docker-build-push.yml.hbs  # Docker build & push to registry
-│   └── deploy-easypanel.yml.hbs   # EasyPanel deployment via webhook
+│   └── deploy-coolify.yml.hbs     # Coolify deployment via SSH
 │
 └── actions/
     ├── docker-build-push/action.yml.hbs   # Build & push Docker image
@@ -38,8 +38,8 @@ infrastructure/github/
 - Multi-stage Docker build
 - Push to container registry (GHCR or Docker Hub)
 
-### Deploy EasyPanel (`deploy-easypanel.yml.hbs`)
-- Triggers EasyPanel webhook after Docker push
+### Deploy Coolify (`deploy-coolify.yml.hbs`)
+- SSHes into the VPS and calls the local Coolify API (`localhost:8000/api/v1/deploy?uuid=...`) after Docker push
 - Runs health check after deployment
 - Supports staging + production environments
 

package/framework/templates/infrastructure/github/workflows/deploy-coolify.yml.hbs

@@ -0,0 +1,33 @@
+name: Deploy to Coolify
+
+on:
+  workflow_call:
+    inputs:
+      environment:
+        required: true
+        type: string
+      image:
+        required: true
+        type: string
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: ${{{{ inputs.environment }}}}
+    steps:
+      - name: Configure SSH
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{{{ secrets.COOLIFY_SSH_KEY }}}}" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          ssh-keyscan -H ${{{{ secrets.COOLIFY_SSH_HOST }}}} >> ~/.ssh/known_hosts
+
+      - name: Trigger Coolify Deploy (via SSH — the Coolify API is not publicly exposed)
+        run: |
+          ssh -i ~/.ssh/id_ed25519 ${{{{ secrets.COOLIFY_SSH_USER }}}}@${{{{ secrets.COOLIFY_SSH_HOST }}}} \
+            'T=$(cat ~/.coolify-token); curl -s -X GET -H "Authorization: Bearer $T" "http://localhost:8000/api/v1/deploy?uuid=${{{{ secrets.COOLIFY_APPLICATION_UUID }}}}"'
+
+      - name: Health Check
+        run: |
+          sleep 30  # Wait for deployment
+          curl --retry 10 --retry-delay 5 --retry-connrefused ${{{{ secrets.APP_URL }}}}/health

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "7.5.0",
+  "version": "7.6.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/framework/templates/infrastructure/docker/easypanel.template.json

@@ -1,46 +0,0 @@
-{
-  "name": "{{kebabCase FEATURE_NAME}}",
-  "services": [
-    {
-      "type": "app",
-      "data": {
-        "projectName": "{{kebabCase FEATURE_NAME}}",
-        "serviceName": "{{kebabCase FEATURE_NAME}}-app",
-        "source": {
-          "type": "github",
-          "owner": "{{GITHUB_OWNER}}",
-          "repo": "{{GITHUB_REPO}}",
-          "ref": "main",
-          "autoDeploy": true
-        },
-        "build": {
-          "type": "dockerfile",
-          "dockerfile": "Dockerfile"
-        },
-        "deploy": {
-          "replicas": 1,
-          "command": null,
-          "zeroDowntime": true
-        },
-        "env": [
-          {
-            "key": "NODE_ENV",
-            "value": "production"
-          },
-          {
-            "key": "DATABASE_URL",
-            "value": "${DATABASE_URL}"
-          }
-        ],
-        "domains": [
-          {
-            "host": "{{kebabCase FEATURE_NAME}}.easypanel.host",
-            "port": 3000,
-            "https": true
-          }
-        ],
-        "mounts": []
-      }
-    }
-  ]
-}

package/framework/templates/infrastructure/github/workflows/deploy-easypanel.yml.hbs

@@ -1,31 +0,0 @@
-name: Deploy to EasyPanel
-
-on:
-  workflow_call:
-    inputs:
-      environment:
-        required: true
-        type: string
-      image:
-        required: true
-        type: string
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    environment: ${{{{ inputs.environment }}}}
-    steps:
-      - name: Trigger EasyPanel Deploy
-        run: |
-          curl -X POST ${{{{ secrets.EASYPANEL_WEBHOOK_URL }}}} \
-            -H "Authorization: Bearer ${{{{ secrets.EASYPANEL_API_TOKEN }}}}" \
-            -H "Content-Type: application/json" \
-            -d '{
-              "image": "${{{{ inputs.image }}}}",
-              "environment": "${{{{ inputs.environment }}}}"
-            }'
-
-      - name: Health Check
-        run: |
-          sleep 30  # Wait for deployment
-          curl --retry 10 --retry-delay 5 --retry-connrefused ${{{{ secrets.APP_URL }}}}/health