SaaS template

This is not gonna make You rich, but it sure as hell will save you a lot of time!

This is production ready setup for Convex and Next SaaS.

Features

Auth
Stripe
shadcn/create UI templte
next intl
next themes
Backend/Frontend Tests
CICD
accurate instructions

Development process

Environments

Dev cloud environment - based on develop branch
Prod cloud environment - based on main branch

Getting Started

First, run the development server:

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

Convex

Source of truth

Go on Coolify, search for Convex and set it up.

Important

Best case: copy config from here, paste it instead of Coolify's docker-compose file, then go into environment variables, copy them, paste them and the new docker-compose into an AI agent and tell him to properly map the envs to docker-compose so it's ready to deploy on coolify.

This works for Convex 1.34.0 (CLI+backend/dashboard)

services:
  backend:
    image: 'ghcr.io/get-convex/convex-backend:latest'
    stop_grace_period: 10s
    stop_signal: SIGINT
    ports:
      - '${PORT:-3210}:3210'
      - '${SITE_PROXY_PORT:-3211}:3211'
    volumes:
      - 'data:/convex/data'
    environment:
      APPLICATION_MAX_CONCURRENT_MUTATIONS: '${APPLICATION_MAX_CONCURRENT_MUTATIONS:-16}'
      APPLICATION_MAX_CONCURRENT_NODE_ACTIONS: '${APPLICATION_MAX_CONCURRENT_NODE_ACTIONS:-16}'
      APPLICATION_MAX_CONCURRENT_QUERIES: '${APPLICATION_MAX_CONCURRENT_QUERIES:-16}'
      APPLICATION_MAX_CONCURRENT_V8_ACTIONS: '${APPLICATION_MAX_CONCURRENT_V8_ACTIONS:-16}'
      INSTANCE_NAME: '${INSTANCE_NAME}'
      INSTANCE_SECRET: '${INSTANCE_SECRET}'
      CONVEX_CLOUD_ORIGIN: '${SERVICE_URL_BACKEND}'
      CONVEX_SITE_ORIGIN: '${SERVICE_URL_BACKEND_SITE}'
      DISABLE_METRICS_ENDPOINT: '${DISABLE_METRICS_ENDPOINT:-true}'
      DOCUMENT_RETENTION_DELAY: '${DOCUMENT_RETENTION_DELAY:-172800}'
      DO_NOT_REQUIRE_SSL: '${DO_NOT_REQUIRE_SSL:-true}'
      DISABLE_BEACON: '${DISABLE_BEACON:-false}'
      REDACT_LOGS_TO_CLIENT: '${REDACT_LOGS_TO_CLIENT:-false}'
      RUST_LOG: '${RUST_LOG:-info}'
      RUST_BACKTRACE: '${RUST_BACKTRACE:-0}'
      ACTIONS_USER_TIMEOUT_SECS: '${ACTIONS_USER_TIMEOUT_SECS:-600}'
      HTTP_SERVER_TIMEOUT_SECONDS: '${HTTP_SERVER_TIMEOUT_SECONDS:-300}'
      CONVEX_RELEASE_VERSION_DEV: '${CONVEX_RELEASE_VERSION_DEV:-}'
      DATABASE_URL: '${DATABASE_URL:-}'
      POSTGRES_URL: '${POSTGRES_URL:-}'
      MYSQL_URL: '${MYSQL_URL:-}'
      AWS_REGION: '${AWS_REGION:-}'
      AWS_ACCESS_KEY_ID: '${AWS_ACCESS_KEY_ID:-}'
      AWS_SECRET_ACCESS_KEY: '${AWS_SECRET_ACCESS_KEY:-}'
      AWS_SESSION_TOKEN: '${AWS_SESSION_TOKEN:-}'
      AWS_S3_FORCE_PATH_STYLE: '${AWS_S3_FORCE_PATH_STYLE:-}'
      AWS_S3_DISABLE_SSE: '${AWS_S3_DISABLE_SSE:-}'
      AWS_S3_DISABLE_CHECKSUMS: '${AWS_S3_DISABLE_CHECKSUMS:-}'
      S3_ENDPOINT_URL: '${S3_ENDPOINT_URL:-}'
      S3_STORAGE_EXPORTS_BUCKET: '${S3_STORAGE_EXPORTS_BUCKET:-}'
      S3_STORAGE_SNAPSHOT_IMPORTS_BUCKET: '${S3_STORAGE_SNAPSHOT_IMPORTS_BUCKET:-}'
      S3_STORAGE_MODULES_BUCKET: '${S3_STORAGE_MODULES_BUCKET:-}'
      S3_STORAGE_FILES_BUCKET: '${S3_STORAGE_FILES_BUCKET:-}'
      S3_STORAGE_SEARCH_BUCKET: '${S3_STORAGE_SEARCH_BUCKET:-}'
    healthcheck:
      test:
        - CMD-SHELL
        - 'curl -f http://localhost:3210/version'
      interval: 5s
      start_period: 10s
      timeout: 5s
      retries: 10
  dashboard:
    image: 'ghcr.io/get-convex/convex-dashboard:latest'
    stop_grace_period: 10s
    stop_signal: SIGINT
    ports:
      - '${DASHBOARD_PORT:-6791}:6791'
    environment:
      PORT: '6791'
      NEXT_PUBLIC_DEPLOYMENT_URL: '${SERVICE_URL_BACKEND}'
      NEXT_PUBLIC_LOAD_MONACO_INTERNALLY: '${NEXT_PUBLIC_LOAD_MONACO_INTERNALLY:-true}'
    depends_on:
      backend:
        condition: service_healthy
volumes:
  data: null

Then make sure to update domains and env vars accordingly

Deploy the service(s - dashboard and the db). It has built-in persistent storage
Connect to server with ssh, jump into a backend container with docker exec -it <name> ./generate_admin_key.sh You'll receive Your admin key and You'll be able to log into dashboard

Admin key:
self-hosted-convex|010...

Now Your base is ready. Go to .env.local and finish setting up the connection.
Run npm install (only if Your image is latest, else use a proper version)
After that You can run npx convex dev and You should be ready to go!
Time to pick a theme! Go to shadcn/create, create a theme, and simply use the received command to init this theme in Your project!

Troubleshooting

󰣇 dev/templates/convex-next-saas   main  !? ❯ npx convex dev
✖ Error: Unable to start push to https://backend-i8e44nvzhj8sxw4qm9tbu1f7.mentat.ovh
✖ Error fetching POST  https://backend-i8e44nvzhj8sxw4qm9tbu1f7.mentat.ovh/api/deploy2/start_push 400 Bad Request: BadJsonBody: Failed to deserialize the JSON body into th
e target type: appDefinition: missing field `functions` at line 1 column 272745

Solution - ensure both CLI and convex self-hosted cloud images versions are the same. If not - I suggest upgrading whatever version is lower to be higher.

5.3 KiB Raw Blame History Unescape Escape