Metadata-Version: 2.4
Name: realtimex-frappe
Version: 0.4.0
Summary: CLI tool for streamlined Frappe/ERPNext site setup with PostgreSQL and bundled binaries support
Author: Realtimex
License: MIT
Keywords: bench,cli,erpnext,frappe,setup
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: frappe-bench>=5.28.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Realtimex Frappe

A CLI tool to set up Frappe/ERPNext sites with PostgreSQL, external Redis, and bundled binaries.

**Platforms:** macOS, Linux

---

## 🚀 Quick Setup for RealTimeX Local App

> [!IMPORTANT]
> **Follow this section to run Frappe inside the RealTimeX Local App environment.**

### Step 1: Install Prerequisites

| Prerequisite | Check Command | macOS Install | RealTimeX App |
|--------------|---------------|---------------|:-------------:|
| **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` | - |
| **wkhtmltopdf** | `wkhtmltopdf --version` | See below | - |
| **Redis** | `which redis-server` | `brew install redis && brew services start redis` | - |
| **psql** | `psql --version` | `brew install postgresql@15` | - |

> [!NOTE]
> ✅ = Bundled with RealTimeX App (no manual installation required)

**wkhtmltopdf (macOS):**
```bash
curl -L https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6-2/wkhtmltox-0.12.6-2.macos-cocoa.pkg -O
installer -pkg wkhtmltox-0.12.6-2.macos-cocoa.pkg -target ~
# If permission denied, use: sudo installer -pkg wkhtmltox-0.12.6-2.macos-cocoa.pkg -target /
```

> [!TIP]
> **Using a remote database?** Skip PostgreSQL installation and configure `REALTIMEX_DB_HOST` to point to your remote server (e.g., Supabase).

**For local PostgreSQL:**
```bash
brew install postgresql@15 && brew services start postgresql@15
```

### Step 2: Configure RealTimeX App

Add this to your RealTimeX Local App configuration:

```json
{
  "command": "uvx",
  "args": ["realtimex-frappe", "run"],
  "env": {
    "REALTIMEX_SITE_NAME": "mysite.localhost",
    "REALTIMEX_ADMIN_PASSWORD": "admin",
    "REALTIMEX_DB_NAME": "frappe_mysite",
    "REALTIMEX_DB_USER": "postgres",
    "REALTIMEX_DB_PASSWORD": "postgres"
  },
  "working_dir": "",
  "port": 8000
}
```

**For Supabase (schema-based isolation):**
```json
{
  "command": "uvx",
  "args": ["realtimex-frappe", "run"],
  "env": {
    "REALTIMEX_SITE_NAME": "mysite.localhost",
    "REALTIMEX_ADMIN_PASSWORD": "admin",
    "REALTIMEX_DB_NAME": "postgres",
    "REALTIMEX_DB_USER": "postgres.xxxx",
    "REALTIMEX_DB_PASSWORD": "your-password",
    "REALTIMEX_DB_HOST": "db.xxxx.supabase.co",
    "REALTIMEX_DB_PORT": "5432",
    "REALTIMEX_DB_SCHEMA": "frappe_mysite"
  },
  "working_dir": "",
  "port": 8000
}
```

### Step 3: Run

**Option A: Via RealTimeX App**

Simply start the app through the RealTimeX interface. The JSON configuration above handles all environment variables automatically.

**Option B: Direct Command Line**

Set environment variables and run manually:

```bash
export REALTIMEX_SITE_NAME=mysite.localhost
export REALTIMEX_ADMIN_PASSWORD=admin
export REALTIMEX_DB_NAME=frappe_mysite
export REALTIMEX_DB_USER=postgres
export REALTIMEX_DB_PASSWORD=postgres

# For remote database, also set:
# export REALTIMEX_DB_HOST=db.xxxx.supabase.co

uvx realtimex-frappe run
```

---

**Result:** Your site will be available at **http://mysite.localhost:8000**

---

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `REALTIMEX_SITE_NAME` | ✅ | - | Site name (e.g., `mysite.localhost`) |
| `REALTIMEX_ADMIN_PASSWORD` | ✅ | - | Admin password |
| `REALTIMEX_DB_NAME` | ✅ | - | Database name to create or connect to |
| `REALTIMEX_DB_USER` | ✅ | - | PostgreSQL username (root credentials for setup) |
| `REALTIMEX_DB_PASSWORD` | ✅ | - | PostgreSQL password |
| `REALTIMEX_DB_SCHEMA` | - | - | PostgreSQL schema name (enables schema mode) |
| `REALTIMEX_NODE_BIN_DIR` | ⚠️ | - | Path to Node.js bin directory |
| `REALTIMEX_DB_HOST` | - | `localhost` | PostgreSQL host |
| `REALTIMEX_DB_PORT` | - | `5432` | PostgreSQL port |
| `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` | Bench installation path |

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

---

## ⚠️ Database Configuration

### Traditional Mode (Default)

When `REALTIMEX_DB_SCHEMA` is **not set**, Frappe creates a new database:

```bash
# ✅ Creates database "frappe_mysite" owned by user "frappe_mysite"
REALTIMEX_DB_NAME="frappe_mysite"
REALTIMEX_DB_USER="postgres"        # Root user for setup
REALTIMEX_DB_PASSWORD="postgres"
```

> [!CAUTION]
> **`REALTIMEX_DB_NAME` controls which database Frappe will CREATE.** Use unique names.
> **Never use `REALTIMEX_DB_NAME="postgres"` without `REALTIMEX_DB_SCHEMA` otherwise Frappe will drop the `postgres` database.**

### Schema Mode (For Supabase)

When `REALTIMEX_DB_SCHEMA` is **set**, Frappe creates a schema within an existing database:

```bash
# ✅ Creates schema "frappe_mysite" in the "postgres" database
REALTIMEX_DB_NAME="postgres"        # Existing database (Supabase default)
REALTIMEX_DB_USER="postgres.xxxx"   # Your Supabase user
REALTIMEX_DB_PASSWORD="your-password"
REALTIMEX_DB_SCHEMA="frappe_mysite" # Schema to create
```

**Schema mode behavior:**
- Creates user named after `db_schema` (e.g., `frappe_mysite`)
- Creates schema owned by this user
- Grants Supabase roles (`anon`, `authenticated`, `service_role`) if they exist
- Sets `search_path` automatically on all connections

> [!TIP]
> Schema mode is ideal for Supabase because it uses the existing `postgres` database and enables Supabase features like Realtime and Edge Functions.

---

## Port Configuration

Control all ports via environment variables:

| Service | Variable | Default |
|---------|----------|---------|
| Webserver | `REALTIMEX_PORT` | `8000` |
| Redis Cache | `REALTIMEX_REDIS_CACHE_PORT` | `13001` |
| Redis Queue | `REALTIMEX_REDIS_QUEUE_PORT` | `11001` |

**Example with custom ports:**
```bash
export REALTIMEX_PORT=3000
export REALTIMEX_REDIS_CACHE_PORT=13002
export REALTIMEX_REDIS_QUEUE_PORT=11002
uvx realtimex-frappe run
```

---

## Storage Location

Bench data is stored persistently at:

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

This location persists across restarts and is independent of the working directory.

---

## Linux Setup

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

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

# PostgreSQL (skip if using remote database)
sudo apt install postgresql postgresql-contrib && sudo systemctl enable --now postgresql

# PostgreSQL client
sudo apt install postgresql-client

# wkhtmltopdf dependencies
sudo apt install xvfb libfontconfig

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

---

## Commands

| Command | Description |
|---------|-------------|
| `run` | Setup and start (production) |
| `env-help` | Show environment variables |
| `validate` | Check prerequisites |

---

## Requirements

- Python 3.11+
- Node.js 18+
- Redis 6+
- PostgreSQL 13+ (local or remote)
- Git, pkg-config, wkhtmltopdf, psql

---

## License

MIT
