add cline docs

Reviewed-on: http://gitea.lan:3000/robbond/pleskSaas/pulls/57

.clinerules

@@ -0,0 +1,36 @@
+# Project AI Rules
+
+This repository contains the Plesk Agency Portal SaaS project.
+
+Before making changes, read the following documentation files:
+
+docs/ai-bootstrap.md
+docs/ai-project-context.md
+docs/system-architecture.md
+docs/GUARDRAILS.md
+docs/next-steps.md
+docs/handovers/latest.md
+docs/current-focus.md
+
+Project guidelines:
+
+- Treat master branch as production-ready.
+- Preserve the working Jenkins CI/CD deployment pipeline.
+- Avoid breaking Supabase Row Level Security policies.
+- Prefer minimal changes over large rewrites.
+- Follow existing Next.js App Router structure.
+
+Deployment architecture:
+
+Jenkins builds Docker image.
+Image transferred using:
+docker save → scp → docker load
+
+Application host path:
+/opt/plesk-agency-portal
+
+Public domain:
+https://portal.rdbcloud.co.uk
+
+Supabase domain
+https://supabase.rdbcloud.co.uk

AI-START-HERE.md

@@ -0,0 +1,45 @@
+# AI Start Here
+
+Before making changes, read these files in order:
+
+1. docs/ai-project-context.md
+2. docs/system-architecture.md
+3. docs/next-steps.md
+4. docs/handovers/latest.md (or the newest dated handover file)
+
+## Project
+
+Plesk Agency Portal
+
+## Rules
+
+- Make minimal safe changes
+- Do not weaken Supabase RLS
+- Preserve working deployment pipeline
+- Prefer extending existing patterns over rewrites
+- Treat `master` as production-ready
+
+## Current Focus
+
+- Fix Supabase HTTPS/public URL
+- Validate auth flow
+- Keep CI/CD stable
+
+## Deployment Summary
+
+- Jenkins builds Docker image
+- Image transferred via `docker save -> scp -> docker load`
+- App runs on `/opt/plesk-agency-portal`
+- Public app URL: `https://portal.rdbcloud.co.uk`
+- supabase URL: `https://supabase.rdbcloud.co.uk`
+
+## Notes
+
+Use the docs folder as source of truth for current state and handover history.
+
+## When updating the project
+
+- update docs/ai-project-context.md for current state
+- add a new file in docs/handovers/
+- update docs/next-steps.md
+- keep this file short

Jenkinsfile

@@ -85,28 +85,36 @@ pipeline {
 
 stage('Deploy') {
   steps {
-    withCredentials([sshUserPrivateKey(
-      credentialsId: "${env.DEPLOY_SSH_CREDENTIAL_ID}",
-      keyFileVariable: 'SSH_KEY'
-    )]) {
-      sh '''
-bash <<EOF
+    sh '''
+bash <<'EOF'
 set -euxo pipefail
 
+SSH_KEY="/var/lib/jenkins/.ssh/plesk_agency_deploy"
+SSH_USER="deploy"
+SSH_OPTS="-i ${SSH_KEY} -o BatchMode=yes -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null"
+
+echo "SSH user from configured deploy key: ${SSH_USER}"
+echo "SSH key file path: ${SSH_KEY}"
+ls -l "${SSH_KEY}"
+ssh-keygen -y -f "${SSH_KEY}"
+
+echo "Testing remote SSH connectivity"
+ssh -n ${SSH_OPTS} "${SSH_USER}@${APP_HOST}" "whoami && hostname && pwd"
+
 echo "Deploying image tag: ${IMAGE_BUILD}"
 docker image inspect "${IMAGE_BUILD}" --format='{{.Id}} {{.RepoTags}}'
 
-ssh -i "$SSH_KEY" "$APP_USER@$APP_HOST" "mkdir -p $DEPLOY_PATH/scripts"
+ssh -n ${SSH_OPTS} "$SSH_USER@$APP_HOST" "mkdir -p $DEPLOY_PATH/scripts"
 
 rsync -az \
-  -e "ssh -i $SSH_KEY" \
+  -e "ssh -n ${SSH_OPTS}" \
   docker-compose.prod.yml \
-  "$APP_USER@$APP_HOST:$DEPLOY_PATH/"
+  "$SSH_USER@$APP_HOST:$DEPLOY_PATH/"
 
 rsync -az \
-  -e "ssh -i $SSH_KEY" \
+  -e "ssh -n ${SSH_OPTS}" \
   scripts/ \
-  "$APP_USER@$APP_HOST:$DEPLOY_PATH/scripts/"
+  "$SSH_USER@$APP_HOST:$DEPLOY_PATH/scripts/"
 
 IMAGE_TAR="plesk-agency-portal-build.tar"
 echo "Creating image archive: ${IMAGE_TAR}"
@@ -115,30 +123,29 @@ ls -lh "${IMAGE_TAR}"
 sha256sum "${IMAGE_TAR}"
 
 echo "Copying image archive to remote host via scp"
-scp -i "$SSH_KEY" "${IMAGE_TAR}" "$APP_USER@$APP_HOST:$DEPLOY_PATH/"
+scp ${SSH_OPTS} "${IMAGE_TAR}" "$SSH_USER@$APP_HOST:$DEPLOY_PATH/"
 
 echo "Verifying image archive exists on remote host"
-ssh -i "$SSH_KEY" "$APP_USER@$APP_HOST" "ls -lh $DEPLOY_PATH/plesk-agency-portal-build.tar"
-ssh -i "$SSH_KEY" "$APP_USER@$APP_HOST" "sha256sum $DEPLOY_PATH/plesk-agency-portal-build.tar"
+ssh -n ${SSH_OPTS} "$SSH_USER@$APP_HOST" "ls -lh $DEPLOY_PATH/plesk-agency-portal-build.tar"
+ssh -n ${SSH_OPTS} "$SSH_USER@$APP_HOST" "sha256sum $DEPLOY_PATH/plesk-agency-portal-build.tar"
 
 echo "Loading image archive on remote host"
-ssh -i "$SSH_KEY" "$APP_USER@$APP_HOST" "docker load -i $DEPLOY_PATH/plesk-agency-portal-build.tar"
+ssh -n ${SSH_OPTS} "$SSH_USER@$APP_HOST" "docker load -i $DEPLOY_PATH/plesk-agency-portal-build.tar"
 
 echo "Verifying exact image tag is available on remote host"
-ssh -i "$SSH_KEY" "$APP_USER@$APP_HOST" "docker image inspect ${IMAGE_BUILD} --format='{{.Id}} {{.RepoTags}}'"
+ssh -n ${SSH_OPTS} "$SSH_USER@$APP_HOST" "docker image inspect ${IMAGE_BUILD} --format='{{.Id}} {{.RepoTags}}'"
 
-ssh -i "$SSH_KEY" "$APP_USER@$APP_HOST" \
+ssh -n ${SSH_OPTS} "$SSH_USER@$APP_HOST" \
   "cd $DEPLOY_PATH && chmod +x ./scripts/deploy-prod.sh ./scripts/smoke-check.sh ./scripts/rollback-prod.sh"
 
 echo "Running remote deploy script with exact image tag"
-ssh -i "$SSH_KEY" "$APP_USER@$APP_HOST" \
+ssh -n ${SSH_OPTS} "$SSH_USER@$APP_HOST" \
   "cd $DEPLOY_PATH && APP_IMAGE='${IMAGE_BUILD}' ./scripts/deploy-prod.sh"
 
 echo "Printing final running container image metadata"
-ssh -i "$SSH_KEY" "$APP_USER@$APP_HOST" "docker inspect plesk-agency-portal --format='{{.Image}} {{.Created}}'"
+ssh -n ${SSH_OPTS} "$SSH_USER@$APP_HOST" "docker inspect plesk-agency-portal --format='{{.Image}} {{.Created}}'"
 EOF
-      '''
-    }
+    '''
   }
 }
 

docs/GUARDRAILS.md

@@ -0,0 +1,38 @@
+# GUARDRAILS
+
+These systems are currently working and must not be broken by AI refactors.
+
+## CI/CD
+
+Jenkins pipeline builds Docker image and deploys it.
+
+Deployment process:
+
+docker save → scp → docker load
+
+## Container
+
+Name:
+plesk-agency-portal
+
+Deploy path:
+/opt/plesk-agency-portal
+
+## Reverse Proxy
+
+Managed by Nginx Proxy Manager
+
+Public URL:
+
+https://portal.rdbcloud.co.uk
+
+## Auth
+
+Supabase Magic Link authentication
+
+Environment variables:
+
+NEXT_PUBLIC_SUPABASE_URL
+SUPABASE_URL
+
+AI tools must avoid large rewrites or architectural changes without explicit instruction.

docs/PROJECT-STATE.md

@@ -0,0 +1,43 @@
+# PROJECT-STATE
+
+## Stable Systems
+
+The following are stable and working:
+
+CI/CD pipeline
+Docker deployment
+Reverse proxy routing
+Application container startup
+Smoke test endpoint
+
+## Deployment
+
+Jenkins → Build → Docker image → docker save → SCP → docker load → container recreate
+
+App path:
+
+/opt/plesk-agency-portal
+
+Container:
+
+plesk-agency-portal
+
+## Public Endpoint
+
+https://portal.rdbcloud.co.uk
+
+## Current Work
+
+Fix Supabase HTTPS endpoint and authentication flow.
+
+## Known Risk
+
+Supabase currently exposed via HTTP internally causing browser mixed content blocking.
+
+## Update Rules
+
+When system changes:
+
+1. Update PROJECT-STATE.md
+2. Update ai-project-context.md
+3. Add a new handover file

docs/RUNBOOK.md

@@ -0,0 +1,58 @@
+# RUNBOOK
+
+## Production App
+
+Host:
+192.168.68.89
+
+Deploy path:
+/opt/plesk-agency-portal
+
+Container:
+plesk-agency-portal
+
+Public URL:
+https://portal.rdbcloud.co.uk
+
+---
+
+## Health Check
+
+Public:
+
+curl https://portal.rdbcloud.co.uk/api/health
+
+Local:
+
+curl http://127.0.0.1:3000/api/health
+
+---
+
+## Check Running Container
+
+docker ps
+docker inspect plesk-agency-portal --format '{{.Image}} {{.Created}}'
+docker images | grep plesk-agency-portal
+
+---
+
+## View Logs
+
+cd /opt/plesk-agency-portal
+docker compose -f docker-compose.prod.yml logs --tail=200
+
+Follow logs:
+
+docker logs -f plesk-agency-portal
+
+---
+
+## Rollback
+
+cd /opt/plesk-agency-portal
+APP_IMAGE=plesk-agency-portal:build-37 ./scripts/rollback-prod.sh
+
+Verify:
+
+docker inspect plesk-agency-portal --format '{{.Image}} {{.Created}}'
+curl http://127.0.0.1:3000/api/health

docs/ai-bootstrap.md

@@ -0,0 +1,191 @@
+# AI Bootstrap Context -- Plesk Agency Portal
+
+This document is intended to be uploaded into a new AI conversation so
+the assistant can quickly understand the project state.
+
+------------------------------------------------------------------------
+
+# Project Overview
+
+The **Plesk Agency Portal** is a multi-tenant SaaS platform that allows
+agencies to manage multiple Plesk servers, hosting subscriptions, and
+domains from a single interface.
+
+Goals:
+
+-   Connect multiple Plesk servers
+-   Sync subscriptions and domains
+-   Manage hosting environments
+-   Provide SaaS billing integration
+-   Enforce tenant isolation using Supabase Row Level Security (RLS)
+
+------------------------------------------------------------------------
+
+# Technology Stack
+
+Frontend Next.js (App Router)
+
+Backend Next.js API routes
+
+Authentication Supabase Auth (Magic Link)
+
+Database Supabase PostgreSQL
+
+CI/CD Jenkins
+
+Containerisation Docker
+
+Reverse Proxy Nginx Proxy Manager
+
+Infrastructure Self-hosted Linux servers
+
+------------------------------------------------------------------------
+
+# Current Deployment Architecture
+
+CI/CD Pipeline:
+
+1.  Code pushed to repository
+2.  Jenkins pipeline runs
+3.  Next.js application builds
+4.  Docker image builds
+5.  Image exported via `docker save`
+6.  Image transferred via SSH/SCP
+7.  Image loaded on application host
+8.  Container recreated
+9.  Smoke test verifies service
+
+Images are transferred using:
+
+docker save → scp → docker load
+
+This avoids requiring a Docker registry during early development.
+
+------------------------------------------------------------------------
+
+# Infrastructure
+
+Jenkins Host Responsible for:
+
+-   building Docker images
+-   running CI/CD pipeline
+-   deploying containers
+
+Application Host
+
+Deployment path:
+
+/opt/plesk-agency-portal
+
+Docker container:
+
+plesk-agency-portal
+
+Application port:
+
+3000
+
+Reverse Proxy:
+
+Nginx Proxy Manager
+
+Public domain:
+
+https://portal.rdbcloud.co.uk
+
+------------------------------------------------------------------------
+
+# Database & Auth
+
+Supabase is self-hosted on an internal server.
+
+Current API endpoint:
+
+http://192.168.68.52:54321
+
+Because the portal runs via HTTPS, this causes a browser mixed-content
+error.
+
+------------------------------------------------------------------------
+
+# Current Blocking Issue
+
+Supabase authentication fails because the frontend attempts to call:
+
+http://192.168.68.52:54321
+
+while the portal itself is served via HTTPS.
+
+Browsers block the request.
+
+------------------------------------------------------------------------
+
+# Planned Fix
+
+Expose Supabase through HTTPS using Nginx Proxy Manager.
+
+Target domain:
+
+https://supabase.rdbcloud.co.uk
+
+Proxy configuration:
+
+Forward host: 192.168.68.52\
+Forward port: 54321
+
+After that update environment variables:
+
+NEXT_PUBLIC_SUPABASE_URL SUPABASE_URL
+
+Then redeploy the portal.
+
+------------------------------------------------------------------------
+
+# Deployment Verification
+
+Example deployed image:
+
+plesk-agency-portal:build-62
+
+Verification command:
+
+docker inspect plesk-agency-portal --format '{{.Image}} {{.Created}}'
+
+Health endpoint:
+
+/api/health
+
+------------------------------------------------------------------------
+
+# Repository Documentation
+
+Important docs:
+
+docs/ai-project-context.md\
+docs/system-architecture.md\
+docs/next-steps.md\
+docs/handovers/\*
+
+------------------------------------------------------------------------
+
+# Typical AI Assistance Areas
+
+-   CI/CD debugging
+-   Docker deployment
+-   Next.js development
+-   Supabase integration
+-   SaaS multi-tenant architecture
+-   Stripe billing integration
+-   Plesk API integration
+
+------------------------------------------------------------------------
+
+# Current Development Stage
+
+Infrastructure and deployment pipeline are working.
+
+Next priorities:
+
+1.  Fix Supabase HTTPS endpoint
+2.  Verify authentication flow
+3.  Continue SaaS portal feature development

docs/current-focus.md

@@ -0,0 +1,7 @@
+# Current Focus
+
+Immediate tasks:
+
+1. Fix Supabase HTTPS endpoint
+2. Verify authentication flow
+3. Continue SaaS portal feature development

docs/handovers/2026-03-07-cicd-deploy-working.md

@@ -0,0 +1,100 @@
+# Handover – 2026-03-07 – CI/CD Deploy Working
+
+## Status
+
+The Plesk Agency Portal deployment pipeline is now working end‑to‑end.
+
+### Jenkins Pipeline
+
+Pipeline successfully performs:
+
+1. Build Next.js application
+2. Build Docker image
+3. Save image archive
+4. Transfer archive to app host
+5. Load image on remote server
+6. Recreate container
+7. Run smoke test
+
+Example deployed image:
+
+plesk-agency-portal:build-62
+
+Verification command:
+
+docker inspect plesk-agency-portal --format '{{.Image}} {{.Created}}'
+
+---
+
+## Infrastructure
+
+### Jenkins Host
+
+Responsibilities:
+
+- Build Docker images
+- Execute CI/CD pipeline
+- Transfer deployment artifacts
+
+### Application Host
+
+Deployment path:
+
+/opt/plesk-agency-portal
+
+Container:
+
+plesk-agency-portal
+
+Application port:
+
+3000
+
+---
+
+## Reverse Proxy
+
+Managed using:
+
+Nginx Proxy Manager
+
+Public domain:
+
+https://portal.rdbcloud.co.uk
+
+---
+
+## Known Issue
+
+Supabase authentication blocked due to mixed content.
+
+Frontend attempts:
+
+http://192.168.68.52:54321
+
+while the site runs via HTTPS.
+
+---
+
+## Next Task
+
+Expose Supabase API through HTTPS:
+
+https://supabase.rdbcloud.co.uk
+
+Then update environment variables:
+
+NEXT_PUBLIC_SUPABASE_URL
+SUPABASE_URL
+
+and redeploy the application.
+
+---
+
+## Deployment Strategy
+
+Docker registry intentionally avoided.
+
+Images transferred using:
+
+docker save → scp → docker load