/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

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

Access

Login: Administrator / admin

Development Workflow

Standard Workflow (Edit → Sync → Test)

# 1. Edit your API file locally
#    Example: hrms/api/employee_clearance.py

# 2. Sync to container and clear cache
dev.bat sync

# 3. Test your API
curl http://localhost:8000/api/method/hrms.api.employee_clearance.get_status

# 4. When ready, commit and push to production
git add .
git commit -m "feat: Add employee clearance API"
git push origin production

Helper Commands

dev.bat start

dev.bat stop

dev.bat restart

dev.bat sync

dev.bat shell

dev.bat bench

dev.bat bench migrate

dev.bat logs

dev.bat test

dev.bat migrate

dev.bat status

dev.bat reset

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

# hrms/api/my_new_api.py
import frappe

@frappe.whitelist(allow_guest=True)
def hello():
    """Test endpoint."""
    return {"message": "Hello from my new API!"}

@frappe.whitelist()
def get_data():
    """Requires authentication."""
    return {"user": frappe.session.user}

2. Update init.py

# hrms/api/__init__.py
from hrms.api.my_new_api import (
    hello,
    get_data,
)

3. Sync and test

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

Container Configuration

frappe/bench:v5.25.11

/workspace/frappe-bench

/bei-api

hrms/api/

dev.localhost

Volumes

docker-dev_frappe-bench

docker-dev_mariadb-data

Note: Volumes persist data across container restarts. To completely reset, use

docker compose down -v

Troubleshooting

Container won't start

# Check logs
dev.bat logs

# Or directly
docker logs frappe-dev

API changes not visible

# Force sync and clear cache
dev.bat sync

# If still not working, restart Frappe
dev.bat restart

Database connection errors

# Check MariaDB is healthy
docker ps

# Should show mariadb-dev as (healthy)

Need fresh start

# WARNING: This deletes all data
dev.bat reset
# Or manually:
docker compose -f docker-dev/docker-compose.yml down -v
dev.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

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

With authentication

# Get session cookie first
curl -c cookies.txt -X POST http://localhost:8000/api/method/login \
  -d "usr=Administrator" -d "pwd=admin"

# Then use the cookie
curl -b cookies.txt http://localhost:8000/api/method/hrms.api.roster.get_roster

Using bench execute

# Run Python code directly
dev.bat bench execute hrms.api.hello.hello

# With arguments
dev.bat bench execute "hrms.api.employee_clearance.get_status" --args '["HR-EMP-0001"]'

When to Deploy to Production

After testing locally:

1. Commit changes:

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

2. Push to production branch:

   git push origin production
   

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

4. Verify production:

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

See

/deploy-frappe

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

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

Production prohibits

bench build

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

What This Means For You

bench build

bench migrate

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

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

   :

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

3. Sync to container:

   dev.bat sync
   

4. Test locally:

   # Check redirect
   curl -sI http://localhost:8000/login | grep -i location
   
   # Check page renders
   curl -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

gh 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

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

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

2. Generate API Keys (First Time Only)

# Login to get session cookie
curl -c cookies.txt -X POST "http://localhost:8000/api/method/login" \
  -d "usr=Administrator&pwd=admin"

# Generate API keys
curl -b cookies.txt -X POST \
  "http://localhost:8000/api/method/frappe.core.doctype.user.user.generate_keys?user=Administrator"
# 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

# Local Development Environment
NEXT_PUBLIC_FRAPPE_URL=http://localhost:8000

# Local Frappe API credentials (from step 2)
FRAPPE_API_KEY=your-api-key
FRAPPE_API_SECRET=your-api-secret

# App Configuration
NEXT_PUBLIC_APP_NAME=BEI Tasks (LOCAL)

4. Start Local bei-tasks

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

5. Test the Connection

# Test Frappe API directly
curl -H "Authorization: token api-key:api-secret" \
  "http://localhost:8000/api/method/hrms.api.onboarding.get_session?token=test"

# Expected: {"message":{"success":false,"error":"Session not found",...}}

Local Development Stack

Syncing Code Changes

# After editing hrms/api/*.py files:
cd F:\Dropbox\Projects\BEI-ERP\docker-dev

# Sync files and clear cache
powershell -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'"

# If whitelist decorators changed, restart Frappe
powershell -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

frappe_backend

frappe_db

frappe_frontend

frappe_websocket

frappe_queue-short

frappe_queue-long

frappe_scheduler

Note: Production now uses Docker Swarm (9 services). Container names changed from

frappe_docker-backend-1

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

Production Test Accounts

Inserting Test Data into Production

# 1. Get AWS credentials
export AWS_ACCESS_KEY_ID=$(doppler secrets get AWS_ACCESS_KEY_ID --project bei-erp --config dev --plain)
export AWS_SECRET_ACCESS_KEY=$(doppler secrets get AWS_SECRET_ACCESS_KEY --project bei-erp --config dev --plain)
export AWS_DEFAULT_REGION=ap-southeast-1

# 2. Run SQL on the CORRECT database (via Swarm backend container)
aws ssm send-command \
  --instance-ids "i-026b7477d27bd46d6" \
  --document-name "AWS-RunShellScript" \
  --parameters 'commands=[
    "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');\""
  ]'

# 3. Verify
aws ssm send-command \
  --instance-ids "i-026b7477d27bd46d6" \
  --document-name "AWS-RunShellScript" \
  --parameters 'commands=[
    "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-%';\""
  ]'

API Credentials for bei-tasks

4a17c23aca83560

38ecc0e1054b1d2

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

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

# 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:

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

Expected response:

{
    "message": {
        "message": "Hello from Frappe HRMS!",
        "timestamp": "2026-01-29 10:04:11.569399",
        "build_version": "2026-01-29T12:16:00+08:00",
        "deployment": "docker-swarm"
    }
}

If

build_version

no_cache=true