> ## Documentation Index
> Fetch the complete documentation index at: https://cona.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Setup

> Configure your development environment for CONA

# 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.

## Quick Start

1. Copy the example environment files from both apps:

```bash theme={null}
# 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

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

```env theme={null}
# 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

```env theme={null}
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

```env theme={null}
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

```env theme={null}
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

```env theme={null}
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

```env theme={null}
DEV_PASSWORD="your-dev-password"
```

**What this does:**

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

### Vercel Environment Detection (Staging/Preview)

```env theme={null}
# 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](https://vercel.com/docs/environment-variables/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

```env theme={null}
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

```env theme={null}
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

```env theme={null}
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

```env theme={null}
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)

```env theme={null}
SUPABASE_SECRET_KEY="your-supabase-secret-key"
```

**What this does:**

* 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

```env theme={null}
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

```env theme={null}
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

```env theme={null}
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)

```env theme={null}
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

## Environment Setup by Environment

### Local Development

```bash theme={null}
# 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

Both applications validate required environment variables on startup. Missing or invalid variables will cause startup failures with helpful error messages.