docs: improve setup documentation and add .env.sample template#32
docs: improve setup documentation and add .env.sample template#32AkramZaabi wants to merge 2 commits intoalphaonelabs:mainfrom
Conversation
WalkthroughThis pull request adds development environment configuration templates and updates setup documentation. Changes include whitelisting a Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.gitignore (1)
20-31: 🧹 Nitpick | 🔵 TrivialRemove duplicate whitelist entry to keep ignore rules unambiguous.
!.env.sampleis declared twice. Keeping only the one after.env*is sufficient and clearer.Suggested cleanup
# Environment & secrets .env .env.local .dev.vars -!.env.sample @@ .env* !.env.sample🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.gitignore around lines 20 - 31, Remove the duplicate whitelist pattern in .gitignore: keep only one occurrence of the negation rule for .env.sample and delete the earlier duplicate (remove the first "!.env.sample" near the top), ensuring the negation after ".env*" remains to make the rules unambiguous; verify there is exactly one "!.env.sample" entry in the file.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Line 100: Replace the phrase "separate instructions" with "separate terminals"
in the README sentence describing how to run the backend worker and frontend
HTML files so it reads that they should be run concurrently in separate
terminals; update the exact sentence where the README currently says "Run them
concurrently in separate instructions." to "Run them concurrently in separate
terminals." to improve clarity for new contributors.
- Line 126: The README.md currently lacks the required trailing newline (MD047);
open README.md and ensure the file ends with exactly one newline character (no
extra blank lines or missing newline) so the final byte is a single newline to
satisfy the linter rule MD047.
- Around line 82-87: Update the README snippet to instruct contributors to copy
the provided .env.sample into .dev.vars instead of duplicating values inline:
replace the explicit key/value block with a short instruction to run "cp
.env.sample .dev.vars" and then edit .dev.vars to replace placeholders
(ENCRYPTION_KEY, JWT_SECRET) with local secrets so the docs follow the
.env.sample template flow.
- Around line 53-69: The ordered list numbering in the README segment containing
"Create the Database:", "Add configuration to `wrangler.toml`:", and "Apply the
Schema:" must use repeated "1." entries to satisfy markdownlint MD029; update
each numeric prefix (currently 1/2/3) so every list item begins with "1." while
preserving the existing content and fenced code blocks (the wrangler d1 create
command and toml snippet) and spacing.
- Around line 84-87: The fenced code block showing environment variables in
README.md lacks a language tag; update the block delimiter from ``` to include a
language (e.g., use ```env) so the snippet becomes a fenced code block with a
language tag for lint MD040 compliance, keeping the same lines
"ENCRYPTION_KEY=your-dev-encryption-key" and "JWT_SECRET=your-dev-jwt-secret".
---
Outside diff comments:
In @.gitignore:
- Around line 20-31: Remove the duplicate whitelist pattern in .gitignore: keep
only one occurrence of the negation rule for .env.sample and delete the earlier
duplicate (remove the first "!.env.sample" near the top), ensuring the negation
after ".env*" remains to make the rules unambiguous; verify there is exactly one
"!.env.sample" entry in the file.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: alphaonelabs/coderabbit/.coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 8ec122e0-e9ea-4650-a219-418647bb4667
📒 Files selected for processing (3)
.env.sample.gitignoreREADME.md
| 1. **Create the Database:** | ||
|
|
||
| ```bash | ||
| wrangler d1 create education_db | ||
| ``` | ||
|
|
||
| - Add the generated database_id to your wrangler.toml: | ||
| 2. **Add configuration to `wrangler.toml`:** | ||
| After running the create command, copy the `database_id` from the output and update your `wrangler.toml` file with this placeholder: | ||
|
|
||
| ```toml | ||
| [[d1_databases]] | ||
| binding = "DB" | ||
| database_name = "education_db" | ||
| database_id = "YOUR_DATABASE_ID" | ||
| database_id = "<YOUR_DATABASE_ID>" | ||
| ``` | ||
|
|
||
| - Apply Schema: | ||
| 3. **Apply the Schema:** |
There was a problem hiding this comment.
Fix ordered-list numbering to satisfy markdownlint (MD029).
This repo’s lint rule expects 1. for each ordered item, not 1/2/3.
Lint-safe numbering
-2. **Add configuration to `wrangler.toml`:**
+1. **Add configuration to `wrangler.toml`:**
@@
-3. **Apply the Schema:**
+1. **Apply the Schema:**📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 1. **Create the Database:** | |
| ```bash | |
| wrangler d1 create education_db | |
| ``` | |
| - Add the generated database_id to your wrangler.toml: | |
| 2. **Add configuration to `wrangler.toml`:** | |
| After running the create command, copy the `database_id` from the output and update your `wrangler.toml` file with this placeholder: | |
| ```toml | |
| [[d1_databases]] | |
| binding = "DB" | |
| database_name = "education_db" | |
| database_id = "YOUR_DATABASE_ID" | |
| database_id = "<YOUR_DATABASE_ID>" | |
| ``` | |
| - Apply Schema: | |
| 3. **Apply the Schema:** | |
| 1. **Create the Database:** | |
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 59-59: Ordered list item prefix
Expected: 1; Actual: 2; Style: 1/1/1
(MD029, ol-prefix)
[warning] 69-69: Ordered list item prefix
Expected: 1; Actual: 3; Style: 1/1/1
(MD029, ol-prefix)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 53 - 69, The ordered list numbering in the README
segment containing "Create the Database:", "Add configuration to
`wrangler.toml`:", and "Apply the Schema:" must use repeated "1." entries to
satisfy markdownlint MD029; update each numeric prefix (currently 1/2/3) so
every list item begins with "1." while preserving the existing content and
fenced code blocks (the wrangler d1 create command and toml snippet) and
spacing.
| ``` | ||
| ENCRYPTION_KEY=your-dev-encryption-key | ||
| JWT_SECRET=your-dev-jwt-secret | ||
| ``` |
There was a problem hiding this comment.
Add a language to fenced code blocks (MD040).
The fence should include a language tag for lint compliance.
Minimal fix
-```
+```env
ENCRYPTION_KEY=your-dev-encryption-key
JWT_SECRET=your-dev-jwt-secret</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 84-84: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 84 - 87, The fenced code block showing environment
variables in README.md lacks a language tag; update the block delimiter from ```
to include a language (e.g., use ```env) so the snippet becomes a fenced code
block with a language tag for lint MD040 compliance, keeping the same lines
"ENCRYPTION_KEY=your-dev-encryption-key" and "JWT_SECRET=your-dev-jwt-secret".
| ### Running the Application | ||
|
|
||
| ### Run Backend | ||
| The application consists of a backend worker and frontend HTML files. Run them concurrently in separate instructions. |
There was a problem hiding this comment.
Wording tweak: use “separate terminals” instead of “separate instructions.”
This improves execution clarity for new contributors.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 100, Replace the phrase "separate instructions" with
"separate terminals" in the README sentence describing how to run the backend
worker and frontend HTML files so it reads that they should be run concurrently
in separate terminals; update the exact sentence where the README currently says
"Run them concurrently in separate instructions." to "Run them concurrently in
separate terminals." to improve clarity for new contributors.
|
|
||
| - **`wrangler: command not found`**: Ensure that npm's global bin directory is in your system's PATH. | ||
| - **`D1_ERROR` when running backend**: Check that you have replaced `<YOUR_DATABASE_ID>` with your actual database ID inside `wrangler.toml`. | ||
| - **CORS Errors**: If the frontend cannot communicate with the backend, ensure your backend is running (`wrangler dev`) and check the console. Ensure you are accessing the frontend via a local server (e.g., `http://localhost:3000`) rather than a `file://` URL. No newline at end of file |
There was a problem hiding this comment.
Add a trailing newline at end of file (MD047).
README should end with exactly one newline to pass lint.
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 126-126: Files should end with a single newline character
(MD047, single-trailing-newline)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 126, The README.md currently lacks the required trailing
newline (MD047); open README.md and ensure the file ends with exactly one
newline character (no extra blank lines or missing newline) so the final byte is
a single newline to satisfy the linter rule MD047.
There was a problem hiding this comment.
Pull request overview
Improves local development onboarding by expanding setup instructions in README.md and adding a committed environment variable template file to standardize local configuration.
Changes:
- Documented clearer prerequisites, repo clone/fork workflow, and separate backend/frontend run steps.
- Expanded Cloudflare D1 setup steps and added a “Common Errors” troubleshooting section.
- Added
.env.sampletemplate and updated.gitignoreto ensure it’s committed.
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| README.md | Expanded local setup steps, D1 instructions, and troubleshooting guidance. |
| .gitignore | Ensures .env.sample is not ignored so it can be committed. |
| .env.sample | Adds a template for required local secrets (encryption/auth). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Running the Application | ||
|
|
||
| ### Run Backend | ||
| The application consists of a backend worker and frontend HTML files. Run them concurrently in separate instructions. |
There was a problem hiding this comment.
“Run them concurrently in separate instructions” reads like a typo/wording error (likely meant “separate terminals” or “separate shells”). Tweaking this phrasing would make the setup steps clearer.
| The application consists of a backend worker and frontend HTML files. Run them concurrently in separate instructions. | |
| The application consists of a backend worker and frontend HTML files. Run them concurrently in separate terminal sessions. |
| git remote add upstream https://github.com/alphaonelabs/learn.git | ||
| ``` | ||
|
|
||
| ### Login to Cloudflare (One time) |
There was a problem hiding this comment.
Heading uses “One time” where the standard phrasing is “One-time”. Please update for consistency/grammar.
| ### Login to Cloudflare (One time) | |
| ### Login to Cloudflare (One-time) |
| # ======================================== | ||
| # Encryption | ||
| # ======================================== | ||
| # Used to encrypt user PII (Personal Identifiable Information) and activity data |
There was a problem hiding this comment.
PII is typically expanded as “Personally Identifiable Information”, not “Personal Identifiable Information”. Update the wording to the standard expansion.
| # Used to encrypt user PII (Personal Identifiable Information) and activity data | |
| # Used to encrypt user PII (Personally Identifiable Information) and activity data |
| 2. **Add configuration to `wrangler.toml`:** | ||
| After running the create command, copy the `database_id` from the output and update your `wrangler.toml` file with this placeholder: | ||
|
|
||
| ```toml | ||
| [[d1_databases]] | ||
| binding = "DB" | ||
| database_name = "education_db" | ||
| database_id = "YOUR_DATABASE_ID" | ||
| database_id = "<YOUR_DATABASE_ID>" | ||
| ``` |
There was a problem hiding this comment.
The D1 setup instructions refer to updating a placeholder database_id, but the repo’s wrangler.toml currently has a concrete UUID committed. This is confusing for new contributors (they may not have access to that D1 DB). Consider adjusting the text to explain they should replace the existing database_id with the UUID from their own wrangler d1 create output (or provide a separate dev/prod config approach).
There was a problem hiding this comment.
Since this is a Cloudflare Workers project it uses .dev.vars for local env variables instead of the standard .env. To avoid any confusion for new contributors, could you rename this file to .dev.vars.example or .dev.vars.sample (whatever suits the best)?
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (4)
README.md (4)
126-126:⚠️ Potential issue | 🟡 MinorEnsure README ends with exactly one trailing newline (MD047).
Please add a single final newline at EOF.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 126, The README.md currently violates MD047 (multiple or missing final newlines); open README.md, remove any extra blank lines at the end and ensure the file terminates with exactly one trailing newline character (save the file so the final byte is a single '\n'), then re-run lint to confirm MD047 is resolved.
100-100:⚠️ Potential issue | 🟡 MinorReplace “separate instructions” with “separate terminals.”
The current wording is confusing for execution steps.
Suggested patch
-The application consists of a backend worker and frontend HTML files. Run them concurrently in separate instructions. +The application consists of a backend worker and frontend HTML files. Run them concurrently in separate terminals.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 100, Replace the phrase "separate instructions" with "separate terminals" in the README text that currently reads "The application consists of a backend worker and frontend HTML files. Run them concurrently in separate instructions." Locate that exact sentence and update it so it now reads "... Run them concurrently in separate terminals." to remove confusion around execution steps.
59-69:⚠️ Potential issue | 🟡 MinorUse
1.for all ordered list items to satisfy markdownlint MD029.This list currently uses
2.and3.; your lint profile expects repeated1.style.Suggested patch
-2. **Add configuration to `wrangler.toml`:** +1. **Add configuration to `wrangler.toml`:** @@ -3. **Apply the Schema:** +1. **Apply the Schema:**🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 59 - 69, Change the ordered list numbering in README.md to use repeated "1." for each item to satisfy markdownlint MD029; specifically update the list entries that start with "2. **Add configuration to `wrangler.toml`:**" and "3. **Apply the Schema:**" so both use "1." (e.g., "1. **Add configuration to `wrangler.toml`:**" and "1. **Apply the Schema:**") while keeping the existing text and code block intact.
84-84:⚠️ Potential issue | 🟡 MinorAdd a language tag to the fenced env block (MD040).
On Line 84, use a typed fence for lint compliance and readability.
Suggested patch
-``` +```env ENCRYPTION_KEY=your-dev-encryption-key JWT_SECRET=your-dev-jwt-secret</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@README.mdat line 84, The fenced code block containing the environment
variables (the block with ENCRYPTION_KEY and JWT_SECRET) is missing a language
tag, causing MD040 lint failures; update the opening fence to include the 'env'
language tag (i.e., change the triple backticks to include env) so the block
becomes a typed fenced block for readability and lint compliance.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.dev.vars.sample:
- Line 8: Replace the incorrect phrase "Personal Identifiable Information" with
the correct term "Personally Identifiable Information" in the comment that reads
"Used to encrypt user Personal Identifiable Information and activity data";
search for that exact phrase and update it so the line reads "Used to encrypt
user Personally Identifiable Information and activity data".
Duplicate comments:
In@README.md:
- Line 126: The README.md currently violates MD047 (multiple or missing final
newlines); open README.md, remove any extra blank lines at the end and ensure
the file terminates with exactly one trailing newline character (save the file
so the final byte is a single '\n'), then re-run lint to confirm MD047 is
resolved.- Line 100: Replace the phrase "separate instructions" with "separate terminals"
in the README text that currently reads "The application consists of a backend
worker and frontend HTML files. Run them concurrently in separate instructions."
Locate that exact sentence and update it so it now reads "... Run them
concurrently in separate terminals." to remove confusion around execution steps.- Around line 59-69: Change the ordered list numbering in README.md to use
repeated "1." for each item to satisfy markdownlint MD029; specifically update
the list entries that start with "2. Add configuration towrangler.toml:"
and "3. Apply the Schema:" so both use "1." (e.g., "1. Add configuration
towrangler.toml:" and "1. Apply the Schema:") while keeping the
existing text and code block intact.- Line 84: The fenced code block containing the environment variables (the block
with ENCRYPTION_KEY and JWT_SECRET) is missing a language tag, causing MD040
lint failures; update the opening fence to include the 'env' language tag (i.e.,
change the triple backticks to include env) so the block becomes a typed fenced
block for readability and lint compliance.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Repository: alphaonelabs/coderabbit/.coderabbit.yaml **Review profile**: ASSERTIVE **Plan**: Pro **Run ID**: `eb8a7638-eab0-41aa-b4cc-965dfc449eca` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 06d4b2efe0a5d4e3c29a53c2aede76e4c88a9941 and b5e091b77dda27446426460936323d36298f97ff. </details> <details> <summary>📒 Files selected for processing (3)</summary> * `.dev.vars.sample` * `.gitignore` * `README.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
| # ======================================== | ||
| # Encryption | ||
| # ======================================== | ||
| # Used to encrypt user PII (Personal Identifiable Information) and activity data |
There was a problem hiding this comment.
Fix PII terminology on Line 8.
Use “Personally Identifiable Information” (not “Personal Identifiable Information”) for correctness in security/privacy docs.
Suggested patch
-# Used to encrypt user PII (Personal Identifiable Information) and activity data
+# Used to encrypt user PII (Personally Identifiable Information) and activity data📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Used to encrypt user PII (Personal Identifiable Information) and activity data | |
| # Used to encrypt user PII (Personally Identifiable Information) and activity data |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.dev.vars.sample at line 8, Replace the incorrect phrase "Personal
Identifiable Information" with the correct term "Personally Identifiable
Information" in the comment that reads "Used to encrypt user Personal
Identifiable Information and activity data"; search for that exact phrase and
update it so the line reads "Used to encrypt user Personally Identifiable
Information and activity data".
|
Thanks for the suggestion, great point. its done ! |
Summary
This PR improves the local development onboarding experience by updating the README and adding a template for environment variables.
README.md Updates:
database_id.wrangler dev) and frontend (npx serve) startup instructions..env.sample Added:
ENCRYPTION_KEYandJWT_SECRET.Why This Helps
Testing
.env.samplematches runtime expectations for environment variables.Purpose
This PR improves local development onboarding by enhancing documentation and providing an environment variables template, making it easier for new contributors to set up and run the project locally.
Key Changes
Documentation Updates (README.md)
database_idintowrangler.tomlwrangler dev) and frontend (npx serve public) startup instructions with expected localhost portsEnvironment Variables Template (.dev.vars.sample)
ENCRYPTION_KEY(for encrypting PII and activity data) andJWT_SECRET(for JWT signing).dev.varsfor local developmentProject Configuration (.gitignore)
.dev.vars.sampleso it remains tracked in version control despite the broader environment file ignore patternsImpact