frappe-cli 0.1.12

Professional CLI for Frappe deployment and management.

Frappe Installer CLI

A professional-grade, modular, and extensible command-line tool to automate Frappe deployment and server management on Ubuntu-based servers. Built with Python, Click, and best practices for production and developer workflows.

---

🚀 Overview

Frappe Installer CLI is a professional-grade, production-ready Python CLI for managing Frappe and ERPNext deployments. It provides a modern, developer-friendly alternative to Bash scripts, with:

• Consistent, colored output and progress bars (Rich/Click)
• Professional error handling and actionable messages
• Modular command groups for all aspects of Frappe/ERPNext management
• Automated backups, SSL, firewall, and security hardening
• Robust logging with log level control
• Automated tests and continuous integration for code quality

---

✨ Key Features

• Step-by-step or full-stack install
• Config-driven: YAML/JSON config for reproducible, production-safe installs
• Multi-tenancy: Manage multiple sites and apps
• Automated backups: External HD, cron, email alerts
• SSL/HTTPS: Certbot with auto-renewal
• Firewall/UFW: Secure defaults, custom ports
• Service management: Restart, status, logs
• Security: Fail2Ban, SSH hardening, log rotation
• Extensible: Modular command groups, easy to add features
• Rich logging: All actions logged to /var/log/frappe-installer.log
• Professional error handling: All user errors are clear and actionable
• Automated testing: Pytest and Click CLI runner for all commands
• CI/CD: Linting, formatting, and tests run on every push/PR (GitHub Actions)

---

🧱 Architecture & Developer Experience

• Click: CLI framework
• Rich: Colored output, progress bars, and prompts
• Subprocess: Executes system commands (apt, pip, nginx, etc.)
• YAML/JSON: Configurable install/runtime settings
• Logging: /var/log/frappe-installer.log (with logrotate)
• Modular codebase: Each command group in its own file/module
• Automated tests: All major commands and error cases covered
• Code quality automation: Black, flake8, isort, and CI pipeline

---

🧪 Automated Testing & Quality

• All commands are tested using pytest and click.testing.CliRunner
• Linting and formatting enforced with flake8, black, and isort
• GitHub Actions workflow runs tests and code checks on every PR
• See requirements-dev.txt for development dependencies

---

🛠️ Usage

frappe --help
frappe site create --help
frappe app clone --help
frappe backup setup --help
# ...and more

All commands support --help with examples. Use --debug and --dry-run for safe experimentation.

---

🤝 Contributing

• Keep commands modular (one file/module per group)
• Add new tests in tests/ using pytest and click.testing.CliRunner
• Run black, flake8, and isort before PRs
• See CONTRIBUTING.md for more guidelines (coming soon)

---

📦 Installation

Requirements

• Python ≥ 3.10
• Ubuntu 22.04/24.04 (Debian variants: partial support)
• pipx (optional, for global CLI install)

Quick Start (Dev)

# Clone the repo
cd frappe-installer/frappe_cli
python3 -m venv venv
source venv/bin/activate
pip install --editable .
frappe --help

Quick Start (Production)

pipx install git+https://github.com/your/repo
frappe --help

---

🧩 Command Structure

frappe <group> <action> [options]

Core Command Groups

Group	Description
install	Full or step-by-step system setup
site	Site creation, listing, backup
service	Restart, view status, logs
ssl	HTTPS via Certbot
firewall	UFW/iptables config
backup	Manual + scheduled backups
app	Install/Update/Remove Frappe apps
config	Config set/get/validate
monitor	Live logs and system health
optimize	Performance tuning
rollback	Backup restore or stage rollback
logrotate	Log rotation management

---

🧪 Usage Examples

Full Install (with config)

frappe install system --config production.yaml
frappe install user --config production.yaml
frappe install deps --config production.yaml
frappe install mariadb --config production.yaml
frappe install bench --config production.yaml
frappe install init --config production.yaml
frappe install prod --config production.yaml

Create a Site

frappe site create --bench-name frappe-bench --site-name example.com --mariadb-root-password rootpass --admin-password admin123

SSL Setup

frappe ssl setup --site-name example.com --email [e-mail]

Backup Setup

frappe backup setup --admin-email [e-mail] --bench-name frappe-bench --site-name example.com

Service Management

frappe service restart
frappe service status --bench-name frappe-bench --site-name example.com

Firewall

frappe firewall setup

App Management

frappe app clone --bench-name frappe-bench --repo-url https://github.com/your/app.git --branch main

Rollback/Uninstall

frappe rollback uninstall --bench-name frappe-bench --site-name example.com

Log Rotation

frappe logrotate setup

---

🛠️ Config File Usage

• Place your config in YAML (see data/example_config.yaml).
• Pass --config production.yaml to any command for reproducible, non-interactive installs.

Example:

system:
  timezone: "Africa/Dar_es_Salaam"
  locale: "en_US.UTF-8"
  user: "frappe"
frappe:
  branch: "version-15"
  bench_name: "frappe-bench"
  site_name: "example.com"
  admin_password: "changeme"
  mariadb_root_password: "rootpass"
services:
  enable_ssl: true
  enable_ufw: true
backup:
  admin_email: "[e-mail]"
  external_hd_uuid: ""
  retention_days: 7
## 📝 License

This project is licensed under the [MIT License](LICENSE).

---

## 🛡️ Server Management Best Practices
- Timezone and locale configuration
- Dedicated `frappe` user
- Automatic UFW (firewall) setup
- Fail2Ban setup (optional)
- SSH hardening (optional)
- Certbot HTTPS auto-renewal
- Systemd + Supervisor integration
- Log rotation

---

## 🧠 Advanced/Extensible
- **Multi-tenancy:** `site list`, `site backup`, `site restore`
- **Monitoring:** `monitor logs`, `monitor health` (stubs for future)
- **Performance:** `optimize performance` (stub)
- **Config management:** `config set/get/validate` (stubs)

---

## 🐞 Troubleshooting
- All actions are logged to `/var/log/frappe-installer.log` (or local fallback)
- Use `frappe service status` to check system health
- Use `frappe logrotate setup` to prevent log bloat
- For permission issues, ensure you run as a sudo-capable user

---

## 🤝 Contributing

1. Fork the repo and create a feature branch
2. Add or improve a command group/module
3. Write clear commit messages and update the README if needed
4. Submit a pull request with a clear description

---

## 📄 License
MIT (or your preferred license)