# Frappe Installer CLI
[](LICENSE)
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
```sh
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](https://pypa.github.io/pipx/) (optional, for global CLI install)
### Quick Start (Dev)
```bash
# Clone the repo
cd frappe-installer/frappe_cli
python3 -m venv venv
source venv/bin/activate
pip install --editable .
frappe --help
```
### Quick Start (Production)
```bash
pipx install git+https://github.com/your/repo
frappe --help
```
---
## ๐งฉ Command Structure
```bash
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)
```bash
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
```bash
frappe site create --bench-name frappe-bench --site-name example.com --mariadb-root-password rootpass --admin-password admin123
```
### SSL Setup
```bash
frappe ssl setup --site-name example.com --email admin@example.com
```
### Backup Setup
```bash
frappe backup setup --admin-email admin@example.com --bench-name frappe-bench --site-name example.com
```
### Service Management
```bash
frappe service restart
frappe service status --bench-name frappe-bench --site-name example.com
```
### Firewall
```bash
frappe firewall setup
```
### App Management
```bash
frappe app clone --bench-name frappe-bench --repo-url https://github.com/your/app.git --branch main
```
### Rollback/Uninstall
```bash
frappe rollback uninstall --bench-name frappe-bench --site-name example.com
```
### Log Rotation
```bash
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:**
```yaml
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: "admin@example.com"
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)
Raw data
{
"_id": null,
"home_page": "https://github.com/okama12/frappe-cli.git",
"name": "frappe-cli",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "frappe, cli, installer, deployment, management",
"author": "Rashidi Okama",
"author_email": "rashidokama@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1f/c8/45a9d182834b24312820075bc76b611f680ba5f3bea0dc03487237c54cc2/frappe_cli-0.1.2.tar.gz",
"platform": null,
"description": "# Frappe Installer CLI\n\n[](LICENSE)\n\nA 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.\n\n---\n\n## \ud83d\ude80 Overview\n\n**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:\n\n- Consistent, colored output and progress bars (Rich/Click)\n- Professional error handling and actionable messages\n- Modular command groups for all aspects of Frappe/ERPNext management\n- Automated backups, SSL, firewall, and security hardening\n- Robust logging with log level control\n- Automated tests and continuous integration for code quality\n\n---\n\n## \u2728 Key Features\n\n- **Step-by-step or full-stack install**\n- **Config-driven**: YAML/JSON config for reproducible, production-safe installs\n- **Multi-tenancy**: Manage multiple sites and apps\n- **Automated backups**: External HD, cron, email alerts\n- **SSL/HTTPS**: Certbot with auto-renewal\n- **Firewall/UFW**: Secure defaults, custom ports\n- **Service management**: Restart, status, logs\n- **Security**: Fail2Ban, SSH hardening, log rotation\n- **Extensible**: Modular command groups, easy to add features\n- **Rich logging**: All actions logged to `/var/log/frappe-installer.log`\n- **Professional error handling**: All user errors are clear and actionable\n- **Automated testing**: Pytest and Click CLI runner for all commands\n- **CI/CD**: Linting, formatting, and tests run on every push/PR (GitHub Actions)\n\n---\n\n## \ud83e\uddf1 Architecture & Developer Experience\n\n- **Click**: CLI framework\n- **Rich**: Colored output, progress bars, and prompts\n- **Subprocess**: Executes system commands (apt, pip, nginx, etc.)\n- **YAML/JSON**: Configurable install/runtime settings\n- **Logging**: `/var/log/frappe-installer.log` (with logrotate)\n- **Modular codebase**: Each command group in its own file/module\n- **Automated tests**: All major commands and error cases covered\n- **Code quality automation**: Black, flake8, isort, and CI pipeline\n\n---\n\n## \ud83e\uddea Automated Testing & Quality\n\n- All commands are tested using `pytest` and `click.testing.CliRunner`\n- Linting and formatting enforced with `flake8`, `black`, and `isort`\n- GitHub Actions workflow runs tests and code checks on every PR\n- See `requirements-dev.txt` for development dependencies\n\n---\n\n## \ud83d\udee0\ufe0f Usage\n\n```sh\nfrappe --help\nfrappe site create --help\nfrappe app clone --help\nfrappe backup setup --help\n# ...and more\n```\n\nAll commands support `--help` with examples. Use `--debug` and `--dry-run` for safe experimentation.\n\n---\n\n## \ud83e\udd1d Contributing\n\n- Keep commands modular (one file/module per group)\n- Add new tests in `tests/` using `pytest` and `click.testing.CliRunner`\n- Run `black`, `flake8`, and `isort` before PRs\n- See `CONTRIBUTING.md` for more guidelines (coming soon)\n\n---\n\n## \ud83d\udce6 Installation\n\n### Requirements\n- Python \u2265 3.10\n- Ubuntu 22.04/24.04 (Debian variants: partial support)\n- [pipx](https://pypa.github.io/pipx/) (optional, for global CLI install)\n\n### Quick Start (Dev)\n```bash\n# Clone the repo\ncd frappe-installer/frappe_cli\npython3 -m venv venv\nsource venv/bin/activate\npip install --editable .\nfrappe --help\n```\n\n### Quick Start (Production)\n```bash\npipx install git+https://github.com/your/repo\nfrappe --help\n```\n\n---\n\n## \ud83e\udde9 Command Structure\n\n```bash\nfrappe <group> <action> [options]\n```\n\n### Core Command Groups\n| Group | Description |\n| ---------- | --------------------------------- |\n| `install` | Full or step-by-step system setup |\n| `site` | Site creation, listing, backup |\n| `service` | Restart, view status, logs |\n| `ssl` | HTTPS via Certbot |\n| `firewall` | UFW/iptables config |\n| `backup` | Manual + scheduled backups |\n| `app` | Install/Update/Remove Frappe apps |\n| `config` | Config set/get/validate |\n| `monitor` | Live logs and system health |\n| `optimize` | Performance tuning |\n| `rollback` | Backup restore or stage rollback |\n| `logrotate`| Log rotation management |\n\n---\n\n## \ud83e\uddea Usage Examples\n\n### Full Install (with config)\n```bash\nfrappe install system --config production.yaml\nfrappe install user --config production.yaml\nfrappe install deps --config production.yaml\nfrappe install mariadb --config production.yaml\nfrappe install bench --config production.yaml\nfrappe install init --config production.yaml\nfrappe install prod --config production.yaml\n```\n\n### Create a Site\n```bash\nfrappe site create --bench-name frappe-bench --site-name example.com --mariadb-root-password rootpass --admin-password admin123\n```\n\n### SSL Setup\n```bash\nfrappe ssl setup --site-name example.com --email admin@example.com\n```\n\n### Backup Setup\n```bash\nfrappe backup setup --admin-email admin@example.com --bench-name frappe-bench --site-name example.com\n```\n\n### Service Management\n```bash\nfrappe service restart\nfrappe service status --bench-name frappe-bench --site-name example.com\n```\n\n### Firewall\n```bash\nfrappe firewall setup\n```\n\n### App Management\n```bash\nfrappe app clone --bench-name frappe-bench --repo-url https://github.com/your/app.git --branch main\n```\n\n### Rollback/Uninstall\n```bash\nfrappe rollback uninstall --bench-name frappe-bench --site-name example.com\n```\n\n### Log Rotation\n```bash\nfrappe logrotate setup\n```\n\n---\n\n## \ud83d\udee0\ufe0f Config File Usage\n\n- Place your config in YAML (see `data/example_config.yaml`).\n- Pass `--config production.yaml` to any command for reproducible, non-interactive installs.\n\n**Example:**\n```yaml\nsystem:\n timezone: \"Africa/Dar_es_Salaam\"\n locale: \"en_US.UTF-8\"\n user: \"frappe\"\nfrappe:\n branch: \"version-15\"\n bench_name: \"frappe-bench\"\n site_name: \"example.com\"\n admin_password: \"changeme\"\n mariadb_root_password: \"rootpass\"\nservices:\n enable_ssl: true\n enable_ufw: true\nbackup:\n admin_email: \"admin@example.com\"\n external_hd_uuid: \"\"\n retention_days: 7\n## \ud83d\udcdd License\n\nThis project is licensed under the [MIT License](LICENSE).\n\n---\n\n## \ud83d\udee1\ufe0f Server Management Best Practices\n- Timezone and locale configuration\n- Dedicated `frappe` user\n- Automatic UFW (firewall) setup\n- Fail2Ban setup (optional)\n- SSH hardening (optional)\n- Certbot HTTPS auto-renewal\n- Systemd + Supervisor integration\n- Log rotation\n\n---\n\n## \ud83e\udde0 Advanced/Extensible\n- **Multi-tenancy:** `site list`, `site backup`, `site restore`\n- **Monitoring:** `monitor logs`, `monitor health` (stubs for future)\n- **Performance:** `optimize performance` (stub)\n- **Config management:** `config set/get/validate` (stubs)\n\n---\n\n## \ud83d\udc1e Troubleshooting\n- All actions are logged to `/var/log/frappe-installer.log` (or local fallback)\n- Use `frappe service status` to check system health\n- Use `frappe logrotate setup` to prevent log bloat\n- For permission issues, ensure you run as a sudo-capable user\n\n---\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repo and create a feature branch\n2. Add or improve a command group/module\n3. Write clear commit messages and update the README if needed\n4. Submit a pull request with a clear description\n\n---\n\n## \ud83d\udcc4 License\nMIT (or your preferred license) ",
"bugtrack_url": null,
"license": "MIT",
"summary": "Professional CLI for Frappe deployment and management.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/okama12/frappe-cli.git",
"Repository": "https://github.com/okama12/frappe-cli.git"
},
"split_keywords": [
"frappe",
" cli",
" installer",
" deployment",
" management"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "811ac4581f605d196ad40278631b7e7f5202f59d9540d4386a91b3eb02ff3295",
"md5": "ae106b556286e6ebebd350fc3980e3a2",
"sha256": "f4523e7661839ec6caf366a66b3ab7a1b3448133a53c4d30ad58ed99d1676703"
},
"downloads": -1,
"filename": "frappe_cli-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae106b556286e6ebebd350fc3980e3a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 66539,
"upload_time": "2025-07-22T14:23:23",
"upload_time_iso_8601": "2025-07-22T14:23:23.139356Z",
"url": "https://files.pythonhosted.org/packages/81/1a/c4581f605d196ad40278631b7e7f5202f59d9540d4386a91b3eb02ff3295/frappe_cli-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1fc845a9d182834b24312820075bc76b611f680ba5f3bea0dc03487237c54cc2",
"md5": "07d94302d94e36ebef05d53d59520728",
"sha256": "4c9f9f2b81ca8d2aee3328ec2e19faf101ab1599246a46826b78ca1928a7b418"
},
"downloads": -1,
"filename": "frappe_cli-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "07d94302d94e36ebef05d53d59520728",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 43549,
"upload_time": "2025-07-22T14:23:24",
"upload_time_iso_8601": "2025-07-22T14:23:24.126369Z",
"url": "https://files.pythonhosted.org/packages/1f/c8/45a9d182834b24312820075bc76b611f680ba5f3bea0dc03487237c54cc2/frappe_cli-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 14:23:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "okama12",
"github_project": "frappe-cli",
"github_not_found": true,
"lcname": "frappe-cli"
}