Skip to Content
DocsApp SdkConfigurationEnvironment Variables

Environment Variables

Das ProcessCube® App-SDK verwendet Umgebungsvariablen zur Konfiguration der Verbindung zu Engine, Authority und anderen Services.

Verfügbare Variables

Engine Configuration

PROCESSCUBE_ENGINE_URL

  • Standard: http://localhost:10560
  • Erforderlich: Nein
  • Beschreibung: URL der ProcessCube® Engine
.env.local
PROCESSCUBE_ENGINE_URL=http://localhost:10560

Wenn die Variable nicht gesetzt ist, wird der Standardwert http://localhost:10560 verwendet.

Beispiele:

# Lokal
PROCESSCUBE_ENGINE_URL=http://localhost:10560
 
# Docker
PROCESSCUBE_ENGINE_URL=http://engine:80
 
# Production
PROCESSCUBE_ENGINE_URL=https://engine.yourcompany.com

Authority Configuration

PROCESSCUBE_AUTHORITY_URL

  • Standard: -
  • Erforderlich: Bei Verwendung von Authentifizierung
  • Beschreibung: URL der ProcessCube® Authority (OpenID Connect Provider)
.env.local
PROCESSCUBE_AUTHORITY_URL=http://localhost:11235

Verwendung:

  • Silent Refresh des User Access Token
  • Login von External Task Workers
  • OAuth 2.0 Client Credentials Flow

NextAuth.js Configuration

Bei Verwendung von NextAuth.js für die Authentifizierung:

NEXTAUTH_URL

  • Erforderlich: Ja (bei NextAuth.js)
  • Beschreibung: URL Ihrer Next.js Anwendung
.env.local
NEXTAUTH_URL=http://localhost:3000

NEXTAUTH_CLIENT_ID

  • Erforderlich: Ja (bei NextAuth.js)
  • Beschreibung: OAuth 2.0 Client ID (aus Authority)
.env.local
NEXTAUTH_CLIENT_ID=my-processcube-app

NEXTAUTH_SECRET

  • Erforderlich: Ja (bei NextAuth.js)
  • Beschreibung: Secret für Session-Verschlüsselung
.env.local
# Generieren mit: openssl rand -base64 32
NEXTAUTH_SECRET=3ef62eb3-fe49-4c2c-ba6f-73e4d234321b

Verwenden Sie für Production einen sicheren, zufälligen String. Generieren Sie ihn mit openssl rand -base64 32.

External Task Worker Configuration

Für External Task Workers (Server-Side):

PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID

  • Erforderlich: Bei External Tasks mit Authentifizierung
  • Beschreibung: Client ID für den External Task Worker
.env.local
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID=external-task-worker

PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET

  • Erforderlich: Bei External Tasks mit Authentifizierung
  • Beschreibung: Client Secret für den External Task Worker
.env.local
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET=5ef83eb1-fe28-4c2c-ba6f-46e4d234321b

Diese Credentials werden vom External Task Worker verwendet, um sich automatisch bei der Authority zu authentifizieren.

Vollständige Konfiguration

Beispiel: Development

.env.local
# ProcessCube Services
PROCESSCUBE_ENGINE_URL=http://localhost:10560
PROCESSCUBE_AUTHORITY_URL=http://localhost:11235
 
# NextAuth.js
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_CLIENT_ID=my-dev-app
NEXTAUTH_SECRET=dev-secret-change-in-production
 
# External Task Worker
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID=external-task-worker
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET=worker-secret-123

Beispiel: Production

.env.production
# ProcessCube Services
PROCESSCUBE_ENGINE_URL=https://engine.yourcompany.com
PROCESSCUBE_AUTHORITY_URL=https://authority.yourcompany.com
 
# NextAuth.js
NEXTAUTH_URL=https://app.yourcompany.com
NEXTAUTH_CLIENT_ID=prod-app
NEXTAUTH_SECRET=${NEXTAUTH_SECRET} # Von Hosting-Service injiziert
 
# External Task Worker
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_ID=prod-worker
PROCESSCUBE_EXTERNAL_TASK_WORKER_CLIENT_SECRET=${WORKER_SECRET} # Von Hosting-Service injiziert

Umgebungsspezifische Dateien

Next.js unterstützt verschiedene .env Dateien:

DateiVerwendungIn Git?
.envAlle Umgebungen✓ Ja (nur Default-Werte)
.env.localLokale Überschreibungen✗ Nein
.env.developmentDevelopment-Modus✓ Ja
.env.productionProduction-Build✓ Ja
.env.production.localProduction-Überschreibungen✗ Nein

Fügen Sie .env*.local zu .gitignore hinzu, um Secrets nicht ins Repository zu committen!

Client-Side Variables

Für Zugriff von Client-Side Code verwenden Sie das NEXT_PUBLIC_ Prefix:

.env.local
# Nur Server-Side verfügbar
PROCESSCUBE_ENGINE_URL=http://localhost:10560
 
# Auch Client-Side verfügbar
NEXT_PUBLIC_APP_NAME=My ProcessCube App
// Server Component - beide verfügbar
const engineUrl = process.env.PROCESSCUBE_ENGINE_URL;
const appName = process.env.NEXT_PUBLIC_APP_NAME;
 
// Client Component - nur NEXT_PUBLIC_ verfügbar
const appName = process.env.NEXT_PUBLIC_APP_NAME; // ✓ Funktioniert
const engineUrl = process.env.PROCESSCUBE_ENGINE_URL; // ✗ undefined

Setzen Sie NIEMALS sensible Informationen (API Keys, Secrets) in NEXT_PUBLIC_ Variables!

Verwendung im Code

Server-Side

app/api/tasks/route.ts
import { getWaitingUserTasks } from '@5minds/processcube_app_sdk/server';
 
export async function GET() {
  // Verwendet automatisch PROCESSCUBE_ENGINE_URL
  const tasks = await getWaitingUserTasks();
 
  return Response.json(tasks);
}

Mit Custom Configuration

lib/processcube.ts
import { getWaitingUserTasks } from '@5minds/processcube_app_sdk/server';
 
export async function getTasksFromCustomEngine() {
  const tasks = await getWaitingUserTasks({
    engineUrl: 'https://custom-engine.com',
    accessToken: 'custom-token',
  });
 
  return tasks;
}

Validierung

Empfohlene Validierung der Environment Variables beim Start:

lib/env.ts
const requiredEnvVars = [
  'PROCESSCUBE_ENGINE_URL',
  'PROCESSCUBE_AUTHORITY_URL',
  'NEXTAUTH_SECRET',
] as const;
 
export function validateEnv() {
  const missing = requiredEnvVars.filter(
    (varName) => !process.env[varName]
  );
 
  if (missing.length > 0) {
    throw new Error(
      `Fehlende Environment Variables: ${missing.join(', ')}`
    );
  }
}
 
// In app/layout.tsx oder instrumentation.ts
validateEnv();

Troubleshooting

Variables werden nicht geladen

Problem: process.env.VARIABLE_NAME ist undefined

Lösungen:

  1. Datei muss .env.local heißen (nicht .env.txt)
  2. Development Server neu starten: npm run dev
  3. Keine Leerzeichen um =: VAR=value (nicht VAR = value)
  4. Keine Anführungszeichen bei Werten nötig

Client-Side undefined

Problem: Variable ist auf Client-Side undefined

Lösung: Verwenden Sie NEXT_PUBLIC_ Prefix

# Falsch - nur Server-Side
ENGINE_URL=http://localhost:10560
 
# Richtig - auch Client-Side
NEXT_PUBLIC_ENGINE_URL=http://localhost:10560

Production Variables

Problem: Variablen funktionieren nicht in Production

Lösungen:

  1. Setzen Sie Environment Variables in Ihrem Hosting-Service (Vercel, AWS, etc.)
  2. .env.production wird nur beim Build verwendet, nicht zur Runtime
  3. Bei Serverless: Variables müssen über das Hosting-Dashboard gesetzt werden

Nächste Schritte

ConfigurationPlugin System