docs: add troubleshooting section to SETUP.md#1070
Conversation
WalkthroughThis PR adds a comprehensive Troubleshooting section to ChangesSetup Troubleshooting Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@SETUP.md`:
- Around line 108-109: Add entries for REDIS_HOST and REDIS_PASSWORD to the main
"Environment Variables" table so Redis connection params are documented and
their required/optional status is clear; reference the existing table and
include REDIS_HOST with examples/values for Docker Compose ("redis") vs local
("localhost") and REDIS_PASSWORD with guidance that empty means no password and
to avoid invisible characters, marking whether each is required (or optional)
and describing acceptable formats. Ensure the new descriptions mention the same
semantics used in the lines that currently note "Wrong `REDIS_HOST`" and "No
password" so the table and the inline notes stay consistent.
- Line 150: Add a new entry for the MAX_CONCURRENT_BROWSERS environment variable
in the Environment Variables table: declare the variable name
MAX_CONCURRENT_BROWSERS, set its purpose as "Limits the number of concurrent
Playwright browser instances for low-memory systems (performance tuning)",
provide a sensible default (e.g., 1), and mark "Mandatory" as "No"; update any
related examples or notes in SETUP.md where MAX_CONCURRENT_BROWSERS is
referenced so the table and the mention at line 150 are consistent.
- Line 99: Add MINIO_SECRET_KEY to the Environment Variables table next to
MINIO_ACCESS_KEY: add a table row for MINIO_SECRET_KEY (name: MINIO_SECRET_KEY),
mark it as required/mandatory, and give a short description like "MinIO secret
key used with MINIO_ACCESS_KEY for S3-compatible authentication — must match the
value used to initialize MinIO"; ensure formatting matches the existing table
rows and mention it pairs with MINIO_ACCESS_KEY for authentication.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| **Causes & Solutions**: | ||
| - MinIO not running: `sudo systemctl start minio` (Linux) or start MinIO app (macOS/Windows) | ||
| - Wrong `MINIO_ENDPOINT`: If running locally without Docker, use `localhost`. With Docker, use the service name `minio` | ||
| - Wrong credentials: `MINIO_ACCESS_KEY` and `MINIO_SECRET_KEY` must match what MinIO was initialized with |
There was a problem hiding this comment.
Document MINIO_SECRET_KEY in the Environment Variables table.
Line 99 references MINIO_SECRET_KEY, but this variable is not documented in the Environment Variables table (lines 51-76). Only MINIO_ACCESS_KEY is listed. Since MinIO requires both an access key and secret key for authentication, MINIO_SECRET_KEY should be added to the main environment variables table with appropriate description and mandatory status.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@SETUP.md` at line 99, Add MINIO_SECRET_KEY to the Environment Variables table
next to MINIO_ACCESS_KEY: add a table row for MINIO_SECRET_KEY (name:
MINIO_SECRET_KEY), mark it as required/mandatory, and give a short description
like "MinIO secret key used with MINIO_ACCESS_KEY for S3-compatible
authentication — must match the value used to initialize MinIO"; ensure
formatting matches the existing table rows and mention it pairs with
MINIO_ACCESS_KEY for authentication.
| - Wrong `REDIS_HOST`: In Docker Compose, use `redis`. Locally, use `localhost` | ||
| - No password: If `REDIS_PASSWORD` is empty, ensure it is not set to a space or invisible character |
There was a problem hiding this comment.
Document Redis environment variables in the Environment Variables table.
Lines 108-109 reference REDIS_HOST and REDIS_PASSWORD, but these variables are not documented in the Environment Variables table (lines 51-76). If Redis is a required dependency (as stated in line 17), its connection parameters should be fully documented in the main environment variables section with appropriate descriptions and mandatory status.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@SETUP.md` around lines 108 - 109, Add entries for REDIS_HOST and
REDIS_PASSWORD to the main "Environment Variables" table so Redis connection
params are documented and their required/optional status is clear; reference the
existing table and include REDIS_HOST with examples/values for Docker Compose
("redis") vs local ("localhost") and REDIS_PASSWORD with guidance that empty
means no password and to avoid invisible characters, marking whether each is
required (or optional) and describing acceptable formats. Ensure the new
descriptions mention the same semantics used in the lines that currently note
"Wrong `REDIS_HOST`" and "No password" so the table and the inline notes stay
consistent.
| ### Performance Issues | ||
|
|
||
| - Increase `shm_size` in docker-compose for Playwright (recommended: `2gb`) | ||
| - Limit Playwright browsers: Set `MAX_CONCURRENT_BROWSERS=1` if running on low-memory systems |
There was a problem hiding this comment.
Document MAX_CONCURRENT_BROWSERS in the Environment Variables table.
Line 150 references MAX_CONCURRENT_BROWSERS as a performance tuning option, but this variable is not documented in the Environment Variables table (lines 51-76). If this is a supported configuration option, it should be added to the environment variables section with appropriate description and mandatory status (likely "No" since it's for performance tuning).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@SETUP.md` at line 150, Add a new entry for the MAX_CONCURRENT_BROWSERS
environment variable in the Environment Variables table: declare the variable
name MAX_CONCURRENT_BROWSERS, set its purpose as "Limits the number of
concurrent Playwright browser instances for low-memory systems (performance
tuning)", provide a sensible default (e.g., 1), and mark "Mandatory" as "No";
update any related examples or notes in SETUP.md where MAX_CONCURRENT_BROWSERS
is referenced so the table and the mention at line 150 are consistent.
1 participant
Summary
Problem
SETUP.md had no troubleshooting section despite requiring 15+ complex environment variables and 4 external services (PostgreSQL, MinIO, Redis, Playwright). New self-hosters regularly hit the same errors (ECONNREFUSED, MinIO unreachable, JWT malformed, CORS).
Solution
Add a dedicated Troubleshooting section with symptom/cause/solution format:
Risk / Compatibility
Notes for maintainers
Summary by CodeRabbit