sc-convex

/sc-convex — Convex on Dokploy

Use this skill when the user wants to deploy, debug, or maintain a self-hosted Convex backend running on Dokploy. The repo lives at https://github.com/rahmanef63/si-coder-agent.

Connection-safe local execution

Credential-dependent local helper scripts must run through sc run -- ... when their Dokploy/Convex access lives in SI-Coder named connections. This lets one child process receive the selected provider connections without writing them to the parent shell. The command examples below show script arguments; prefix them with sc run -- unless the caller already provides the required environment.

NEVER ask the user to run Convex CLI by hand

For self-hosted Convex projects the Convex CLI (v1.27+) auto-detects the backend from .env.local (CONVEX_SELF_HOSTED_URL + CONVEX_SELF_HOSTED_ADMIN_KEY). The schema/function push happens automatically via the sc-git pre-push hook installed by /sc-all. Do not instruct the user to run npx convex deploy, pnpm convex:deploy, convex:push, or any Convex CLI command interactively. If the hook is not installed, install it yourself (node ~/.claude/skills/sc-git/scripts/hook.js install --repo <name>) instead of asking.

If the hook is genuinely unable to deploy (admin key invalid, backend unreachable), debug it with scripts/check-backend.js and fix root cause — do not punt the convex CLI call to the user.

Pre-requisites

• DOKPLOY_API_URL, DOKPLOY_API_KEY — Dokploy admin
• CONVEX_ADMIN_KEY (or generated on the fly from the running container)
• Optional HOSTINGER_API_TOKEN for DNS A-record automation

If anything is missing, route the user to /sc-onboarding.

CORE MANDATES (LEARNED LESSONS)

1. Self-Hosted Convex by default: never silently swap to Clerk. ALWAYS use @convex-dev/auth for new projects unless the user explicitly asks for Clerk.
2. convex/_generated is checked in: never run npx convex codegen inside Dockerfile. Generate locally with npx convex dev --once and commit the folder.
3. Admin Key Sync Rule: when generating or rotating the admin key, update BOTH the Dokploy Compose env (CONVEX_ADMIN_KEY) and the repo's local env file in a single pass. Never leave them out-of-sync.
4. PEM via REST, not CLI: npx convex env set JWT_PRIVATE_KEY "-----BEGIN..." breaks because -- is parsed as a flag. Use scripts/set-auth-env.js (admin REST /api/update_environment_variables) instead.
5. NEXT_PUBLIC_CONVEX_URL at build time: NEXT_PUBLIC_* is inlined at next build. If the Dockerfile uses a dummy URL, the deployed JS connects to the wrong server — see ## Dockerfile pattern below.
6. No Scrypt/bcrypt password hashing: Dokploy proxy kills WebSocket at >60s. Use PBKDF2 (10k iter ≈ 50ms) via WebCrypto — see ## Password hashing below.
7. Route auth:* actions via HTTP: WebSocket reconnect mid-flight aborts in-flight actions. Wrap the Convex client so auth:* goes via ConvexHttpClient — see ## Frontend pattern below.