Configuration

EOS Hub is configured through environment variables defined in a .env file at the project root. This page documents every available variable.

Environment Variables Reference

Database

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string

DATABASE_URL="postgresql://user:password@localhost:5432/eos_hub"

The connection string format is:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public

TIP

For connection pooling in production (e.g., with PgBouncer), append &pgbouncer=true to the connection string and set a separate DIRECT_URL for migrations.

Authentication

Variable	Required	Description
NEXTAUTH_SECRET	Yes	Random secret for signing JWTs and encrypting sessions
NEXTAUTH_URL	Yes	The canonical URL of your application
GOOGLE_CLIENT_ID	No	Google OAuth 2.0 client ID
GOOGLE_CLIENT_SECRET	No	Google OAuth 2.0 client secret

NEXTAUTH_SECRET="a-random-32-character-secret"
NEXTAUTH_URL="http://localhost:3000"

# Google OAuth (optional)
GOOGLE_CLIENT_ID="123456789.apps.googleusercontent.com"
GOOGLE_CLIENT_SECRET="GOCSPX-xxxxxxxxxxxx"

INFO

If Google OAuth credentials are not provided, only email/password authentication is available. Users must be created manually -- by an organization Owner or Admin in Organization settings > Members, or by the platform operator when creating an organization.

Setting Up Google OAuth

1. Go to the Google Cloud Console.
2. Create a new project or select an existing one.
3. Navigate to APIs & Services > Credentials.
4. Click Create Credentials > OAuth 2.0 Client IDs.
5. Set the application type to Web application.
6. Add http://localhost:3000 to Authorized JavaScript origins.
7. Add http://localhost:3000/api/auth/callback/google to Authorized redirect URIs.
8. Copy the Client ID and Client Secret into your .env file.

Branding and Terminology

Variable	Required	Description
PRODUCT_NAME	No	The product name (default: EOS Hub). It is shown in the app and is also the brand wordmark next to the mark, the name in the web app manifest (home screen), the MCP server's title and instructions, and the OAuth resource name that AI connectors show. See Brand.
DEFAULT_TERMINOLOGY	No	Terms for organizations that didn't choose their own: eos (Rocks, L10 meetings, V/TO…, default) or neutral (Goals, Weekly meetings, Vision & Strategy…). See Terminology.

Encryption

Variable	Required	Description
DATA_ENCRYPTION_KEY	Yes	Base64 of 32 random bytes. Encrypts stored secrets such as AI provider API keys (AES-256-GCM).

Generate a key with:

openssl rand -base64 32

DATA_ENCRYPTION_KEY="base64-of-32-random-bytes"

DANGER

Keep DATA_ENCRYPTION_KEY stable and backed up together with your other secrets. If it is lost or changed, stored API keys can no longer be decrypted and must be re-entered in Platform > AI.

WARNING

In production the server refuses to start if DATA_ENCRYPTION_KEY is missing or is not a valid base64-encoded 32-byte key.

Application

Variable	Required	Default	Description
PORT	No	3000	Port for the development server
NODE_ENV	No	development	Environment mode (development, production, test)

Monitoring

Uptime checks, logs and error reports, e.g. with Better Stack (any Sentry-compatible error tracker works). Each part is off while its variable is empty.

Variable	Required	Description
APP_ENV	No	Environment name in error reports and logs (e.g. prod, dev; default production)
SENTRY_DSN	No	Error reporting DSN (Better Stack: Errors → Application → Data ingestion: https://<token>@<ingesting host>/<application id>). Errors from the server and the browser are reported -- no tracing, no session replay, users by id only. Read at runtime, not baked into the build.
HEARTBEAT_URL	No	Heartbeat URL of an uptime monitor. The background job that ends forgotten meetings calls it every 5 minutes (…/fail when the run failed), so a stopped job raises an alert.
BETTERSTACK_LOGS_HOST, BETTERSTACK_LOGS_TOKEN	No	Log source (ingesting host and source token) for the logs service in docker-compose.yml: with COMPOSE_PROFILES=logs it ships the logs of the stack's app and postgres containers (Vector, docker/vector.yaml).

Health check: GET /api/health answers 200 {"status":"ok","version":"…"} while the app and its database work and 503 otherwise -- point an uptime monitor at it. In production the server logs one JSON line per entry (level, msg and ids, never content).

Database Configuration

Prisma Schema

The database schema is defined in prisma/schema.prisma. Key models include:

• User -- Authentication and profile data (incl. personal time zone)
• Organization -- Companies hosted on the installation (name, time zone, default language, status)
• OrgMember -- Organization membership with the organization role (Owner, Admin, Member, Implementer)
• Team -- Teams within an organization
• TeamMember -- Team membership with the team role
• Meeting -- L10 Meeting instances
• Measurable -- Scorecard entries
• Rock -- Quarterly priorities
• Issue -- IDS items
• Todo -- Action items
• VTO -- Vision/Traction Organizer

Database Migrations

The database schema is managed with Prisma migrations in prisma/migrations. Schema changes ship only as migrations -- prisma db push is no longer used.

Create a new migration after modifying the schema (development only):

npx prisma migrate dev --name descriptive_name

Apply migrations in production:

npx prisma migrate deploy

Docker

The Docker entrypoint runs prisma migrate deploy on every start, so no manual step is needed. A database created by the old db push flow (it has tables but no migration history) is detected and baselined automatically before the migrations are applied. If a migration fails, the container stops instead of starting against a half-migrated database.

WARNING

Back up the database before upgrading to a new version -- migrations can include data migrations.

Auth Providers

EOS Hub uses NextAuth with two providers:

Credentials Provider

The default provider allows email/password login. Passwords are hashed with bcrypt before storage. Users are created through the seed script, by organization Owners and Admins in Organization settings > Members, or by the platform operator when creating an organization.

Google OAuth Provider

When configured, a "Sign in with Google" button appears on the login page. On first sign-in, a user record is automatically created and linked to the Google account.

WARNING

Users who sign in via Google OAuth without being added first get the USER system role and belong to no organization -- they see a No organization yet page until an organization Owner or Admin adds them by email.

Internationalization (next-intl)

EOS Hub supports multiple languages through next-intl. The current locale is stored in a cookie and defaults to the browser's preferred language.

See the Internationalization page for details on adding languages and managing translation files.

Theming

Theme preferences (dark/light mode and color scheme) are stored per-user in the browser via next-themes and cookies. See the Theming page for details on color schemes and CSS variables.

Production Deployment

For production deployments, ensure:

1. NODE_ENV=production is set.
2. NEXTAUTH_URL points to your actual domain (e.g., https://app.example.com).
3. NEXTAUTH_SECRET is a strong, unique random string.
4. DATA_ENCRYPTION_KEY is set (see Encryption) and backed up.
5. DATABASE_URL uses a connection pooler if available.
6. Run npx prisma migrate deploy before starting the application (the Docker image does this automatically).
7. Build the application with npm run build before npm run start.
8. Optionally set up monitoring.

Next Steps

• Organizations & Teams -- Data model and team structure
• Roles & Permissions -- Access control system