Skip to content

docs: improve setup documentation and add .env.sample template #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AkramZaabi wants to merge 5 commits into
base: main
Choose a base branch
from
Open

docs: improve setup documentation and add .env.sample template #32

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
06d4b2e
docs: improve setup documentation and add .env.sample template
AkramZaabi Mar 30, 2026
b5e091b
docs: rename env template to .dev.vars.sample
AkramZaabi Apr 5, 2026
9baf352
Apply suggestion from @Copilot
A1L13N Apr 23, 2026
2971434
Apply suggestion from @Copilot
A1L13N Apr 23, 2026
6cbbdb6
Apply suggestion from @Copilot
A1L13N Apr 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .env.sample
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Alpha One Labs Education Platform - Environment Variables Template
# Copy this file to `.dev.vars` for local development.
# Do not commit real secrets to version control.

# ========================================
# Encryption
# ========================================
# Used to encrypt user PII (Personal Identifiable Information) and activity data
# before storing it in the database. Ensure this is a strong randomly generated string.
ENCRYPTION_KEY=your-dev-encryption-key-here

# ========================================
# Authentication
# ========================================
# Used to sign JSON Web Tokens (JWT) for stateless user authentication.
# Keep this secret to prevent unauthorized token forging.
JWT_SECRET=your-dev-jwt-secret-here
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ venv/
.env
.env.local
.dev.vars
!.env.sample

# OS
.DS_Store
Expand All @@ -27,3 +28,4 @@ Thumbs.db
.idea/
*.swp
.env*
!.env.sample
75 changes: 43 additions & 32 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,102 +14,113 @@ Alpha One Labs is an education platform designed to facilitate both learning and

### Prerequisites

Make sure you have installed:
- Node.js
- Wrangler CLI
Before starting, ensure you have the following installed:
- **Node.js**: v18.0.0 or higher
- **npm**: v9.0.0 or higher
- **Wrangler CLI**: For deploying Cloudflare Workers

Install Wrangler:
Install Wrangler globally using npm:

```bash
npm install -g wrangler
```

### Clone the Repository
### Fork & Clone the Repository (For Contributors)

If you are a contributor, first fork the repository to your own GitHub account.

```bash
git clone https://github.com/alphaonelabs/learn.git
# Clone your fork (replace <your-username> with your actual username)
git clone https://github.com/<your-username>/learn.git
cd learn

# Add the original repository as an upstream remote
git remote add upstream https://github.com/alphaonelabs/learn.git
```

### Login to Cloudflare (One time)
Comment thread
A1L13N marked this conversation as resolved.
Outdated

Authenticate the Wrangler CLI with your Cloudflare account. This will open a browser window to complete the login process safely.

```bash
wrangler login
```

### Setup Database (D1)

- Create Database:
Follow these step-by-step instructions to set up your Cloudflare D1 database:

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>"
```
Comment on lines +59 to 67
Copy link

Copilot AI Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copilot uses AI. Check for mistakes.

- Apply Schema:
3. **Apply the Schema:**
Comment on lines +53 to +69
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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.

Suggested change
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.

Run the following to set up your database tables (for local development):

```bash
wrangler d1 execute education_db --file=schema.sql
wrangler d1 execute education_db --local --file=schema.sql
```

### Setup Environment Variables

This project requires environment variables for encryption and authentication.

- For Local Development
#### For Local Development

Create a `.dev.vars` file in the project root:
Create a `.dev.vars` file in the root of the project to store local secrets.

```
ENCRYPTION_KEY=your-dev-encryption-key
JWT_SECRET=your-dev-jwt-secret
```
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated
Comment on lines 84 to 87
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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".


- For Production
Use Wrangler secrets:
#### For Production

Use the Wrangler CLI to set secrets securely for your deployed worker:

```bash
wrangler secret put ENCRYPTION_KEY
wrangler secret put JWT_SECRET
```

### Running the Application

### Run Backend
The application consists of a backend worker and frontend HTML files. Run them concurrently in separate instructions.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated
Comment thread
A1L13N marked this conversation as resolved.
Outdated

```bash
wrangler dev
```
#### Run Backend

Backend server starts at:
Start the Cloudflare Worker locally:

```bash
http://127.0.0.1:8787
wrangler dev
```

### Run Frontend
The backend server usually starts at: `http://127.0.0.1:8787`

- Open directly
#### Run Frontend

```bash
public/index.html
```

- Use a local server
Serve the static files using a local development server (like `serve`):

```bash
npx serve public
```

Frontend Server will start at:
The frontend server usually starts at: `http://localhost:3000`

```bash
http://localhost:3000
```
### Common Errors

- **`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.
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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.

Loading