Adjust env example and docs by elie222 · Pull Request #1024 · elie222/inbox-zero

elie222 · 2025-11-27T13:59:58Z

Set default premium bypass to true in Docker Compose and restructure environment variable docs and examples for Docker-focused self-hosting

Update .env.example to separate Docker auto-configured variables from required settings, change docker-compose.yml to default NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS to true, and revise hosting docs to clarify Redis and Docker defaults and migration commands.

📍Where to Start

Start with the web service environment block in docker-compose.yml to verify the default NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS change, then review the top section of apps/web/.env.example for the new structure and comments.

Macroscope summarized a1d3a6f.

Summary by CodeRabbit

Documentation
- Updated self-hosting guides with streamlined deployment procedures and new troubleshooting section for common setup issues
- Reorganized environment configuration documentation for clarity on Redis and encryption requirements
Chores
- Enhanced environment configuration structure with improved organization of encryption, API keys, and Redis settings

_{✏️ Tip: You can customize this high-level summary in your review settings.}

vercel · 2025-11-27T14:00:03Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
inbox-zero	Ready	Preview	Nov 27, 2025 2:05pm

coderabbitai · 2025-11-27T14:00:10Z

Walkthrough

Environment variables are reorganized in .env.example with new encryption and API key configuration sections. Docker compose default for the premium bypass flag changed to true. Documentation updated to reflect new environment structure, deployment procedures, and Prisma migration setup in containerized environments.

Changes

Cohort / File(s)	Summary
Environment Configuration `apps/web/.env.example`, `docker-compose.yml`	Environment variables reorganized into logical sections (Docker/required, Email encryption, Internal API keys, Redis). Removed `NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS=true` from example file. Added `EMAIL_ENCRYPT_SECRET`, `EMAIL_ENCRYPT_SALT`, `INTERNAL_API_KEY`, `API_KEY_SALT`. Changed docker-compose default for `NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS` to true.
Deployment & Hosting Documentation `docs/hosting/environment-variables.md`, `docs/hosting/self-hosting.md`	Updated Redis and bypass flag documentation. Clarified that `NEXT_PUBLIC_BASE_URL` must be set at runtime. Removed `NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS` from deployment commands. Added Troubleshooting section and notes about Prisma being pre-installed in container. Updated migration commands to use Prisma CLI directly.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Consistency check: Verify that environment variable names, defaults, and descriptions align across .env.example, docker-compose.yml, and documentation files
Docker behavior: Confirm the NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS default change and how it interacts with the removed .env.example entry
Documentation accuracy: Ensure all migration command references and runtime configuration guidance are correct

Possibly related PRs

Add AWS Copilot deployment guide and fix Docker Prisma migration setup #1009: Adds email encryption and internal API key configuration to environment files and aligns Docker/docs for in-container Prisma migrations, reflecting overlapping environment and deployment setup changes.
Self hosting with docker #760: Modifies apps/web/.env.example and self-hosting Docker documentation, sharing the same files and deployment configuration scope.
Update deploy instructions #997: Touches the NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS feature flag across Docker and docs configuration surfaces, making changes to the same flag's defaults and usage.

Poem

🐰 Config reorganized, tidy and bright,
Docker and docs now aligned just right,
Redis and secrets in sections so neat,
Prisma runs local, the setup's complete!
— Your friendly CodeRabbit 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Adjust env example and docs' is vague and generic, lacking specificity about what was adjusted and why.	Use a more descriptive title that captures the main change, such as 'Update Docker Compose defaults and environment configuration' or 'Enable premium checks bypass by default in Docker Compose'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch chore/docker-compose-defaults

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0844f16 and a1d3a6f.

📒 Files selected for processing (4)

apps/web/.env.example (2 hunks)
docker-compose.yml (1 hunks)
docs/hosting/environment-variables.md (3 hunks)
docs/hosting/self-hosting.md (4 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

!(pages/_document).{jsx,tsx}

📄 CodeRabbit inference engine (.cursor/rules/ultracite.mdc)

Don't use the next/head module in pages/_document.js on Next.js projects

Files:

docker-compose.yml
docs/hosting/self-hosting.md
docs/hosting/environment-variables.md
apps/web/.env.example

apps/web/**/{.env.example,env.ts,turbo.json}

📄 CodeRabbit inference engine (apps/web/CLAUDE.md)

Add environment variables to .env.example, env.ts, and turbo.json

Files:

apps/web/.env.example

🧠 Learnings (17)

📓 Common learnings

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/environment-variables.mdc:0-0
Timestamp: 2025-11-25T14:36:45.797Z
Learning: Applies to .env.example : Add new environment variables to `.env.example` with example values

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/environment-variables.mdc:0-0
Timestamp: 2025-11-25T14:36:43.454Z
Learning: Applies to .env.example : Add environment variables to `.env.example` with example values in the format `VARIABLE_NAME=value_example`

Learnt from: garnertb
Repo: elie222/inbox-zero PR: 580
File: apps/web/.env.example:4-7
Timestamp: 2025-07-19T15:06:43.730Z
Learning: In apps/web/.env.example, boolean environment variables follow an unquoted convention (e.g., LOG_ZOD_ERRORS=true, AUTH_TRUST_HOST=true). Logical grouping of related variables (like auth variables together) is preferred over strict alphabetical ordering for better developer experience.

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: apps/web/CLAUDE.md:0-0
Timestamp: 2025-11-25T14:36:18.404Z
Learning: Applies to apps/web/**/{.env.example,env.ts,turbo.json} : Add environment variables to `.env.example`, `env.ts`, and `turbo.json`

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/environment-variables.mdc:0-0
Timestamp: 2025-11-25T14:36:45.797Z
Learning: Applies to {.env.example,apps/web/env.ts} : Client-side environment variables must be prefixed with `NEXT_PUBLIC_`

📚 Learning: 2025-11-25T14:36:45.797Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/environment-variables.mdc:0-0
Timestamp: 2025-11-25T14:36:45.797Z
Learning: Applies to {.env.example,apps/web/env.ts} : Client-side environment variables must be prefixed with `NEXT_PUBLIC_`

Applied to files:

docker-compose.yml
docs/hosting/environment-variables.md
apps/web/.env.example

📚 Learning: 2025-11-25T14:36:45.797Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/environment-variables.mdc:0-0
Timestamp: 2025-11-25T14:36:45.797Z
Learning: Applies to apps/web/env.ts : Add client-side environment variables to `apps/web/env.ts` under the `client` object with `NEXT_PUBLIC_` prefix and Zod schema validation

Applied to files:

docker-compose.yml
docs/hosting/self-hosting.md
docs/hosting/environment-variables.md
apps/web/.env.example

📚 Learning: 2025-11-25T14:36:18.404Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: apps/web/CLAUDE.md:0-0
Timestamp: 2025-11-25T14:36:18.404Z
Learning: Applies to apps/web/**/*NEXT_PUBLIC_* : Prefix client-side environment variables with `NEXT_PUBLIC_`

Applied to files:

docker-compose.yml
docs/hosting/environment-variables.md
apps/web/.env.example

📚 Learning: 2025-11-25T14:36:43.454Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/environment-variables.mdc:0-0
Timestamp: 2025-11-25T14:36:43.454Z
Learning: Applies to apps/web/env.ts : For client-side environment variables in `apps/web/env.ts`, prefix them with `NEXT_PUBLIC_` and add them to both the `client` and `experimental__runtimeEnv` sections

Applied to files:

docker-compose.yml
docs/hosting/self-hosting.md
docs/hosting/environment-variables.md
apps/web/.env.example

📚 Learning: 2025-11-25T14:38:27.988Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/posthog-feature-flags.mdc:0-0
Timestamp: 2025-11-25T14:38:27.988Z
Learning: Applies to apps/web/hooks/useFeatureFlags.ts : For early access features, create boolean flag hooks using `useFeatureFlagEnabled` with the pattern `export function use[FeatureName]Enabled()`

Applied to files:

docs/hosting/environment-variables.md

📚 Learning: 2025-11-25T14:38:32.318Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/posthog-feature-flags.mdc:0-0
Timestamp: 2025-11-25T14:38:32.318Z
Learning: Applies to **/*.{ts,tsx} : For early access feature flags, create hooks using the naming convention `use[FeatureName]Enabled` that return a boolean from `useFeatureFlagEnabled("flag-key")`

Applied to files:

docs/hosting/environment-variables.md

📚 Learning: 2025-11-25T14:38:27.988Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/posthog-feature-flags.mdc:0-0
Timestamp: 2025-11-25T14:38:27.988Z
Learning: Feature flags are configured in the PostHog dashboard for both early access features and A/B testing

Applied to files:

docs/hosting/environment-variables.md

📚 Learning: 2025-11-25T14:38:27.988Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/posthog-feature-flags.mdc:0-0
Timestamp: 2025-11-25T14:38:27.988Z
Learning: Applies to apps/web/hooks/useFeatureFlags.ts : Use kebab-case for feature flag keys (e.g., `inbox-cleaner`, `pricing-options-2`)

Applied to files:

docs/hosting/environment-variables.md

📚 Learning: 2025-11-25T14:38:27.988Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/posthog-feature-flags.mdc:0-0
Timestamp: 2025-11-25T14:38:27.988Z
Learning: Applies to apps/web/hooks/useFeatureFlags.ts : Use `use[FeatureName]Enabled` naming convention for boolean feature flag hooks and `use[FeatureName]Variant` for A/B test variant hooks

Applied to files:

docs/hosting/environment-variables.md

📚 Learning: 2025-11-25T14:36:18.404Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: apps/web/CLAUDE.md:0-0
Timestamp: 2025-11-25T14:36:18.404Z
Learning: Applies to apps/web/**/{.env.example,env.ts,turbo.json} : Add environment variables to `.env.example`, `env.ts`, and `turbo.json`

Applied to files:

apps/web/.env.example

📚 Learning: 2025-11-25T14:36:45.797Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/environment-variables.mdc:0-0
Timestamp: 2025-11-25T14:36:45.797Z
Learning: Applies to .env.example : Add new environment variables to `.env.example` with example values

Applied to files:

apps/web/.env.example

📚 Learning: 2025-11-25T14:36:43.454Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/environment-variables.mdc:0-0
Timestamp: 2025-11-25T14:36:43.454Z
Learning: Applies to .env.example : Add environment variables to `.env.example` with example values in the format `VARIABLE_NAME=value_example`

Applied to files:

apps/web/.env.example

📚 Learning: 2025-07-19T15:06:43.730Z

Learnt from: garnertb
Repo: elie222/inbox-zero PR: 580
File: apps/web/.env.example:4-7
Timestamp: 2025-07-19T15:06:43.730Z
Learning: In apps/web/.env.example, boolean environment variables follow an unquoted convention (e.g., LOG_ZOD_ERRORS=true, AUTH_TRUST_HOST=true). Logical grouping of related variables (like auth variables together) is preferred over strict alphabetical ordering for better developer experience.

Applied to files:

apps/web/.env.example

📚 Learning: 2025-11-25T14:36:45.797Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/environment-variables.mdc:0-0
Timestamp: 2025-11-25T14:36:45.797Z
Learning: Applies to apps/web/env.ts : Add client-side environment variables to `apps/web/env.ts` under the `experimental__runtimeEnv` object to enable runtime access

Applied to files:

apps/web/.env.example

📚 Learning: 2025-11-25T14:36:45.797Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/environment-variables.mdc:0-0
Timestamp: 2025-11-25T14:36:45.797Z
Learning: Applies to apps/web/env.ts : Add server-only environment variables to `apps/web/env.ts` under the `server` object with Zod schema validation

Applied to files:

apps/web/.env.example

📚 Learning: 2025-11-25T14:39:04.892Z

Learnt from: CR
Repo: elie222/inbox-zero PR: 0
File: .cursor/rules/security-audit.mdc:0-0
Timestamp: 2025-11-25T14:39:04.892Z
Learning: No hardcoded secrets in code; all secrets must be stored in environment variables (e.g., CRON_SECRET)

Applied to files:

apps/web/.env.example

🪛 dotenv-linter (4.0.0)

apps/web/.env.example

[warning] 93-93: [SpaceCharacter] The line has spaces around equal sign

(SpaceCharacter)

[warning] 93-93: [ValueWithoutQuotes] This value needs to be surrounded in quotes

(ValueWithoutQuotes)

[warning] 94-94: [SpaceCharacter] The line has spaces around equal sign

(SpaceCharacter)

[warning] 94-94: [UnorderedKey] The API_KEY_SALT key should go before the INTERNAL_API_KEY key

(UnorderedKey)

[warning] 94-94: [ValueWithoutQuotes] This value needs to be surrounded in quotes

(ValueWithoutQuotes)

[warning] 100-100: [SpaceCharacter] The line has spaces around equal sign

(SpaceCharacter)

[warning] 100-100: [ValueWithoutQuotes] This value needs to be surrounded in quotes

(ValueWithoutQuotes)

[warning] 101-101: [SpaceCharacter] The line has spaces around equal sign

(SpaceCharacter)

[warning] 101-101: [UnorderedKey] The REDIS_URL key should go before the UPSTASH_REDIS_TOKEN key

(UnorderedKey)

[warning] 101-101: [ValueWithoutQuotes] This value needs to be surrounded in quotes

(ValueWithoutQuotes)

[warning] 102-102: [UnorderedKey] The QSTASH_TOKEN key should go before the REDIS_URL key

(UnorderedKey)

[warning] 103-103: [UnorderedKey] The QSTASH_CURRENT_SIGNING_KEY key should go before the QSTASH_TOKEN key

(UnorderedKey)

[warning] 104-104: [UnorderedKey] The QSTASH_NEXT_SIGNING_KEY key should go before the QSTASH_TOKEN key

(UnorderedKey)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

GitHub Check: cubic · AI code reviewer
GitHub Check: Jit Security
GitHub Check: test

🔇 Additional comments (11)

docker-compose.yml (1)

79-79: Default bypass flag change aligns with PR objectives.

Setting NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS to true as default in Docker Compose is appropriate for self-hosted deployments and coordinates with the removal of this flag from .env.example.

docs/hosting/environment-variables.md (3)

35-36: Clarified Redis requirement conditions.

The updated description correctly specifies that Redis variables are required only when not using Docker Compose with local Redis. This aligns with the auto-configuration behavior described in the Self-Hosting Guide.

86-86: Updated bypass flag default matches docker-compose.yml.

The default for NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS is now correctly documented as true, consistent with the docker-compose change and self-hosting recommendations.

104-104: Notes section consolidation improves clarity.

Replacing the detailed Redis and bypass flag notes with a single reference to the Self-Hosting Guide reduces duplication and directs users to comprehensive deployment guidance.

apps/web/.env.example (3)

1-10: New Docker auto-configured variables section improves clarity.

The commented section at the top clearly indicates which variables are set by docker-compose and when users should uncomment them for local development. This prevents configuration confusion and aligns with the deployment documentation.

9-9: NEXT_PUBLIC_BYPASS_PREMIUM_CHECKS removal from active config is intentional.

The flag is now set exclusively via docker-compose.yml defaults (Line 79) rather than in the .env.example. This simplifies the example file and centralizes Docker-specific defaults, which is appropriate for self-hosting guidance. Users running locally without Docker can uncomment it from the Docker auto-configured section if needed.

18-20: All new environment variables are already properly registered in apps/web/env.ts with correct Zod schema validation.

Verification confirms:

EMAIL_ENCRYPT_SECRET (line 27): z.string() ✓

EMAIL_ENCRYPT_SALT (line 28): z.string() ✓

API_KEY_SALT (line 94): z.string().optional() ✓

INTERNAL_API_KEY (line 114): z.string() ✓

All variables are correctly placed in the server section and use appropriate Zod validation. Since these are server-only variables (no NEXT_PUBLIC_ prefix), they correctly do not appear in experimental__runtimeEnv.

docs/hosting/self-hosting.md (4)

53-53: Added helpful clarification about Docker auto-configured variables.

The note clearly explains that the commented Docker variables should remain commented because docker-compose automatically sets them with correct internal hostnames. This prevents a common configuration mistake.

60-60: Runtime NEXT_PUBLIC_BASE_URL configuration is correctly documented.

The deployment command now correctly passes NEXT_PUBLIC_BASE_URL as a shell environment variable at runtime, and the added note (Line 65) clearly explains why: docker-compose.yml overrides the .env file value. This is a critical clarification that prevents misconfiguration in production deployments.

Also applies to: 65-65

90-91: Prisma migration commands correctly use pre-installed container version.

Updated commands use docker compose exec web prisma migrate deploy instead of npx, which correctly reflects that Prisma is pre-installed in the production image. This avoids unnecessary npx overhead and prevents version mismatches.

Also applies to: 115-115, 118-118

96-96: Added practical troubleshooting guidance.

The new troubleshooting note about running docker compose pull web addresses the specific scenario where npx attempts to install a different Prisma version. This is helpful documentation for common runtime issues.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

cubic-dev-ai

No issues found across 4 files

jit-ci

❌ The following Jit checks failed to run:

secret-detection

#jit_bypass_commit in this PR to bypass, Jit Admin privileges required.

More info in the Jit platform.

adjust default env

a1d3a6f

vercel bot deployed to Preview November 27, 2025 14:05 View deployment

cubic-dev-ai bot reviewed Nov 27, 2025

View reviewed changes

jit-ci bot reviewed Nov 27, 2025

View reviewed changes

elie222 merged commit 572d8ca into main Nov 27, 2025
15 of 17 checks passed

elie222 deleted the chore/docker-compose-defaults branch November 27, 2025 14:18

This was referenced Jan 4, 2026

feat: add devcontainer for local development #1188

Merged

config: rename LOG_ZOD_ERRORS to DISABLE_LOG_ZOD_ERRORS #1236

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Adjust env example and docs#1024

Adjust env example and docs#1024
elie222 merged 1 commit intomainfrom
chore/docker-compose-defaults

elie222 commented Nov 27, 2025 •

edited by coderabbitai bot

Loading

Uh oh!

vercel bot commented Nov 27, 2025 •

edited

Loading

Uh oh!

coderabbitai bot commented Nov 27, 2025 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

jit-ci bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Comments

Conversation

elie222 commented Nov 27, 2025 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Set default premium bypass to true in Docker Compose and restructure environment variable docs and examples for Docker-focused self-hosting

📍Where to Start

Summary by CodeRabbit

Uh oh!

vercel bot commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Nov 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Pre-merge checks and finishing touches

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

jit-ci bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

elie222 commented Nov 27, 2025 •

edited by coderabbitai bot

Loading

vercel bot commented Nov 27, 2025 •

edited

Loading

coderabbitai bot commented Nov 27, 2025 •

edited

Loading