frappe-cli


Namefrappe-cli JSON
Version 0.1.2 PyPI version JSON
download
home_pagehttps://github.com/okama12/frappe-cli.git
SummaryProfessional CLI for Frappe deployment and management.
upload_time2025-07-22 14:23:24
maintainerNone
docs_urlNone
authorRashidi Okama
requires_python<4.0,>=3.10
licenseMIT
keywords frappe cli installer deployment management
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Frappe Installer CLI

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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"
}
        
Elapsed time: 1.05322s