Configuration

Onekit starts with one Bun/TypeScript app targeting web, iOS, and Android. One provides routes and the web server; Tamagui provides shared UI; Better Auth and Drizzle use PostgreSQL; SST deploys the server and API to AWS. Native binaries have a separate Expo/EAS release process.

These are editable source and environment settings. An interactive setup wizard and interchangeable billing/storage modules are not implemented.

Configuration map

src/config/app.ts is bundled into clients. It must not contain credentials. Changing a name does not automatically rename the database, SST stack, package, theme storage key, or application-store listing; review those separately when adapting the starter.

Local environment

Create an untracked .env from .env.example, generate a fresh auth secret with openssl rand -base64 32, and fill in the following values. Never reuse the example database credentials in a hosted environment.

Server configuration is validated when used. Static page generation does not require database or auth secrets. In local development, native devices need a reachable server address; use one canonical origin consistently for auth and API configuration. Restart the server or rebuild clients after changing values that are read at startup or bundled into the app.

Uploaded images go to one private bucket with keys prefixed per owner, never a bucket per workspace: an AWS account gets 100 buckets by default, creating one is a slow control-plane call nobody wants inside a signup path, and isolation here is the application refusing to serve a key it does not own. Bytes go through the service rather than a presigned URL, which is what lets the server cap the size and establish what a file actually is — the stored content type is the one it sniffed, never the one the browser claimed, and SVG is refused outright because it is XML that can carry script. Set uploads: true in infra/config.ts to deploy the bucket; SST’s link gives the task role that bucket’s policy, so no keys are configured by hand.

Onekit ships passwordless: with EMAIL_PROVIDER set and nothing else named, the sign-in screen asks for an address and emails a six-digit code. See Authentication for the whole truth table, including what happens when neither switch nor transport nor OAuth pair is configured.

The browser auth client uses the current website origin. Native auth uses ONE_PUBLIC_SERVER_URL and SecureStore. OAuth callback URLs use ${BETTER_AUTH_URL}/api/auth/callback/google or /api/auth/callback/apple. See Authentication for provider setup and current limitations.

Brand and native variants

Set your final bundle/package identifiers before configuring provider applications or store listings. Development and preview append .development and .preview to the base iOS/Android identifiers; production uses the base identifiers. Names also include the variant outside production. The URL scheme is shared by the current variants, so validate deep links with the intended build installed.

Changing the URL scheme, package identifiers, plugins, or native configuration requires rebuilding the native app. EAS profiles do not provision project ownership, signing credentials, store records, or a production API origin; configure those for your own account. Align Apple provider configuration with the actual build identifier. Update public/favicon.svg and add native icons/splash assets before release.

The shared theme preference can be changed in Settings. To create a custom visual system, edit Tamagui tokens/themes and the consuming components together; the accent field is not an automatic recoloring mechanism for every element.

Auth and database policy

Email/password is enabled with a minimum password length of eight. Password reset, confirmation, password change, and deletion work when an email provider is configured; see Email. Organizations and role management require additional schema and application work.

Generate migrations after editing the schema, review the SQL, then apply them explicitly to the intended database. Deployment does not run migrations automatically. Use separate databases and secrets per stage, and size each process’s connection pool against the total service replica count. See Database.

Row-level security

Workspace tenancy is enforced in the application: every query over the eight CRM tables carries organization_id, in one place, and tests/tenancy.test.ts holds that rule. The eight tables also carry a PostgreSQL row-level policy, as a floor under a mistake rather than as the mechanism — drizzle/0013_row_level_security.sql.

Each request runs in one transaction whose first statement is select set_config('onekit.org_id', …, true), and the policies compare organization_id against that setting. Two consequences worth planning for:

• A request holds a pooled connection for its whole life, so DATABASE_POOL_MAX now bounds concurrent requests rather than concurrent queries. Size it against expected concurrency per process, not against query volume.
• The setting is transaction-local, so this is correct behind RDS Proxy or PgBouncer in transaction pooling mode as well as session mode. The value is discarded at commit and cannot reach the next request on the same backend. Nothing in the kit issues a bare SET, which would be silently wrong under transaction pooling — do not add one.

The policies do nothing unless DATABASE_URL connects as an ordinary role. PostgreSQL bypasses row-level security for a superuser or a role with BYPASSRLS no matter what the tables say, and the kit’s Compose file ships a single superuser for convenience. The server logs one line at startup when it detects this; tenancy still holds, but the backstop is inert. To get it, create a dedicated non-owner role, run migrations as the owner, and point the app at the role:

create role onekit_app login password 'choose-a-strong-one';
grant usage on schema public to onekit_app;
grant select, insert, update, delete on all tables in schema public to onekit_app;
-- So tables created by later migrations are reachable too.
alter default privileges in schema public grant select, insert, update, delete on tables to onekit_app;

FORCE ROW LEVEL SECURITY is set on all eight tables, so a deployment that points DATABASE_URL at the owning role is still subject to the policies — ownership is safe, only the two bypasses are not.

SST settings

infra/config.ts defaults to us-east-1, ARM64, port 3000, and local development port 8081. Production requests 0.5 vCPU/1 GB with one to two instances; other stages request 0.25 vCPU/0.5 GB with one instance. The deployed service and load balancer have ongoing infrastructure costs. PostgreSQL is Amazon RDS in the same stack by default (infraConfig.database); ONEKIT_DATABASE=external uses your own instead.

SST requires BetterAuthSecret, ZeroDbPassword and ZeroAdminPassword secrets for each stage, plus DatabaseUrl and ZeroUpstreamDb with an external database. Enable infraConfig.oauth.google or .apple and set the corresponding provider secret pair to deploy social login. Set infraConfig.email.from to a verified SES identity to deploy email delivery with the ses:SendEmail task permission. Setting only local .env values does not change the deployed service.

The domain determines the deployed public/auth origins. Production is protected and retains resources on removal; other stages use removal behavior. Review stack and stage identity before renaming either. Changing ports also requires keeping package scripts, Docker configuration, and health checks aligned. Follow Deployment for exact commands and prerequisites.

Next configuration rounds

Introduce additional options as complete, documented configurations. Test supported combinations before treating them as a buyer-facing feature.