realtimex-frappe 0.5.0

CLI tool for streamlined Frappe/ERPNext site setup with PostgreSQL and bundled binaries support

Realtimex Frappe

Run Frappe/ERPNext with PostgreSQL, schema-based isolation, and external Redis.

---

Quick Start

You have a PostgreSQL database ready. Here's what to do:

Step 1: Admin Setup (Once)

Run this once on any machine to initialize the database and install apps:

RealTimeX Local App JSON:

{
  "command": "uvx",
  "args": ["realtimex-frappe", "setup"],
  "env": {
    "REALTIMEX_MODE": "admin",
    "REALTIMEX_SITE_NAME": "mysite.localhost",
    "REALTIMEX_SITE_PASSWORD": "admin",
    "REALTIMEX_DB_HOST": "db.xxxx.supabase.co",
    "REALTIMEX_DB_PORT": "5432",
    "REALTIMEX_DB_NAME": "postgres",
    "REALTIMEX_DB_SCHEMA": "mysite_schema",
    "REALTIMEX_DB_USER": "mysite_schema",
    "REALTIMEX_DB_PASSWORD": "your_site_password",
    "REALTIMEX_ADMIN_DB_USER": "postgres",
    "REALTIMEX_ADMIN_DB_PASSWORD": "your_admin_password"
  },
  "port": 8000
}

Or via command line:

export REALTIMEX_MODE=admin
export REALTIMEX_SITE_NAME=mysite.localhost
export REALTIMEX_SITE_PASSWORD=admin
export REALTIMEX_DB_HOST=db.xxxx.supabase.co
export REALTIMEX_DB_PORT=5432
export REALTIMEX_DB_NAME=postgres
export REALTIMEX_DB_SCHEMA=mysite_schema
export REALTIMEX_DB_USER=mysite_schema
export REALTIMEX_DB_PASSWORD=your_site_password
export REALTIMEX_ADMIN_DB_USER=postgres
export REALTIMEX_ADMIN_DB_PASSWORD=your_admin_password

realtimex-frappe setup

What happens:

1. Creates the schema mysite_schema in your PostgreSQL database
2. Creates a database user mysite_schema (same name as schema)
3. Installs Frappe and ERPNext
4. Outputs credentials to share with your team

Step 2: User Mode (Run Anywhere)

Use the credentials output from admin setup to run on any machine:

RealTimeX Local App JSON (use values from admin setup output):

{
  "command": "uvx",
  "args": ["realtimex-frappe", "run"],
  "env": {
    "REALTIMEX_MODE": "user",
    "REALTIMEX_SITE_NAME": "mysite.localhost",
    "REALTIMEX_DB_HOST": "db.xxxx.supabase.co",
    "REALTIMEX_DB_PORT": "5432",
    "REALTIMEX_DB_NAME": "postgres",
    "REALTIMEX_DB_SCHEMA": "mysite_schema",
    "REALTIMEX_DB_USER": "mysite_schema",
    "REALTIMEX_DB_PASSWORD": "your_site_password"
  },
  "port": 8000
}

Or via command line (use values from admin setup output):

export REALTIMEX_MODE=user
export REALTIMEX_SITE_NAME=mysite.localhost
export REALTIMEX_DB_HOST=db.xxxx.supabase.co
export REALTIMEX_DB_PORT=5432
export REALTIMEX_DB_NAME=postgres
export REALTIMEX_DB_SCHEMA=mysite_schema
export REALTIMEX_DB_USER=mysite_schema
export REALTIMEX_DB_PASSWORD=your_site_password

realtimex-frappe run

What happens:

1. Downloads apps locally (if not already present)
2. Creates local site configuration pointing to remote database
3. Starts the Frappe server

Result: Your site is available at http://mysite.localhost:8000

---

Understanding the Two Modes

	Admin Mode	User Mode
Purpose	Initialize database and install apps	Run the server
Command	realtimex-frappe setup	realtimex-frappe run
When	Once, by the project admin	Anytime, by any team member
Requires	Admin database credentials	Shared credentials from admin
Creates	Schema, tables, initial data	Local config only

Workflow:

1. Admin runs setup once → creates database schema and installs apps
2. Admin shares the output credentials with team
3. Team members copy those credentials and run run

---

Environment Variables

Required for Both Modes

Variable	Description
REALTIMEX_MODE	admin or user
REALTIMEX_SITE_NAME	Site name (e.g., mysite.localhost)
REALTIMEX_DB_HOST	PostgreSQL host
REALTIMEX_DB_PORT	PostgreSQL port (default: 5432)
REALTIMEX_DB_NAME	Database name (e.g., postgres for Supabase)
REALTIMEX_DB_SCHEMA	Schema name (e.g., mysite_schema)
REALTIMEX_DB_USER	Site database user (created by admin setup)
REALTIMEX_DB_PASSWORD	Site database password

Required for Admin Mode Only

Variable	Description
REALTIMEX_SITE_PASSWORD	Frappe administrator password
REALTIMEX_ADMIN_DB_USER	Root database user (e.g., postgres)
REALTIMEX_ADMIN_DB_PASSWORD	Root database password

Optional

Variable	Default	Description
REALTIMEX_PORT	8000	Webserver port
REALTIMEX_REDIS_HOST	127.0.0.1	Redis host
REALTIMEX_REDIS_CACHE_PORT	13001	Redis cache port
REALTIMEX_REDIS_QUEUE_PORT	11001	Redis queue port
REALTIMEX_BENCH_PATH	~/.realtimex.ai/storage/local-apps/frappe-bench	Installation path
REALTIMEX_FORCE_REINSTALL	false	Delete and reinstall (for recovery)

Run realtimex-frappe env-help for the complete list.

---

Commands

Command	Description
setup	Admin mode: create database, install apps, output credentials
run	User mode: start the server (auto-setup local config if needed)
env-help	Show all environment variables
validate	Check if prerequisites are installed

---

Prerequisites

macOS

Prerequisite	Check	Install
Git	git --version	brew install git
Node.js 18+	node --version	brew install node@18
npm	npm --version	(included with Node.js)
pkg-config	which pkg-config	brew install pkg-config
Redis	which redis-server	brew install redis && brew services start redis

wkhtmltopdf (macOS):

curl -L https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-2/wkhtmltox-0.12.6-2.macos-cocoa.pkg -O
sudo installer -pkg wkhtmltox-0.12.6-2.macos-cocoa.pkg -target /

Linux

# System dependencies
sudo apt update && sudo apt install git pkg-config curl

# Redis
sudo apt install redis-server && sudo systemctl enable --now redis-server

# Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs

# wkhtmltopdf and dependencies
sudo apt install xvfb libfontconfig wkhtmltopdf

---

Storage

All data is stored at:

~/.realtimex.ai/storage/local-apps/frappe-bench/

This persists across restarts and is independent of your working directory.

---

Security Model

Schema-based isolation provides security boundaries:

What the site user CAN do	What the site user CANNOT do
All operations within their schema	Access other schemas
CREATE/ALTER/DROP tables in schema	DROP the schema itself
Run migrations, install apps	Create new schemas

The admin user (postgres) owns the schema; the site user operates within it.

---

License

MIT