Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

9.0 KB
Raw Blame
// Only the config loader (`apps/api/src/config/env.ts`) reads `process.env`.
// `undefined` means "not set", never "blank": a blank `KEY=` is absent. Anything
// derived from more than one variable is resolved by the loader and arrives finished.

/** Which pino transport ships the logs, and how the service name is built. */
export interface LoggingConfig {
  level: string;
  silent: boolean;
  /** LOG_EXPORTER, or `otlp` when only HYPERDX_API_KEY is set. */
  exporter: 'otlp' | 'stdout';
  hyperdxApiKey: string | undefined;
  /** The two halves of `getServiceName`: `<prefix>-<name>-<environment>`. */
  serviceNamePrefix: string | undefined;
  serviceNameEnvironment: string;
  /** Whether stdout/stderr are routed through pino at all (production, or an
   *  exporter explicitly asked for). Local dev output stays untouched. */
  interceptProcessOutput: boolean;
}

/** One OAuth client's three credentials. */
export interface OAuthClientConfig {
  clientId: string;
  clientSecret: string;
  redirectUri: string;
}

export interface AuthConfig {
  /**
   * AUTH_SECRET, else COOKIE_SECRET. Signs better-auth's session cookie;
   * changing it signs everyone out. Unset leaves only legacy sessions.
   */
  secret: string | undefined;
  /** DASHBOARD_URL plus API_CORS_ORIGINS: who may call `/api/auth`. */
  trustedOrigins: string[];
  /**
   * `undefined` means the variable is unset, which is what cloud runs and what
   * makes registration unconditionally open — distinct from an explicit
   * `ALLOW_REGISTRATION=false`.
   */
  allowRegistration: boolean | undefined;
  allowInvitation: boolean | undefined;
  github: OAuthClientConfig;
  google: OAuthClientConfig;
  /** The same Google client, redirected at the Search Console callback. */
  googleGsc: OAuthClientConfig;
  /**
   * DEV_LOGIN: a one-click sign-in for a local box, as `email/password`. The
   * loader refuses it under NODE_ENV=production, so it is never set there.
   */
  devLogin: DevLoginConfig | undefined;
}

export interface DevLoginConfig {
  email: string;
  password: string;
}

export interface CookieConfig {
  /** COOKIE_SECRET: keys the share-access HMAC. Empty means shares stay locked. */
  secret: string;
  /** COOKIE_TLDS: extra multi-part public suffixes, lowercased. */
  extraMultiPartTlds: string[];
  /** CUSTOM_COOKIE_DOMAIN: overrides the domain derived from the dashboard. */
  customDomain: string | undefined;
}

export interface OpenAiConfig {
  apiKey: string | undefined;
  baseUrl: string | undefined;
  project: string | undefined;
  organization: string | undefined;
}

export interface AnthropicConfig {
  apiKey: string | undefined;
  baseUrl: string | undefined;
  authToken: string | undefined;
  version: string | undefined;
}

export interface AiConfig {
  openai: OpenAiConfig;
  anthropic: AnthropicConfig;
}

/**
 * OP_CLIENT_ID / OP_CLIENT_SECRET / OP_API_URL: the OpenPanel project this
 * deployment reports its own AI calls to. Unset means no self-tracking.
 */
export interface SelfTrackingConfig {
  clientId: string | undefined;
  clientSecret: string | undefined;
  apiUrl: string | undefined;
}

export interface SlackConfig {
  clientId: string | undefined;
  clientSecret: string | undefined;
  oauthRedirectUrl: string | undefined;
  stateSecret: string | undefined;
}

export interface PolarConfig {
  saveDiscountId: string | undefined;
  webhookSecret: string | undefined;
}

export const KAFKA_SASL_MECHANISMS = [
  'plain',
  'scram-sha-256',
  'scram-sha-512',
] as const;
export type KafkaSaslMechanism = (typeof KAFKA_SASL_MECHANISMS)[number];

/**
 * TLS/SASL for an external broker; unauthenticated plaintext when nothing is
 * set. The CA file is read where the client is built, so an unreadable path
 * fails there with its own message.
 */
export interface KafkaSecurityConfig {
  ssl: {
    enabled: boolean;
    caPath: string | undefined;
    rejectUnauthorized: boolean | undefined;
  };
  sasl:
    | { mechanism: KafkaSaslMechanism; username: string; password: string }
    | undefined;
}

/**
 * The Kafka transport's knobs. Every one is resolved: kafkajs is handed these
 * values verbatim, so a `??` at the call site would be a second default.
 */
export interface KafkaConfig {
  clientId: string;
  brokers: string[];
  eventsTopic: string;
  eventsDlqTopic: string;
  consumerGroup: string;
  partitionsConcurrent: number;
  minMessages: number;
  maxWaitMs: number;
  maxMessagesPerPartition: number;
  sessionTimeoutMs: number;
  heartbeatIntervalMs: number;
  /** How long the group waits for every member to rejoin during a rebalance. */
  rebalanceTimeoutMs: number;
  requestTimeoutMs: number;
  connectionTimeoutMs: number;
  producerRetries: number;
  producerInitialRetryMs: number;
  producerMaxRetryMs: number;
  /** kafkajs `maxInFlightRequests`. 1: one produce round-trip at a time. */
  producerMaxInFlight: number;
  /** Messages accumulated into one `send()`. Below 2 batching is off. */
  producerBatchSize: number;
  /** A partial batch's maximum wait, in ms, before it is sent anyway. */
  producerBatchLingerMs: number;
  /**
   * The broker's `max.message.bytes`. `/track` refuses a larger body with a
   * 413 rather than letting kafkajs answer with a raw protocol error at 500.
   * Raise this alongside the broker's own setting.
   */
  maxMessageBytes: number;
  handlerMaxAttempts: number;
  handlerRetryInitialMs: number;
  handlerRetryMaxMs: number;
  security: KafkaSecurityConfig;
}

/** Per-buffer sizing. `undefined` keeps the buffer's own documented default. */
export interface BufferSizing {
  batchSize: number | undefined;
  chunkSize?: number | undefined;
  ttlSeconds?: number | undefined;
  fetchChunkSize?: number | undefined;
}

export interface BuffersConfig {
  /** BUFFER_ASYNC_INSERTS: switches every buffer's inserts to async mode. */
  asyncInserts: boolean;
  chInsertConcurrency: number | undefined;
  bot: BufferSizing;
  event: BufferSizing & {
    microBatchMs: number | undefined;
    microBatchSize: number | undefined;
  };
  group: BufferSizing;
  aiEvent: BufferSizing;
  profile: BufferSizing;
  profileBackfill: BufferSizing;
  replay: BufferSizing;
  session: BufferSizing & { squash: boolean };
}

export interface SessionConfig {
  /** SESSION_TIMEOUT_MS: idle window before a session ends. */
  timeoutMs: number | undefined;
  reaperEnabled: boolean;
  reaperBatchSize: number | undefined;
  reaperWallclockDeadmanMs: number | undefined;
  vacuumEnabled: boolean;
  vacuumBatchSize: number | undefined;
  vacuumStaleThresholdMs: number | undefined;
  /** EXPERIMENTAL_PROFILE_BACKFILL, narrowed to a project list when given. */
  profileBackfillEnabled: boolean;
  profileBackfillProjectIds: string[];
}

/**
 * Sizing knobs on read and write paths. Each is a positive integer or
 * `undefined`; a malformed value keeps the default instead of failing boot.
 */
export interface QueryConfig {
  eventPropertyValueAutocompleteLimit: number | undefined;
  cohortMaterializeLimit: number | undefined;
  cohortQueryMemoryLimitBytes: number | undefined;
  cohortQuerySpillBytes: number | undefined;
  eventListMaxLookbackDays: number | undefined;
  sessionListMaxLookbackDays: number | undefined;
  importBatchSize: number | undefined;
  insightsRetentionDays: number | undefined;
  windDownMaxPerRun: number | undefined;
}

export interface ObjectStoreExportConfig {
  lagSeconds: number | undefined;
  batchSize: number | undefined;
  maxBatchesPerRun: number | undefined;
  concurrency: number | undefined;
  /** GCS_API_ENDPOINT: a non-default endpoint (an emulator, or a test double). */
  gcsApiEndpoint: string | undefined;
}

/** Comma-separated header orders; `undefined` keeps the shipped order. */
export interface IpHeaderConfig {
  attributionOrder: string[] | undefined;
  trustedOrder: string[] | undefined;
}

/** Everything core reads from the environment, parsed and derived once. */
export interface CoreConfig {
  isProduction: boolean;
  isDevelopment: boolean;
  selfHosted: boolean;
  /** DASHBOARD_URL, else the dashboard's public URL. `''` when neither is set. */
  dashboardUrl: string;
  /** Set on the demo deployment only: every session resolves to this user. */
  demoUserId: string | undefined;
  /** CLICKHOUSE_CLUSTER. Must agree with what `migrate:deploy` created. */
  clickhouseClustered: boolean;
  /**
   * ADMIN_USERNAME / ADMIN_PASSWORD: HTTP Basic credentials for operator-only
   * surfaces (bull-board today). Undefined leaves those surfaces on their own
   * guard alone.
   */
  adminAuth: { username: string; password: string } | undefined;
  /** The single symmetric key for at-rest encryption; 32 bytes as 64 hex. */
  encryptionKey: string | undefined;
  /** DISABLE_PING: a self-hosted instance opts out of the usage ping. */
  pingDisabled: boolean;
  logging: LoggingConfig;
  auth: AuthConfig;
  cookies: CookieConfig;
  ai: AiConfig;
  selfTracking: SelfTrackingConfig;
  slack: SlackConfig;
  polar: PolarConfig;
  kafka: KafkaConfig;
  buffers: BuffersConfig;
  session: SessionConfig;
  query: QueryConfig;
  objectStoreExport: ObjectStoreExportConfig;
  ipHeaders: IpHeaderConfig;
}