/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

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

Volumes

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:

   bashCopy

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

2. Push to production branch:

   bashCopy

   git push origin production
   

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

4. Verify production:

   bashCopy

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

   Copy

   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:

   pythonCopy

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

3. Sync to container:

   bashCopy

   dev.bat sync
   

4. Test locally:

   bashCopy

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

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, 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

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

# 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

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 doesn't update after deployment, rebuild with no_cache=true.