Environment Variables

Owlat uses environment variables to configure payments, email sending, authentication, and feature flags. Backend variables are set via the Convex dashboard; frontend variables live in .env files.

Self-hosted configuration

Self-hosters put everything in a single .env file at the repo root. Start from the template:

cp .env.selfhost.example .env

The template and docker-compose.yml reference these variables:

Required secrets

Public URLs

MTA (mail sending)

Deployment mode

Port overrides (optional)

All ports default to sensible values. Override only if the defaults conflict:

# CONVEX_PORT=3210
# CONVEX_SITE_PORT=3211
# DASHBOARD_PORT=6791
# WEB_PORT=3000
# MTA_HTTP_PORT=3100
# MTA_SMTP_PORT=25
# REDIS_PORT=6379
# CLAMAV_PORT=3310

Optional: PostHog analytics

# NUXT_PUBLIC_POSTHOG_API_KEY=
# NUXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com

Where to Set Variables

Convex backend — tenant app (all process.env references in apps/api/):

npx convex env set VAR_NAME value

Or set them in the Convex dashboard under your deployment's Settings > Environment Variables.

Convex backend — control plane (all process.env references in apps/nest-api/):

The control plane runs its own Convex deployment. Set variables via the Convex dashboard for the nest-api deployment.

Nuxt frontend (apps/web/.env):

NUXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NUXT_PUBLIC_CONVEX_SITE_URL=https://your-deployment.convex.site
NUXT_PUBLIC_SITE_URL=http://localhost:3000

Infrastructure Billing (Control Plane)

Billing is managed by the control plane (apps/nest-api), not the tenant app. Each organization subscribes to an infrastructure tier that determines their VPS specifications and monthly price.

Pricing Tiers

Prerequisites

• A Stripe account
• Three products with monthly recurring prices (one per tier)

Required Variables

Set these in the nest-api Convex dashboard:

Setup Steps

1. Create a Stripe account at stripe.com and note your secret key from the API Keys page.
2. Create three products in Stripe — one for each tier (Starter, Growth, Enterprise) with monthly recurring pricing. Copy the Price IDs (start with price_).
3. Set the environment variables in the nest-api Convex dashboard:

   npx convex env set STRIPE_SECRET_KEY sk_live_...
   npx convex env set STRIPE_WEBHOOK_SECRET whsec_...
   npx convex env set STRIPE_PRICE_STARTER price_...
   npx convex env set STRIPE_PRICE_GROWTH price_...
   npx convex env set STRIPE_PRICE_ENTERPRISE price_...
   

4. Configure a Stripe webhook pointing to the nest-api Convex site URL. Subscribe to events: invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted.

Infrastructure (Hetzner)

The control plane provisions VPS instances on Hetzner Cloud. These variables are set in the nest-api Convex dashboard.

Required Variables

Setup Steps

1. Create a Hetzner Cloud project at console.hetzner.cloud.
2. Generate an API token with read/write permissions from the project's Security > API Tokens page.
3. (Optional) Upload an SSH key in the project's Security > SSH Keys page. Copy the key ID.
4. Set the environment variables:

   npx convex env set HETZNER_API_TOKEN your-api-token
   npx convex env set HETZNER_SSH_KEY_IDS 12345,67890
   

Email Sending

Provider Selection

Owlat supports three email providers: a custom MTA for direct SMTP delivery (default), AWS SES, and Resend. Set the EMAIL_PROVIDER variable in the Convex dashboard:

npx convex env set EMAIL_PROVIDER mta     # default
npx convex env set EMAIL_PROVIDER resend
npx convex env set EMAIL_PROVIDER mta

AWS SES

Setup Steps

1. Create an IAM user in AWS with programmatic access and the AmazonSESFullAccess policy (or a scoped policy allowing ses:SendEmail and ses:SendRawEmail).
2. Verify your sending domain in the SES console. SES requires domain verification before you can send emails.
3. Request production access if your SES account is in sandbox mode. Sandbox mode limits sending to verified addresses only.
4. Set the environment variables:

   npx convex env set EMAIL_PROVIDER ses
   npx convex env set AWS_SES_REGION eu-west-1
   npx convex env set AWS_SES_ACCESS_KEY_ID AKIA...
   npx convex env set AWS_SES_SECRET_ACCESS_KEY ...
   

Resend

Setup Steps

1. Create a Resend account at resend.com and add your sending domain.
2. Generate an API key from the Resend dashboard.
3. (Optional) Set up webhooks for delivery tracking:
   • In Resend, create a webhook pointing to your Convex site URL's webhook endpoint
   • Copy the webhook signing secret
4. Set the environment variables:

   npx convex env set EMAIL_PROVIDER resend
   npx convex env set RESEND_API_KEY re_...
   npx convex env set RESEND_WEBHOOK_SECRET whsec_...
   

Custom MTA

When using the custom MTA (EMAIL_PROVIDER=mta), the Convex backend connects to the MTA service over HTTP. See the MTA System docs for full architecture details.

Setup Steps

1. Deploy the MTA service from apps/mta/ (see the MTA System docs for configuration).
2. Set the environment variables in the Convex dashboard:

   npx convex env set EMAIL_PROVIDER mta
   npx convex env set MTA_API_URL http://mta.internal:3100
   npx convex env set MTA_API_KEY your-shared-api-key
   npx convex env set MTA_WEBHOOK_SECRET your-webhook-secret
   

Common Email Configuration

These variables apply regardless of which provider you use:

Email Security

Optional environment variables for email content and attachment scanning. See the Email Security docs for details on the scanning pipeline.

Variables

Set in the Convex dashboard:

Set in the MTA environment:

Setup Steps

1. (Optional) Enable URL reputation checking — get a Google Safe Browsing API key from the Google Cloud Console:

   npx convex env set GOOGLE_SAFE_BROWSING_API_KEY AIza...
   

2. (Optional) Enable ClamAV malware scanning — deploy ClamAV alongside the MTA (see MTA System > ClamAV Sidecar) and set the internal URL:

   npx convex env set MTA_INTERNAL_URL http://mta.internal:3100
   

Analytics (PostHog)

Owlat integrates with PostHog for product analytics and error tracking. The integration is optional — everything works without it.

Variables

Convex dashboard:

Nuxt frontend (apps/web/.env):

Setup Steps

1. Create a PostHog project at posthog.com and copy the project API key.
2. Add the organization group type in PostHog: go to Settings → Groups → add a group type called organization. This enables organization-level analytics.
3. Set the environment variables:

   # Convex (server-side events)
   npx convex env set POSTHOG_API_KEY phc_...
   npx convex env set POSTHOG_HOST https://eu.i.posthog.com
   
   # apps/web/.env (client-side events)
   NUXT_PUBLIC_POSTHOG_API_KEY=phc_...
   NUXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
   

Tracked Events

Client-side (automatic):

• $pageview — SPA page navigations
• $pageleave — page leave events
• $exception — Vue errors and unhandled promise rejections
• User identification and organization group association

Server-side (fire-and-forget from mutations):

• campaign_created, campaign_sent
• contact_created
• automation_created, automation_activated, automation_paused
• topic_created

All server events include organizationId as a property and PostHog group.

Translations (AI)

Owlat supports AI-powered email template translations. OpenRouter is the primary provider; OpenAI is used as a fallback if OpenRouter is not configured.

Set in the Convex dashboard:

npx convex env set OPENROUTER_API_KEY sk-or-...
# or, as fallback:
npx convex env set OPENAI_API_KEY sk-...

Authentication

Set BETTER_AUTH_SECRET in the Convex dashboard. Use a long, random string:

npx convex env set BETTER_AUTH_SECRET $(openssl rand -base64 32)

Nuxt Frontend

These go in apps/web/.env:

Admin Dashboard

The nest dashboard (apps/nest/) uses its own .env file. It connects to a separate Convex deployment (apps/nest-api), not the same backend as the tenant web app.

Set in apps/nest/.env:

Complete Reference

Tenant App (apps/api)

Control Plane (apps/nest-api)

Frontend (apps/web and apps/nest)

MTA (apps/mta)