Banata

Deployment

Self-Hosted Quick Start

Deploy the full Banata platform on your own infrastructure.

This guide is for operators self-hosting Banata itself.

It is not a customer-app quickstart for embedding auth locally. Self-hosting Banata still means:

  1. deploy a Banata dashboard and backend
  2. sign in to that dashboard
  3. create a project
  4. create a project-scoped API key
  5. point apps at that self-hosted Banata instance with the same SDKs and frontend helpers

What You Are Deploying

The self-hosted stack keeps Banata's normal product shape:

  • dashboard-first setup
  • project-scoped API keys
  • Banata-managed users, sessions, organizations, and templates
  • Banata-managed email delivery and auth configuration
  • app-side integration through @banata-auth/sdk, @banata-auth/nextjs, and @banata-auth/react

Platform Runtime Files

The self-hosted platform still keeps a small amount of local Convex wiring:

text
convex/
|-- convex.config.ts
|-- auth.config.ts
|-- authNode.ts
|-- http.ts
`-- banataAuth/
    |-- auth.ts
    |-- adapter.ts
    `-- schema.ts

The packaged component provides the component registration, packaged schema, and packaged migrations. The local banataAuth/ folder only keeps the files that still need deployment env, runtime config, or Convex codegen anchoring.

See Convex Integration for the exact file responsibilities.

Operator Setup

  1. Deploy the Banata dashboard app
  2. Deploy the Convex backend for that Banata instance
  3. Configure email providers and templates in the dashboard
  4. Sign in to the dashboard as an operator
  5. Create a project for the customer or internal app
  6. Create a project-scoped API key

At that point the app integration looks the same as hosted Banata.

App Integration Example

ts
// src/lib/auth-server.ts
import { createBanataAuthServer } from "@banata-auth/nextjs/server";
 
export const {
  handler,
  isAuthenticated,
  getToken,
  preloadAuthQuery,
  fetchAuthQuery,
  fetchAuthMutation,
  fetchAuthAction,
} = createBanataAuthServer({
  convexUrl: process.env.NEXT_PUBLIC_CONVEX_URL!,
  convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
  apiKey: process.env.BANATA_API_KEY!,
});
ts
// src/app/api/auth/[...all]/route.ts
import { handler } from "@/lib/auth-server";
 
export const { GET, POST, PUT, PATCH, DELETE } = handler;
ts
// src/lib/auth-client.ts
import { createAuthClient } from "@banata-auth/react/plugins";
 
export const authClient = createAuthClient({
  baseURL: "/api/auth",
});

Environment Variables

For the customer app:

bash
NEXT_PUBLIC_CONVEX_URL=https://your-banata-instance.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://your-banata-instance.convex.site
NEXT_PUBLIC_SITE_URL=http://localhost:3000
BANATA_API_KEY=sk_test_your_project_key

For the Banata platform deployment itself, follow:

Important Rule

Do not treat @banata-auth/convex as the normal first-run integration for customer apps.

Customer apps should not become usable auth runtimes just because someone copied local Convex config into their repo. Authentication is meant to start only after a Banata dashboard project exists and a project-scoped API key has been issued.