chore: add human-readable deployment docs to README.md
This commit is contained in:
root
parent
3f46886310
commit
b6103cbb01
2 changed files with 104 additions and 14 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Service Factory — ERPNext Custom App Project
|
||||
|
||||
> **Current Version: V0.1.0009** — Each completed prompt/step increments the patch number by 1 (V0.1.0000 → V0.1.0001 → V0.1.0002…). The agent automatically commits and pushes after every step.
|
||||
> **Current Version: V0.1.0010** — Each completed prompt/step increments the patch number by 1 (V0.1.0000 → V0.1.0001 → V0.1.0002…). The agent automatically commits and pushes after every step.
|
||||
|
||||
## Project Overview
|
||||
|
||||
|
|
|
|||
116
README.md
116
README.md
|
|
@ -1,10 +1,65 @@
|
|||
### Service Factory
|
||||
# Service Factory
|
||||
|
||||
Professional Services Delivery & Capacity Management
|
||||
Professional Services Delivery & Capacity Management — a custom Frappe/ERPNext app.
|
||||
|
||||
### Installation
|
||||
## Deployment Architecture
|
||||
|
||||
You can install this app using the [bench](https://github.com/frappe/bench) CLI:
|
||||
### Production Stack
|
||||
|
||||
```
|
||||
┌──────────────────────┐
|
||||
│ Zoraxy Proxy │
|
||||
│ (SSL termination) │
|
||||
│ Port 443 → 8000 │
|
||||
│ /socket.io → :9000 │
|
||||
│ WebSocket passthrough │
|
||||
└──────┬───────────────┘
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ Nginx (8000+8080) │
|
||||
│ │
|
||||
│ /assets/ → filesystem │
|
||||
│ /socket.io → :9000 │
|
||||
│ /* → gunicorn :8001 │
|
||||
└───────┬──────────┬────┘
|
||||
│ │
|
||||
┌───────┴──┐ ┌────┴────────┐
|
||||
│ Gunicorn │ │ Socket.IO │
|
||||
│ :8001 │ │ Node.js :9000│
|
||||
└──────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
### Key Configuration
|
||||
|
||||
| Component | Setting | Notes |
|
||||
|-----------|---------|-------|
|
||||
| **Zoraxy** | WebSocket passthrough: **enabled** | Required for real-time updates |
|
||||
| **Zoraxy** | Virtual directory: `/socket.io` → `http://172.16.8.20:9000/socket.io` | Routes WebSocket directly to socket.io server |
|
||||
| **Nginx** | `/assets/` served directly from filesystem | Bypasses gunicorn — essential for correct CSS/JS MIME types behind proxies |
|
||||
| **Nginx** | `proxy_set_header Host erp.lohmar.co.uk` | Set for socket.io location to pass origin checks |
|
||||
| **Socket.io** | Origin check **disabled** in `authenticate.js` | Socket.io's built-in CORS handles security; middleware check breaks behind proxies |
|
||||
|
||||
### Services
|
||||
|
||||
| Service | Port | Description |
|
||||
|---------|------|-------------|
|
||||
| `frappe-bench-web.service` | 8001 | Gunicorn (Frappe web app) — behind nginx |
|
||||
| `frappe-bench-worker.service` | — | Background async worker |
|
||||
| `frappe-bench-schedule.service` | — | Scheduled job runner |
|
||||
| `frappe-bench-socketio.service` | 9000 | Realtime WebSocket (Node.js) |
|
||||
| `frappe-bench-watch.service` | — | File watcher for dev/assets |
|
||||
|
||||
### Ports
|
||||
|
||||
| Port | Purpose |
|
||||
|------|---------|
|
||||
| 443 | Zoraxy HTTPS → nginx :8000 |
|
||||
| 8080 | Nginx direct (no SSL, for testing) |
|
||||
| 8000 | Nginx (Zoraxy target) |
|
||||
| 8001 | Gunicorn (behind nginx) |
|
||||
| 9000 | Socket.io Node.js server |
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
cd $PATH_TO_YOUR_BENCH
|
||||
|
|
@ -12,22 +67,57 @@ bench get-app $URL_OF_THIS_REPO --branch version-16
|
|||
bench install-app service_factory
|
||||
```
|
||||
|
||||
### Contributing
|
||||
### Post-Install
|
||||
|
||||
This app uses `pre-commit` for code formatting and linting. Please [install pre-commit](https://pre-commit.com/#installation) and enable it for this repository:
|
||||
1. Create Zoraxy virtual directory: `/socket.io` → `http://[server-ip]:9000/socket.io` with WebSocket passthrough enabled
|
||||
2. Configure nginx to serve `/assets/` directly (see nginx config in `deploy/`)
|
||||
3. If behind a reverse proxy, disable the socket.io origin check in `frappe/realtime/middlewares/authenticate.js`
|
||||
|
||||
## DocTypes
|
||||
|
||||
### Engagement Card (the core)
|
||||
|
||||
The primary work tracking DocType with:
|
||||
- **Assignments** — Multi-person team allocation
|
||||
- **Activity Log** — Timestamped comments, milestones, notes
|
||||
- **Time Log** — Per-employee hours tracking
|
||||
- **Subtasks** — Delegatable breakdown items
|
||||
|
||||
Card types: SE (Sales Engineering), PS (Professional Services), MS (Managed Services), Support
|
||||
|
||||
### Status Flow
|
||||
```
|
||||
Discovery → Delivery → Complete → Archived
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Prerequisites
|
||||
- Python ≥3.14
|
||||
- Node.js/Bun
|
||||
- pre-commit
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
cd apps/service_factory
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
Pre-commit is configured to use the following tools for checking and formatting your code:
|
||||
Pre-commit runs ruff, eslint, prettier, and pyupgrade on commit.
|
||||
|
||||
- ruff
|
||||
- eslint
|
||||
- prettier
|
||||
- pyupgrade
|
||||
### Agent Workflow
|
||||
|
||||
### License
|
||||
This project uses OpenAgentsControl. The agent operates in two modes:
|
||||
- **🗣️ Discuss** — Architecture, design, questions (no execution)
|
||||
- **🔧 Build** — Execute agreed plans (write, deploy, commit)
|
||||
|
||||
mit
|
||||
### Versioning
|
||||
|
||||
Format: `V{major}.{minor}.{patch}` (e.g., `V0.1.0009`)
|
||||
- Patch auto-increments on every git push
|
||||
- Agent commits and pushes after every completed step
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
|
|
|||
Loading…
Reference in a new issue