/local-frappe - Local Frappe Development

CRITICAL: TEST LOCALLY FIRST - NO EXCEPTIONS

NEVER deploy Frappe/Python changes directly to production.

The 15-20 minute production build/deploy cycle is UNACCEPTABLE for iterative development.

What This Command Does

Sets up and manages a local Frappe development environment for testing BEI custom APIs before deploying to production.

MANDATORY: Always test changes locally BEFORE pushing to production. The local environment matches production (Frappe v15, ERPNext v15, HRMS v15).

Quick Start

bash
1cd docker-dev
2dev.bat start     # Windows (first run takes 10-15 minutes)
3./dev.sh start    # Linux/Mac

Access

Login: Administrator / admin

Development Workflow

Standard Workflow (Edit → Sync → Test)

bash
1# 1. Edit your API file locally
2#    Example: hrms/api/employee_clearance.py
3
4# 2. Sync to container and clear cache
5dev.bat sync
6
7# 3. Test your API
8curl http://localhost:8000/api/method/hrms.api.employee_clearance.get_status
9
10# 4. When ready, commit and push to production
11git add .
12git commit -m "feat: Add employee clearance API"
13git push origin production

Helper Commands

File Structure

docker-dev/
├── docker-compose.yml    # Container orchestration
├── dev.bat               # Windows helper script
└── dev.sh                # Linux/Mac helper script

hrms/api/                 # BEI custom API files (synced to container)
├── __init__.py           # API exports (CRITICAL - update when adding new APIs)
├── hello.py              # Test endpoint
├── employee_clearance.py # Clearance APIs
├── enrichment.py         # Data enrichment APIs
├── google_chat.py        # Google Chat integration
├── google_drive.py       # Google Drive integration
├── google_login.py       # Google OAuth
├── oauth_tokens.py       # OAuth token management
├── onboarding.py         # Employee onboarding
└── roster.py             # Shift roster APIs

Adding a New API

1. Create your API file

python
1# hrms/api/my_new_api.py
2import frappe
3
4@frappe.whitelist(allow_guest=True)
5def hello():
6    """Test endpoint."""
7    return {"message": "Hello from my new API!"}
8
9@frappe.whitelist()
10def get_data():
11    """Requires authentication."""
12    return {"user": frappe.session.user}

2. Update init.py

python
1# hrms/api/__init__.py
2from hrms.api.my_new_api import (
3    hello,
4    get_data,
5)

3. Sync and test

bash
1dev.bat sync
2curl http://localhost:8000/api/method/hrms.api.my_new_api.hello

Container Configuration

Volumes

Note: Volumes persist data across container restarts. To completely reset, use docker compose down -v.

Troubleshooting

Container won't start

bash
1# Check logs
2dev.bat logs
3
4# Or directly
5docker logs frappe-dev

API changes not visible

bash
1# Force sync and clear cache
2dev.bat sync
3
4# If still not working, restart Frappe
5dev.bat restart

Database connection errors

bash
1# Check MariaDB is healthy
2docker ps
3
4# Should show mariadb-dev as (healthy)

Need fresh start

bash
1# WARNING: This deletes all data
2dev.bat reset
3# Or manually:
4docker compose -f docker-dev/docker-compose.yml down -v
5dev.bat start

First run taking too long

First run downloads and installs:

• Frappe Framework (~3 min)
• ERPNext (~5 min)
• HRMS (~3 min)
• Site creation (~2 min)

Total: 10-15 minutes. Subsequent starts are fast (~30 seconds).

Testing APIs

Without authentication

bash
1# APIs with @frappe.whitelist(allow_guest=True)
2curl http://localhost:8000/api/method/hrms.api.hello.hello

With authentication

bash
1# Get session cookie first
2curl -c cookies.txt -X POST http://localhost:8000/api/method/login \
3  -d "usr=Administrator" -d "pwd=admin"
4
5# Then use the cookie
6curl -b cookies.txt http://localhost:8000/api/method/hrms.api.roster.get_roster

Using bench execute

bash
1# Run Python code directly
2dev.bat bench execute hrms.api.hello.hello
3
4# With arguments
5dev.bat bench execute "hrms.api.employee_clearance.get_status" --args '["HR-EMP-0001"]'

When to Deploy to Production

After testing locally:

1. Commit changes:

   bash
   1git add hrms/api/
   2git commit -m "feat: Add employee clearance API"

2. Push to production branch:

   bash
   1git push origin production

3. Monitor GitHub Actions: https://github.com/Bebang-Enterprise-Inc/hrms/actions

4. Verify production:

   bash
   1curl https://hq.bebang.ph/api/method/hrms.api.hello.hello

See /deploy-frappe skill for full production deployment options.

DO NOT DO

1. NEVER edit files directly in the container - Changes are lost on restart
2. NEVER use docker commit - Corrupts the Python environment
3. NEVER push untested code to production - Always test locally first
4. NEVER skip updating __init__.py - API won't be whitelisted
5. NEVER assume production deploy will pick up code changes - Use no_cache=true (see below)

CRITICAL: Local vs Production Asset Handling

Why Local Works But Production Breaks

Local development allows bench build because:

• Single container environment
• No persistent asset volumes (fresh start each time)
• Development mode reloads assets on change

Production prohibits bench build because:

• Multi-container architecture (frontend + backend)
• Persistent volumes don't auto-update
• Assets baked into Docker image at build time

What This Means For You

The Production Rule

All code and asset changes MUST go through Docker image rebuild.

When you push to production:

1. GitHub Actions rebuilds the entire Docker image
2. New CSS/JS hashes are baked into image
3. Assets volume should be deleted before deploy
4. Fresh containers get consistent assets

Never "hot-fix" production by running bench commands.

See /deploy-frappe for the full CSS 404 root cause analysis and fix.

Testing Custom WWW Pages Locally

Creating Custom Pages (like login)

1. Create your page file:

   hrms/www/bei-login.html  # The HTML template
   hrms/www/bei-login.py    # Optional Python context handler
   

2. If redirecting from an existing route, add to hrms/hooks.py:

   python
   1website_redirects = [
   2    {"source": "/login", "target": "/bei-login", "redirect_http_status": 302},
   3]

3. Sync to container:

   bash
   1dev.bat sync

4. Test locally:

   bash
   1# Check redirect
   2curl -sI http://localhost:8000/login | grep -i location
   3
   4# Check page renders
   5curl -s http://localhost:8000/bei-login | grep -o "<title>.*</title>"

Important: Production Deployment Uses Docker Cache

After testing locally, you MUST use no_cache=true when deploying:

bash
1gh workflow run "Build and Deploy Frappe HRMS" --repo Bebang-Enterprise-Inc/hrms -f no_cache=true -f run_migrate=true

Why: Docker cache doesn't detect when git repo contents change. Without no_cache=true, the build serves cached layers from previous builds.

How to verify fresh build: Check GitHub Actions build time:

• ~2 min = CACHED (old code)
• ~5-10 min = FRESH (new code)

Running bei-tasks Frontend Locally (Added 2026-01-24)

For full-stack local development, run both Frappe AND bei-tasks locally:

1. Start Local Frappe

bash
1cd F:\Dropbox\Projects\BEI-ERP\docker-dev
2powershell -Command "docker compose up -d"
3# Wait for Frappe to start (~30 seconds if already initialized)

2. Generate API Keys (First Time Only)

bash
1# Login to get session cookie
2curl -c cookies.txt -X POST "http://localhost:8000/api/method/login" \
3  -d "usr=Administrator&pwd=admin"
4
5# Generate API keys
6curl -b cookies.txt -X POST \
7  "http://localhost:8000/api/method/frappe.core.doctype.user.user.generate_keys?user=Administrator"
8# Returns: {"message":{"api_key":"xxx","api_secret":"yyy"}}

3. Configure bei-tasks for Local Frappe

Create/update F:\Dropbox\Projects\bei-tasks\.env.development.local:

env
1# Local Development Environment
2NEXT_PUBLIC_FRAPPE_URL=http://localhost:8000
3
4# Local Frappe API credentials (from step 2)
5FRAPPE_API_KEY=your-api-key
6FRAPPE_API_SECRET=your-api-secret
7
8# App Configuration
9NEXT_PUBLIC_APP_NAME=BEI Tasks (LOCAL)

4. Start Local bei-tasks

bash
1cd F:\Dropbox\Projects\bei-tasks
2npm run dev
3# Frontend runs at http://localhost:3000

5. Test the Connection

bash
1# Test Frappe API directly
2curl -H "Authorization: token api-key:api-secret" \
3  "http://localhost:8000/api/method/hrms.api.onboarding.get_session?token=test"
4
5# Expected: {"message":{"success":false,"error":"Session not found",...}}

Local Development Stack

Syncing Code Changes

bash
1# After editing hrms/api/*.py files:
2cd F:\Dropbox\Projects\BEI-ERP\docker-dev
3
4# Sync files and clear cache
5powershell -Command "docker exec frappe-dev bash -c 'cp -f /bei-api/*.py /workspace/frappe-bench/apps/hrms/hrms/api/ && cd /workspace/frappe-bench && bench --site dev.localhost clear-cache'"
6
7# If whitelist decorators changed, restart Frappe
8powershell -Command "docker restart frappe-dev"

Important Notes

1. Authentication Required: Local APIs need authentication (no allow_guest=True)
2. Session Cookie OR Token Auth: Use either method for local testing
3. Different Site: Local uses dev.localhost, production uses hq.bebang.ph
4. No Test Data: Local DB is empty - create test data as needed

Related Skills

• /deploy-frappe - Production deployment (ONLY after local testing)
• /frappe-sql-bulk - Bulk data operations
• /frappe-doctype - DocType development

Production Testing Infrastructure (Added 2026-01-23)

CRITICAL: Database Architecture Discovery

The Frappe system at hq.bebang.ph uses a LOCAL Docker database via Docker Swarm (migrated 2026-01-29).

Note: Production now uses Docker Swarm (9 services). Container names changed from frappe_docker-backend-1 to dynamic names under frappe_backend.1.xxxx.

Common Mistake: AWS SSM commands often connect to the RDS database (frappe-hrms-db.ctmwomgscn66.ap-southeast-1.rds.amazonaws.com), but the live Frappe instance uses the local Docker database. This causes "no employees found" issues when testing.

Production Test Accounts

Inserting Test Data into Production

bash
1# 1. Get AWS credentials
2export AWS_ACCESS_KEY_ID=$(doppler secrets get AWS_ACCESS_KEY_ID --project bei-erp --config dev --plain)
3export AWS_SECRET_ACCESS_KEY=$(doppler secrets get AWS_SECRET_ACCESS_KEY --project bei-erp --config dev --plain)
4export AWS_DEFAULT_REGION=ap-southeast-1
5
6# 2. Run SQL on the CORRECT database (via Swarm backend container)
7aws ssm send-command \
8  --instance-ids "i-026b7477d27bd46d6" \
9  --document-name "AWS-RunShellScript" \
10  --parameters 'commands=[
11    "docker exec $(docker ps -qf name=frappe_backend) bench --site hq.bebang.ph mariadb --execute \"INSERT INTO tabEmployee (name, employee_name, first_name, status, gender, date_of_birth, date_of_joining, company, user_id, creation, modified, owner, modified_by) VALUES ('TEST-STAFF-001', 'Test Staff', 'Test', 'Active', 'Male', '1990-01-01', '2024-01-01', 'Bebang Enterprise Inc.', 'test.staff@bebang.ph', NOW(), NOW(), 'Administrator', 'Administrator');\""
12  ]'
13
14# 3. Verify
15aws ssm send-command \
16  --instance-ids "i-026b7477d27bd46d6" \
17  --document-name "AWS-RunShellScript" \
18  --parameters 'commands=[
19    "docker exec $(docker ps -qf name=frappe_backend) bench --site hq.bebang.ph mariadb --execute \"SELECT name, employee_name, user_id FROM tabEmployee WHERE name LIKE 'TEST-%';\""
20  ]'

API Credentials for bei-tasks

IMPORTANT: HR API routes use token auth (not session cookies) for Employee lookups because regular Frappe users don't have Employee read permission.

Verifying API Connection

bash
1# Test from production
2curl -X POST https://hq.bebang.ph/api/resource/Employee \
3  -H "Authorization: token 4a17c23aca83560:38ecc0e1054b1d2" \
4  -H "Content-Type: application/json" \
5  -d '{"filters": [["user_id", "=", "test.staff@bebang.ph"]]}'
6
7# Expected: Returns employee record

Troubleshooting Production Tests

1. "No employee found" but employee exists:

   • Check you're querying the Docker database, not RDS
   • Use bench --site hq.bebang.ph mariadb not direct RDS connection

2. API returns 401:

   • Verify Vercel env vars match Doppler
   • Redeploy after env var changes

3. Container not found:

   • Production now uses Docker Swarm (migrated 2026-01-29)
   • Service names: frappe_backend, frappe_frontend, etc.
   • Container names are dynamic: frappe_backend.1.xxxxx
   • Use docker service ls to verify services
   • Use docker ps -qf name=frappe_backend to get container ID

4. HR pages show "Failed to get employee data":

   • HR APIs need token auth, not session auth
   • Check app/api/hr/*/route.ts uses Authorization: token header

5. Code deployed but changes not visible:

   • Docker build caching issue - use no_cache=true when deploying
   • See /deploy-frappe for details on when to use no_cache
   • Verify with: curl https://hq.bebang.ph/api/method/hrms.api.hello.hello
   • Response should include build_version field showing deployment timestamp

Deployment Verification Endpoint

The hello API includes deployment info for verification:

bash
1curl -s https://hq.bebang.ph/api/method/hrms.api.hello.hello | python -m json.tool

Expected response:

json
1{
2    "message": {
3        "message": "Hello from Frappe HRMS!",
4        "timestamp": "2026-01-29 10:04:11.569399",
5        "build_version": "2026-01-29T12:16:00+08:00",
6        "deployment": "docker-swarm"
7    }
8}

If build_version doesn't update after deployment, rebuild with no_cache=true.