Production Deployment

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CONTRIBUTING.md
• supabase/config.toml
• SECURITY.md
• apps/web/lib/metadata.ts
• release-please-config.json
• apps/web/emails/README.md

Production deployment for Kocteau involves a coordinated release of a Next.js web application and a Supabase cloud infrastructure. The system is designed as a monorepo where apps/web serves as the primary production surface, while the backend relies on Supabase for authentication, PostgreSQL database management, and file storage.

The deployment process is automated using Release Please, which handles versioning and changelog generation based on conventional commits. Security is maintained through strict environment variable separation, ensuring that privileged keys (such as Supabase service roles) are never exposed to the client-side or public documentation.

Deployment Architecture

The production environment consists of a Next.js frontend (typically hosted on Vercel) and a Supabase Cloud backend. The frontend communicates with Supabase via the client SDK using public publishable keys, while sensitive operations are handled through server routes or Supabase RPCs.

The diagram shows the high-level flow between the Next.js frontend, Supabase backend services, and external integrations for music data and email delivery.
Sources: README.md, apps/web/lib/metadata.ts:7-13

Release Automation and Versioning

Kocteau utilizes Release Please to automate the creation of GitHub Releases and the maintenance of the CHANGELOG.md.

Conventional Commits

The release pipeline relies on specific PR title patterns to determine version bumps:

• fix(...): Triggers a patch version bump.
• feat(...): Triggers a minor version bump.
• chore(release): Used for version tagging and publishing.

Sources: CONTRIBUTING.md:68-81, release-please-config.json

Release Workflow

1. Contributors open PRs with clear titles.
2. Release Please aggregates these into a "Release PR" on the main branch.
3. Maintainers merge the Release PR to trigger versioning, tagging, and GitHub Release creation.

Sources: CONTRIBUTING.md:88-93, release-please-config.json

Infrastructure and Configuration

Production infrastructure is managed through the Supabase CLI and environment-specific configuration files.

Supabase Cloud Migrations

Maintainers use a pinned version of the Supabase CLI to push changes to production. The process involves linking to the cloud project and performing a dry run before applying migrations.

Command	Purpose
pnpm supabase:link --project-ref <ref>	Connects the local environment to the production project.
pnpm supabase:db:push:dry	Validates migrations against the production schema without applying them.
pnpm supabase:db:push	Applies schema, RLS, and RPC changes to production.

Sources: README.md:175-184

Production Environment Variables

Environment variables are strictly categorized to prevent security leaks. Public variables are prefixed with NEXT_PUBLIC_, while secret keys remain server-side.

Variable	Scope	Description
NEXT_PUBLIC_SITE_URL	Public	The canonical production URL (e.g., https://kocteau.com).
NEXT_PUBLIC_SUPABASE_URL	Public	The Supabase project API URL.
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	Public	Browser-safe key for Supabase client interactions.
SUPABASE_SERVICE_ROLE_KEY	Secret	Privileged key for bypass RLS (Never exposed to frontend).
RESEND_API_KEY	Secret	Used for SMTP email delivery via Supabase Auth.

Sources: README.md:143-157, SECURITY.md:23-28

Authentication and Email Delivery

In production, Kocteau uses an OTP-first (One-Time Password) flow. This avoids complex password management and improves security.

Email Configuration

Supabase Auth is configured to use Resend as the SMTP provider. Production email templates are code-only and do not include magic link URLs to avoid confusing redirection loops.

The sequence shows the OTP verification flow where the user remains within the application UI to complete authentication.
Sources: README.md:213-221, apps/web/emails/README.md:13-26

Email Template Requirements

• Template Path: supabase/templates/supabase-otp-template.html
• Placeholder: Must use {{ .Token }} for the 6-digit code.
• Constraint: Confirm email must be enabled in the Supabase dashboard.

Sources: supabase/config.toml:191-198, apps/web/emails/README.md:17-21

Site Metadata and SEO

Production deployment includes a dynamic metadata resolver to handle social previews (Open Graph) and SEO.

// apps/web/lib/metadata.ts
export function createPageMetadata({
  title,
  description = DEFAULT_DESCRIPTION,
  path,
  image,
  noIndex = false,
}: CreatePageMetadataOptions): Metadata {
  const fullTitle = withSiteName(title);
  const canonical = normalizePath(path);
  // ... resolver logic
  return {
    title,
    description,
    openGraph: {
      title: fullTitle,
      description,
      type: "website",
      url: canonical,
      images: [openGraphImageDescriptor],
    },
    // ...
  };
}

Sources: apps/web/lib/metadata.ts:70-108

Security Policies

Production security relies on Row Level Security (RLS) within Supabase and proper secret management.

• Private Reporting: Security vulnerabilities must be reported through GitHub private advisories.
• Service Roles: Service role keys and database passwords must never be committed to the repository or posted in public channels.
• Rate Limiting: Production rate limiting is handled directly in PostgreSQL to avoid external dependencies like Redis.

Sources: SECURITY.md:5-20, README.md:100

Conclusion

Production deployment of Kocteau is a balance of automated release cycles and strict infrastructure management. By leveraging Release Please for versioning and Supabase for backend services, the project maintains a "web-first" production surface that is resilient, secure, and easily maintainable through standard CLI workflows.