Plesk Agency Management Portal (MVP)

Next.js + Tailwind + Supabase + Stripe multi-tenant SaaS starter for agencies managing one or more Plesk instances.

Included MVP Features

• Supabase Postgres schema + RLS (supabase/schema.sql)
• Supabase Auth (magic-link login)
• Agency tenancy context (agency_members based)
• Dashboard with:
  • Plesk instance connect + validation
  • Plesk sync (subscriptions + domains)
  • Subscription suspend / unsuspend actions
  • Stripe checkout + billing portal launch
• Stripe webhook endpoint to sync billing state

1) Setup

1. Install dependencies:

npm install

2. Create local env:

cp .env.example .env.local

3. Fill .env.local with your Supabase + Stripe values.

4. In Supabase SQL Editor, run:

-- contents of supabase/schema.sql

5. In Supabase Auth settings, set site URL and redirect URL(s), e.g.:

• http://localhost:3000
• http://localhost:3000/dashboard

6. Run dev server:

npm run dev

2) Seed Minimum Data

After first login user is created in auth.users, then add membership rows (via SQL) so tenant context resolves:

insert into agencies (name) values ('My Agency') returning id;

-- replace values
insert into agency_members (agency_id, user_id, role)
values ('<agency_uuid>', '<auth_user_uuid>', 'owner');

3) API Endpoints

• POST /api/plesk/instances — create + validate Plesk connection
• POST /api/plesk/instances/:id/sync — pull/sync subscriptions + domains from one Plesk instance
• POST /api/plesk/instances/:id/autosync — update auto-sync enabled/frequency for one Plesk instance
• POST /api/jobs/plesk-sync-all — background sync job for all connected instances (requires X-JOB-SECRET)
• POST /api/cron/autosync — scheduled auto-sync tick (requires X-CRON-SECRET)
• POST /api/plesk/subscriptions/:id/action — suspend or unsuspend
• POST /api/stripe/checkout — create Stripe Checkout session
• POST /api/stripe/portal — create Stripe Customer Portal session
• POST /api/stripe/webhook — Stripe webhook receiver

4) Important Notes

• Set a strong ENCRYPTION_KEY; it encrypts stored Plesk auth secrets.
• Set a strong PLESK_CRED_ENC_KEY (32-byte base64 or 64-char hex) for Plesk credential encryption.
• Set JOB_SECRET for internal cron-triggered job auth.
• Set CRON_SECRET for /api/cron/autosync auth.
• /api/stripe/webhook is excluded from auth middleware for Stripe signature verification.
• Current implementation is intentionally MVP-focused; add stronger validation, retries, idempotency keys, and richer error observability for production.

5) Automatic Plesk Auto-Sync (CL3.5)

Background auto-sync endpoint:

curl -sS -X POST http://localhost:3000/api/jobs/plesk-sync-all \
  -H "X-JOB-SECRET: <JOB_SECRET>"

Recommended cron (every 5 minutes):

*/5 * * * * curl -sS -X POST http://localhost:3000/api/jobs/plesk-sync-all -H "X-JOB-SECRET: ${JOB_SECRET}"

Notes:

• Job uses DB lock (job_locks) to avoid overlapping runs.
• Job processes at most 10 connected instances per run.
• Instances synced in the last 3 minutes are skipped.

6) Auto Sync Worker (CL6)

New scheduler fields live on plesk_instances:

• auto_sync_enabled
• auto_sync_frequency_minutes
• last_auto_sync_at
• next_auto_sync_at
• auto_sync_lock_until
• auto_sync_lock_token

Endpoint for periodic worker ticks:

curl -sS -X POST http://localhost:3000/api/cron/autosync \
  -H "X-CRON-SECRET: <CRON_SECRET>"

Recommended system cron (every 5 minutes):

*/5 * * * * curl -sS -X POST https://<your-host>/api/cron/autosync -H "X-CRON-SECRET: ${CRON_SECRET}"

Or schedule the same call from Jenkins.

Worker safety behavior:

• processes at most 5 instances per tick
• concurrency limited to 2 at a time
• per-instance lock lease 15 minutes
• per-instance timeout guard 14 minutes
• per-instance failures are isolated and logged to actions_log