​

Environment Setup

​

Quick Start

1. Copy the example environment files from both apps:

# Copy webapp environment file
cp apps/webapp/.env.example apps/webapp/.env.local

# Copy temporal workers environment file
cp apps/temporal-workers/.env.example apps/temporal-workers/.env.local

2. Fill in the required variables in both .env.local files

​

Application Architecture

• 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

​

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"

• 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"

• 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"

• 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"

• 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"

• 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"

• 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

• 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

​

Integration APIs

​

Shopify Integration

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

• 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"

• 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"

• 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"

• 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"

• Enables private file storage for logos, CSV imports, and GoBD-compliant documents
• Service-role key allows server-side uploads and signed URL generation
• Uses the same Supabase project as the database

​

Error Tracking

SENTRY_AUTH_TOKEN="your-sentry-token"

• 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=""

• 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"

• 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"

• 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

​

Environment Setup by Environment

​

Local Development

# Database - use local PostgreSQL or Supabase
DATABASE_URL="postgresql://postgres:password@localhost:5432/cona_dev"

# Temporal - use local Temporal server
TEMPORAL_ADDRESS="localhost:7233"
TEMPORAL_NAMESPACE="default"
TEMPORAL_API_KEY=""

# Integrations - use sandbox/test credentials
PAYPAL_API_BASE_URL="https://api-m.sandbox.paypal.com"
PAYPAL_AUTH_URL="https://www.sandbox.paypal.com/signin/authorize"

# URLs - use local URLs
APP_BASE_URL="http://localhost:3000"
NEXT_PUBLIC_APP_URL="http://localhost:3000"

​

Security Best Practices

1. Never commit .env files to version control
2. Use different credentials for each environment
3. Rotate secrets regularly (especially encryption keys and API keys)
4. Limit access to production credentials to essential personnel only
5. Use environment-specific namespaces for Temporal workflows
6. Validate all environment variables on application startup
7. Use secure methods to share credentials with team members (password managers, secure vaults)

​

Environment Variable Validation