Skip to content

Commit 75a3989

Browse files
sis0k0sis0k0
authored
Merge pull request #51 from mongodb-developer/update-lf
Update project metadata and CI workflow
2 parents e9558ff + fc3f108 commit 75a3989

15 files changed

Lines changed: 544 additions & 41 deletions

File tree

‎.claude/settings.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"enabledPlugins": {
3+
"mongodb@claude-plugins-official": true
4+
}
5+
}

‎.devcontainer/README.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Codespaces & Dev Container Setup
2+
3+
This project is configured to work seamlessly in GitHub Codespaces or with VS Code Dev Containers.
4+
5+
## Starting with Codespaces
6+
7+
1. **Click "Code" → "Codespaces" → "Create codespace on main"** from the GitHub repo
8+
2. The devcontainer will automatically:
9+
- Spin up a MongoDB instance (Atlas Local)
10+
- Install all dependencies
11+
- Seed sample data
12+
13+
## Using with VS Code Dev Containers
14+
15+
1. **Install the Dev Containers extension** in VS Code
16+
2. **Open the repo locally** and run: `Ctrl+Shift+P` → "Dev Containers: Reopen in Container"
17+
3. VS Code will build the environment and start MongoDB
18+
19+
## Accessing Services
20+
21+
Once the devcontainer is running:
22+
23+
| Service | URL | Purpose |
24+
|---------|-----|---------|
25+
| React App | http://localhost:5173 | Frontend (Vite dev server) |
26+
| Express API | http://localhost:5050 | Backend REST API |
27+
| MongoDB | mongodb://admin:mongodb@localhost:27017 | Database (no browser UI) |
28+
| MongoDB VS Code Extension | N/A | Query database directly in VS Code |
29+
30+
## Quick Start in Codespaces
31+
32+
Once the devcontainer is fully loaded (wait for "Poststart" to complete):
33+
34+
```bash
35+
# Terminal 1: Start the Express server
36+
cd mern/server
37+
npm start
38+
39+
# Terminal 2: Start the React dev server
40+
cd mern/client
41+
npm run dev
42+
```
43+
44+
Then open http://localhost:5173 in your browser.
45+
46+
## Database Credentials
47+
48+
- **Host**: `mongodb` (inside container) or `localhost:27017` (from host)
49+
- **Username**: `admin`
50+
- **Password**: `mongodb`
51+
- **Database**: `employees`
52+
53+
## Seeding Sample Data
54+
55+
The devcontainer automatically seeds sample data on startup. To manually reseed:
56+
57+
```bash
58+
cd mern/server
59+
node seed.js
60+
```
61+
62+
## VS Code Extensions
63+
64+
The devcontainer includes these extensions:
65+
66+
- **MongoDB for VS Code** — Query your MongoDB directly from VS Code
67+
- **TypeScript** — TypeScript language support
68+
- **Prettier** — Code formatter
69+
70+
## Troubleshooting
71+
72+
### MongoDB connection issues
73+
```bash
74+
# Check if MongoDB is running
75+
mongosh -u admin -p mongodb --eval "db.adminCommand('ping')"
76+
```
77+
78+
### Port conflicts
79+
If ports 5050, 5173, or 27017 are already in use:
80+
- **Codespaces**: Automatic port forwarding handles this
81+
- **Local Dev Container**: Modify `docker-compose.yml` to use different ports
82+
83+
### Rebuild the devcontainer
84+
```bash
85+
# VS Code: Ctrl+Shift+P → "Dev Containers: Rebuild Container"
86+
# CLI: devcontainer build --workspace-folder .
87+
```

‎.devcontainer/devcontainer.json‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
{
2+
"name": "MERN Stack with MongoDB",
3+
"dockerComposeFile": "docker-compose.yml",
4+
"service": "app",
5+
"workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
6+
7+
"features": {
8+
"ghcr.io/devcontainers/features/node:1": {
9+
"version": "22"
10+
}
11+
},
12+
13+
"customizations": {
14+
"vscode": {
15+
"extensions": [
16+
"mongodb.mongodb-vscode",
17+
"ms-vscode.vscode-typescript-next",
18+
"esbenp.prettier-vscode"
19+
],
20+
"settings": {
21+
"mongodb.connectionSslEnabled": false,
22+
"mongodb.defaultAuthenticationDatabase": "admin"
23+
}
24+
}
25+
},
26+
27+
"forwardPorts": [5050, 5173, 27017],
28+
"portsAttributes": {
29+
"5050": {
30+
"label": "Express API",
31+
"onAutoForward": "notify"
32+
},
33+
"5173": {
34+
"label": "React Dev Server",
35+
"onAutoForward": "notify"
36+
},
37+
"27017": {
38+
"label": "MongoDB",
39+
"onAutoForward": "silent"
40+
}
41+
},
42+
43+
"postCreateCommand": "cd mern/server && npm ci && node seed.js && cd ../client && npm ci",
44+
45+
"remoteEnv": {
46+
"ATLAS_URI": "mongodb://admin:mongodb@mongodb:27017/employees"
47+
}
48+
}

‎.devcontainer/docker-compose.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
version: '3.8'
2+
3+
services:
4+
app:
5+
image: mcr.microsoft.com/devcontainers/javascript-node:22-bookworm
6+
volumes:
7+
- ../..:/workspaces:cached
8+
command: sleep infinity
9+
network_mode: service:mongodb
10+
environment:
11+
- ATLAS_URI=mongodb://admin:mongodb@mongodb:27017/employees
12+
- PORT=5050
13+
14+
mongodb:
15+
image: mongodb/mongodb-atlas-local:latest
16+
restart: unless-stopped
17+
ports:
18+
- 27017:27017
19+
environment:
20+
MONGODB_INITDB_ROOT_USERNAME: admin
21+
MONGODB_INITDB_ROOT_PASSWORD: mongodb
22+
MONGO_INITDB_DATABASE: employees
23+
volumes:
24+
- mongodb-data:/data/db
25+
- mongodb-config:/data/configdb
26+
healthcheck:
27+
test: mongosh --eval "db.adminCommand('ping')"
28+
interval: 10s
29+
timeout: 5s
30+
retries: 5
31+
32+
volumes:
33+
mongodb-data:
34+
mongodb-config:

‎.github/workflows/main.yaml‎

Lines changed: 45 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,71 @@
1-
# This is a basic workflow to help you get started with Actions
2-
31
name: CI
42

5-
# Controls when the workflow will run
63
on:
7-
# Triggers the workflow on push or pull request events but only for the main branch
84
push:
9-
branches: [ $default-branch ]
5+
branches: [ main ]
106
pull_request:
11-
branches: [ $default-branch ]
12-
13-
# Allows you to run this workflow manually from the Actions tab
7+
branches: [ main ]
148
workflow_dispatch:
159

16-
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
1710
jobs:
18-
# This workflow contains a single job called "build"
19-
2011
build:
21-
# The type of runner that the job will run on
2212
runs-on: ubuntu-latest
2313
environment: Testing
2414
strategy:
2515
matrix:
26-
node-version: [14.x , 16.x]
27-
max-parallel: 1
28-
29-
# Steps represent a sequence of tasks that will be executed as part of the job
16+
node-version: [20.x, 22.x]
17+
max-parallel: 1
18+
services:
19+
mongodb:
20+
image: mongo:latest
21+
options: >-
22+
--health-cmd mongosh
23+
--health-interval 10s
24+
--health-timeout 5s
25+
--health-retries 5
26+
ports:
27+
- 27017:27017
28+
env:
29+
MONGO_INITDB_ROOT_USERNAME: admin
30+
MONGO_INITDB_ROOT_PASSWORD: mongodb
31+
3032
steps:
31-
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
32-
- uses: actions/checkout@v2
33-
with:
34-
ref: 'main-test'
33+
- uses: actions/checkout@v4
3534

36-
- name: Install server npm packages
37-
uses: bahmutov/npm-install@v1
35+
- name: Use Node.js ${{ matrix.node-version }}
36+
uses: actions/setup-node@v4
3837
with:
39-
working-directory: mern/server
38+
node-version: ${{ matrix.node-version }}
39+
cache: 'npm'
40+
cache-dependency-path: |
41+
mern/server/package-lock.json
42+
mern/client/package-lock.json
43+
44+
- name: Install server npm packages
45+
run: npm ci
46+
working-directory: mern/server
4047

4148
- name: Install client npm packages
42-
uses: bahmutov/npm-install@v1
43-
with:
44-
working-directory: mern/client
49+
run: npm ci
50+
working-directory: mern/client
4551

4652
- name: Start server in the background
47-
env:
48-
ATLAS_URI: ${{ secrets.ATLAS_URI }}
49-
run: (cd mern/server && echo "ATLAS_URI=$ATLAS_URI" > config.env && npm start &)
53+
env:
54+
ATLAS_URI: mongodb://admin:mongodb@localhost:27017/
55+
run: |
56+
echo "ATLAS_URI=$ATLAS_URI" > config.env
57+
npm start > /tmp/server.log 2>&1 &
58+
echo "Server PID: $!"
59+
working-directory: mern/server
5060

51-
- name: Start React app in the background
52-
run: (cd mern/client && npm start &)
61+
- name: Wait for server to be ready
62+
run: |
63+
npx wait-on http://localhost:5050/record --timeout 30000 || (cat /tmp/server.log && exit 1)
5364
5465
- name: Install Cypress and run tests
55-
uses: cypress-io/github-action@v2
66+
uses: cypress-io/github-action@v6
5667
with:
5768
working-directory: mern/client
69+
start: npm run dev
70+
wait-on: 'http://localhost:5173'
5871

‎AGENTS.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# AGENTS.md — AI Agent Guide
2+
3+
This file is the source of truth for AI agents working in this repository.
4+
5+
## Project Overview
6+
7+
Full-stack MERN CRUD app for managing employee records. React (Vite) frontend communicates with an Express REST API; MongoDB Atlas stores data in the `employees` database, `records` collection.
8+
9+
## Project Structure
10+
11+
```
12+
mern-stack-example/
13+
├── EDD.md # MongoDB data model — read before touching schema or routes
14+
├── mern/
15+
│ ├── client/ # React 18 + Vite + Tailwind CSS frontend
16+
│ │ ├── src/
17+
│ │ │ ├── App.jsx # Root component and routes
18+
│ │ │ ├── components/
19+
│ │ │ │ ├── Navbar.jsx
20+
│ │ │ │ ├── Record.jsx # Create / edit form
21+
│ │ │ │ └── RecordList.jsx # Main list view
22+
│ │ ├── vite.config.js
23+
│ │ └── package.json
24+
│ └── server/ # Node.js + Express REST API
25+
│ ├── db/
26+
│ │ └── connection.js # MongoDB Atlas connection (appName set here)
27+
│ ├── routes/
28+
│ │ └── record.js # GET / POST / PATCH / DELETE /record
29+
│ ├── seed.js # Database seed script
30+
│ ├── server.js # Express app entry point
31+
│ └── package.json
32+
└── .github/workflows/main.yaml # CI: install, start, Cypress e2e
33+
```
34+
35+
## Build and Test Commands
36+
37+
```bash
38+
# Install and start the API server
39+
cd mern/server
40+
npm install
41+
npm start # requires mern/server/config.env (see Environment Variables)
42+
43+
# Install and start the React dev server
44+
cd mern/client
45+
npm install
46+
npm run dev # serves on http://localhost:5173
47+
48+
# Seed the database
49+
cd mern/server
50+
node seed.js # requires ATLAS_URI in config.env
51+
52+
# Run Cypress e2e tests (client must be running)
53+
cd mern/client
54+
npx cypress run
55+
```
56+
57+
## Environment Variables
58+
59+
Create `mern/server/config.env` (not committed):
60+
61+
| Variable | Description | Example |
62+
|-------------|------------------------------------------|---------|
63+
| `ATLAS_URI` | MongoDB Atlas connection string | `mongodb+srv://user:pass@cluster.mongodb.net/` |
64+
| `PORT` | Port for the Express server | `5050` |
65+
66+
## MongoDB Skills
67+
68+
Use the official MongoDB agent skills from https://github.com/mongodb/agent-skills
69+
whenever the task is MongoDB-specific and a matching skill exists.
70+
71+
## When To Use EDD.md
72+
73+
Use [EDD.md](./EDD.md) as the source of truth for the MongoDB data model in this repository.
74+
75+
Consult [EDD.md](./EDD.md) before making changes that touch:
76+
77+
- MongoDB collections, document structure, or field names
78+
- Express routes that read or write database records
79+
- Validation, form fields, API payloads, or UI that depend on persisted data
80+
- Schema documentation, Mermaid diagrams, or entity modeling discussions

0 commit comments

Comments
 (0)