Environment Setup

This guide details all the environment variables needed to run CONA and how to configure them for both the webapp and temporal workers.

Setup procedure

Follow the canonical local development setup in the root README to copy the workspace templates and prepare the database. This page describes the environment variables; the README owns the setup commands. The database workspace uses packages/database/.env.example, copied to packages/database/.env. Set ADMIN_DIRECT_URL for Prisma schema commands and ADMIN_DATABASE_URL for seeding to your local database. See the database README for database-specific operations.

Application Architecture

CONA consists of two main applications that require environment configuration:

Webapp (apps/webapp): Next.js application handling web UI, API routes, and integrations
Temporal Workers (apps/temporal-workers): Background workers processing workflows and long-running tasks

Both applications share some common environment variables but have specific requirements.

Webapp Environment Variables

Database Configuration

# PostgreSQL connection strings
DATABASE_URL="postgresql://postgres.user:password@pooler.supabase.com:6543/postgres?pgbouncer=true&sslmode=require"
DIRECT_URL="postgresql://postgres.user:password@pooler.supabase.com:5432/postgres?sslmode=require"

What these do:

DATABASE_URL: Main database connection using pgBouncer for connection pooling - optimized for high-throughput applications
DIRECT_URL: Direct database connection for migrations, schema changes, and operations requiring transaction isolation

Supabase Configuration

NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-anon-key"

What these do:

NEXT_PUBLIC_SUPABASE_URL: Your Supabase project URL for database and auth services
NEXT_PUBLIC_SUPABASE_ANON_KEY: Public anonymous key for client-side Supabase operations (safe to expose)

Security & Encryption

ENCRYPTION_KEY="your-encryption-key"

What this does:

Encrypts sensitive data like API keys, tokens, and PII before storing in database
Generate using: openssl rand -base64 32
Must be the same across webapp and temporal-workers

Auth0 Configuration

AUTH0_DOMAIN="auth.your-app-url.com"
AUTH0_TENANT_DOMAIN="your-tenant.eu.auth0.com"
AUTH0_CLIENT_ID="your-client-id"
AUTH0_CLIENT_SECRET="your-client-secret"
AUTH0_SECRET="your-auth0-secret"
AUTH0_API_BASE_URL="https://your-tenant.eu.auth0.com/api/v2"
AUTH0_M2M_CLIENT_ID="your-management-api-client-id"
AUTH0_M2M_CLIENT_SECRET="your-management-api-client-secret"

What these do:

AUTH0_DOMAIN: User-facing custom domain for login/signup flows (the branded URL users see, e.g. auth.cona.app)
AUTH0_TENANT_DOMAIN: Canonical tenant domain used only for the Management API v2 (e.g. your-tenant.eu.auth0.com). The Management API is not served on custom domains, so this must be the raw tenant host. If unset, the Management client falls back to parsing the hostname out of AUTH0_API_BASE_URL.
AUTH0_CLIENT_ID/SECRET: Application credentials for Auth0 SDK
AUTH0_SECRET: Random string for encrypting session cookies
AUTH0_API_BASE_URL: Management API endpoint for user management operations
AUTH0_M2M_CLIENT_ID/SECRET: Machine-to-machine credentials for server-side Auth0 operations

Application URLs

APP_BASE_URL="https://your-app-url.com"
NEXT_PUBLIC_APP_URL="https://your-app-url.com"

What these do:

APP_BASE_URL: Server-side base URL for redirects and API calls
NEXT_PUBLIC_APP_URL: Client-side accessible URL for frontend operations

Development & Debugging

DEV_PASSWORD="your-dev-password"

What this does:

Password-protects development routes and debugging tools in non-production environments

Vercel Environment Detection (Staging/Preview)

# Automatically provided by Vercel for Next.js projects (no setup required)
NEXT_PUBLIC_VERCEL_ENV="preview"  # or "production", "development"
NEXT_PUBLIC_VERCEL_TARGET_ENV="staging"  # custom environment name if configured

What these do:

NEXT_PUBLIC_VERCEL_ENV: The deployment environment (development, preview, or production)
NEXT_PUBLIC_VERCEL_TARGET_ENV: The custom environment name (e.g., staging) when using Vercel custom environments

Both variables are automatically provided by Vercel for Next.js projects as Framework Environment Variables. No manual setup required. Why this matters: Client-side components (like debug mode toggle) need the NEXT_PUBLIC_ prefix to access environment variables in the browser. The getEnvironmentInfo() utility uses these variables to detect the current environment on both server and client.

Integration APIs

Shopify Integration

SHOPIFY_CLIENT_ID="your-shopify-client-id"
SHOPIFY_CLIENT_SECRET="your-shopify-client-secret"

What these do:

OAuth credentials for Shopify app integration
Allows connecting to Shopify stores and accessing store data
Obtained from Shopify Partners dashboard

PayPal Integration

PAYPAL_CLIENT_ID="your-paypal-client-id"
PAYPAL_CLIENT_SECRET="your-paypal-client-secret"
PAYPAL_API_BASE_URL="https://api-m.sandbox.paypal.com"
PAYPAL_AUTH_URL="https://www.sandbox.paypal.com/signin/authorize"

What these do:

OAuth credentials for PayPal integration
PAYPAL_API_BASE_URL: API endpoint (sandbox for testing, live for production)
PAYPAL_AUTH_URL: OAuth authorization endpoint
Enables PayPal transaction import and reconciliation

Amazon SP-API Integration

AMAZON_SP_API_CLIENT_ID="your-amazon-client-id"
AMAZON_SP_API_CLIENT_SECRET="your-amazon-client-secret"
AMAZON_API_BASE_URL="https://api.amazon.com"
AMAZON_SP_API_AUTH_URL="https://sellercentral.amazon.com/apps/authorize/consent"

What these do:

OAuth credentials for Amazon Selling Partner API
Enables Amazon marketplace data import and order processing
Obtained from Amazon Developer Console

Analytics & Monitoring

NEXT_PUBLIC_POSTHOG_KEY="your-posthog-key"
NEXT_PUBLIC_POSTHOG_HOST="https://eu.i.posthog.com"

What these do:

PostHog analytics for user behavior tracking and feature analytics
NEXT_PUBLIC_POSTHOG_HOST: PostHog instance URL (EU for GDPR compliance)

File Storage (Supabase)

SUPABASE_SECRET_KEY="your-supabase-secret-key"

What this does:

Enables private file storage for logos, CSV imports, and GoBD-compliant documents
Supabase secret key (prefer sb_secret_...) allows server-side uploads and signed URL generation
Uses the same Supabase project as the database

Error Tracking

SENTRY_AUTH_TOKEN="your-sentry-token"

What this does:

Sentry integration for error tracking and performance monitoring
Automatically captures and reports application errors

Temporal Workers Environment Variables

Temporal Configuration

TEMPORAL_ADDRESS="localhost:7233"
TEMPORAL_NAMESPACE="default"
TEMPORAL_API_KEY=""

What these do:

TEMPORAL_ADDRESS: Temporal server connection string (localhost for dev, cloud URL for production)
TEMPORAL_NAMESPACE: Isolated workflow environment (use different namespaces for dev/staging/prod)
TEMPORAL_API_KEY: Required for Temporal Cloud (leave empty for local development)

Security & Encryption

ENCRYPTION_KEY="your-encryption-key"

What this does:

Must match the webapp encryption key exactly
Used to decrypt sensitive data stored by the webapp
Critical for workflow activities that handle encrypted data

File Storage (Supabase)

SUPABASE_SECRET_KEY="your-supabase-secret-key"

What this does:

Must match the webapp Supabase secret key exactly
Required for Temporal activities that upload DATEV ZIPs, Sammelbeleg PDFs, and delete CSV batch files
Without this, file cleanup and document storage workflows will fail