frappe-ops-app-lifecycle

# App Lifecycle Management

## Quick Reference

| Command | Purpose | When to Use |
|---|---|---|
| `bench new-app` | Scaffold new app | Starting a new project |
| `bench get-app URL` | Clone from Git | Installing existing app |
| `bench --site SITE install-app` | Install on site | After get-app or new-app |
| `bench --site SITE remove-app` | Uninstall from site | Removing app from site |
| `bench remove-app` | Remove from bench | Removing app entirely |
| `bench --site SITE migrate` | Run patches + sync | After code changes |
| `bench build` | Compile assets | After JS/CSS changes |
| `bench --site SITE console` | Python REPL | Debugging |
| `bench start` | Start dev server | Development |
| `bench setup production` | Configure nginx+supervisor | Deploying to production |

## 1. Scaffolding: bench new-app

```bash
bench new-app my_custom_app
```

Interactive prompts:
- App Title → Human-readable name
- App Description → One-line summary
- App Publisher → Company/author name
- App Email → Contact email
- App Icon → Default: `octicon octicon-file-directory`
- App Color → Default: `grey`
- App License → Default: `MIT`

### Generated Directory Structure

```
apps/my_custom_app/
├── MANIFEST.in              # Files included in Python package
├── README.md                # Project readme
├── license.txt              # License file
├── requirements.txt         # Python dependencies
├── dev-requirements.txt     # Dev-only Python deps (v15+)
├── package.json             # Node.js dependencies
├── setup.py                 # Python package config (v14)
├── pyproject.toml           # Python package config (v15+)
├── my_custom_app/
│   ├── __init__.py          # App version string
│   ├── hooks.py             # Framework integration hooks
│   ├── modules.txt          # List of app modules
│   ├── patches.txt          # Migration patches list
│   ├── config/
│   │   ├── __init__.py
│   │   ├── desktop.py       # Desktop/workspace config
│   │   └── docs.py          # Documentation config
│   ├── public/              # Static assets → /assets/my_custom_app/
│   │   ├── css/
│   │   └── js/
│   ├── templates/           # Jinja templates
│   └── www/                 # Portal pages (URL = path)
```

### What Each Core File Does

| File | Purpose | NEVER Forget |
|---|---|---|
| `__init__.py` | Defines `__version__` | ALWAYS update before release |
| `hooks.py` | ALL framework integration | Entry point for everything |
| `modules.txt` | Declares app modules | ALWAYS add new modules here |
| `patches.txt` | Migration patch registry | ALWAYS add patches in order |
| `requirements.txt` | Python deps installed on setup | Add pip packages here |
| `public/` | Static files served by nginx | Accessible at `/assets/app_name/` |
| `www/` | Portal pages | Filename = URL path |

## 2. Development Cycle

```
Code → Migrate → Build → Test → Commit
```

### Step-by-Step

```bash
# 1. Make code changes (DocTypes, reports, APIs, etc.)

# 2. Migrate — sync DocType schema + run patches
bench --site mysite migrate

# 3. Build — compile JS/CSS assets
bench build --app my_custom_app

# 4. Test — run Python tests
bench --site mysite run-tests --app my_custom_app

# 5. Commit
git -C apps/my_custom_app add -A && git -C apps/my_custom_app commit -m "feat: add feature"
```

ALWAYS run `bench migrate` after modifying DocType JSON files.
ALWAYS run `bench build` after modifying JS/CSS files.

## 3. Getting Apps from Git

```bash
# Public repo
bench get-app https://github.com/org/my_app

# Specific branch
bench get-app https://github.com/org/my_app --branch develop

# Private repo via SSH
bench get-app git@github.com:org/private_app.git

# Private repo via token (v15+)
bench get-app https://TOKEN@github.com/org/private_app.git
```

After `get-app`, ALWAYS install on the target site:
```bash
bench --site mysite install-app my_app
```

`get-app` clones to `apps/` and adds to `apps.txt`.
`install-app` creates database tables and runs `after_install` hooks.

## 4. Installing and Removing Apps

### Installation Order Matters
Apps are installed in order listed in `apps.txt`. If App B depends on App A, App A MUST be listed first.

```bash
# Install
bench --site mysite install-app my_app

# Verify
bench --site mysite list-apps
# Output: frappe, erpnext, my_app

# Remove from site (keeps code in apps/)
bench --site mysite remove-app my_app

# Remove from bench entirely (deletes code)
bench remove-app my_app
```

### App Dependencies (v14+)
Declare in `hooks.py`:
```python
required_apps = ["frappe", "erpnext"]
```

Frappe ALWAYS checks `required_apps` during installation and blocks if dependencies are missing.

## 5. Debugging with bench console

```bash
bench --site mysite console
```

Opens an IPython REPL with Frappe context:

```python
# Query data
frappe.db.sql("SELECT name, status FROM `tabSales Invoice` LIMIT 5", as_dict=True)

# Get a document
doc = frappe.get_doc("Sales Invoice", "SINV-00001")
print(doc.grand_total)

# Test a whitelisted method
from my_app.api import my_function
result = my_function(param="value")

# Check configuration
frappe.get_site_config()

# Auto-reload on code changes (v15+)
# Start with: bench --site mysite console --autoreload
```

ALWAYS use `bench console` for debugging — NEVER modify production data with raw SQL.

## 6. Development Mode vs Production Mode

### Development Mode
```bash
# Enable
bench set-config -g developer_mode 1

# Start dev server (Procfile: web + worker + redis + socketio)
bench start
```

Development mode enables:
- DocType editing in Desk
- "Is Standard" option for reports/scripts
- Auto-reload on Python file changes
- Detailed error tracebacks in browser
- `dev-requirements.txt` dependencies installed

### Production Mode
```bash
# Disable developer mode
bench set-config -g developer_mode 0

# Setup production (nginx + supervisor)
sudo bench setup production USERNAME

# Restart
sudo supervisorctl restart all
# or
sudo systemctl restart supervisor
```

Production mode:
- Serves via n