Frappe Ops Cloud

Frappe Cloud & Press

Complete reference for Frappe Cloud managed hosting and Press self-hosted alternative.

---

Quick Reference: Frappe Cloud Concepts

---

Decision Tree: Frappe Cloud vs Self-Hosted

Choosing hosting strategy:
├── Small team, want zero ops overhead?
│   └── Frappe Cloud (Shared Bench) — fastest time to production
├── Need custom server configuration?
│   ├── Budget for managed infra? → Frappe Cloud (Private Bench)
│   └── Want full control? → Self-hosted with bench
├── Need to host Frappe for multiple clients?
│   ├── Want managed platform? → Frappe Cloud
│   └── Want own platform? → Self-hosted Press
├── Regulatory/compliance — data must stay on-premises?
│   └── Self-hosted (bench or Press)
└── Development/testing environment?
    ├── Quick prototype → Frappe Cloud (free trial)
    └── Long-term dev → Local bench installation

---

Frappe Cloud Overview

Frappe Cloud is a fully managed hosting platform for the Frappe stack. It handles server provisioning, backups, updates, monitoring, and scaling.

Core Features

Infrastructure Options

---

Frappe Cloud Dashboard

Site Management

The dashboard provides centralized control for all site operations:

• Create sites — Provision new sites on shared or private benches
• Install/remove apps — Add or remove Frappe apps from sites
• Backups — Manual and scheduled backups, restore from backup
• Domain management — Add custom domains with automatic SSL
• Site config — Edit site_config.json via the dashboard
• Monitoring — View CPU, memory, disk usage, and request logs
• Site actions — Migrate, update, suspend, archive, or transfer sites

Bench Management

• Create benches — Set up shared or private benches
• App management — Select apps and their versions/branches
• Update scheduling — Control when benches receive updates
• Environment variables — Set custom environment variables
• SSH access — Connect to bench via SSH for debugging
• Log browser — View application and error logs
• Database access — Query the database via the dashboard

Server Management

• Provision servers — Create servers across multiple cloud providers
• Scale resources — Upgrade CPU, memory, and storage
• Storage add-ons — Attach additional storage volumes
• Server snapshots — Create and restore server snapshots

---

Deploying Apps on Frappe Cloud

Adding a Custom App

1. Navigate to Apps in the Frappe Cloud dashboard 2. Click Add App and provide the GitHub repository URL 3. Select the branch to deploy 4. Configure build settings if needed 5. The app becomes available for installation on sites within compatible benches

App Marketplace

Frappe Cloud includes a marketplace where developers can:

• List apps with descriptions and pricing
• Set compatibility requirements (Frappe version, dependencies)
• Configure pricing models (free, one-time, subscription)
• Manage payouts for commercial apps
• Track installations and usage analytics

Deployment Workflow

Developer pushes code → Frappe Cloud detects update →
  Bench rebuild triggered → Assets compiled →
    Sites migrated → New version live

For Private Benches: Updates are controlled by the bench owner — NEVER auto-deployed without approval.

For Shared Benches: Frappe manages the update schedule.

---

Site Provisioning Workflow

Creating a New Site

1. Select bench — Choose shared or private bench 2. Choose plan — Select resource allocation (CPU, memory, storage) 3. Configure apps — Select which apps to install 4. Set domain — Use *.frappe.cloud subdomain or custom domain 5. Create — Frappe Cloud provisions the site (typically under 5 minutes)

Custom Domain Setup

1. Navigate to site Domains in the dashboard 2. Add your custom domain (e.g., erp.example.com) 3. Configure DNS: Add a CNAME record pointing to the Frappe Cloud proxy 4. Frappe Cloud verifies DNS and provisions SSL certificate automatically 5. ALWAYS wait for DNS propagation before expecting SSL to work (up to 48 hours)

Critical Rules

• ALWAYS use CNAME records for custom domains (not A records)
• NEVER transfer DNS to Frappe Cloud — only add CNAME records
• ALWAYS verify SSL is active before switching production traffic
• Custom domain SSL uses Let's Encrypt — auto-renews before expiry

---

Frappe Cloud vs Self-Hosted Comparison

---

Press: Self-Hosted Frappe Cloud

What Is Press?

Press is the open-source platform (AGPL-3.0) that powers Frappe Cloud. Organizations can self-host Press to create their own managed hosting platform for Frappe applications.

GitHub: https://github.com/frappe/press

Architecture

Key Capabilities

• Multi-server management — Provision and manage multiple servers
• Site lifecycle — Create, update, migrate, backup, restore, archive sites
• Bench management — Deploy benches with specific app versions
• Billing system — Subscriptions, invoicing, wallet credits, ERP integration
• Marketplace — App listing, pricing, payouts
• Role-based access — Granular permissions per team and resource
• Monitoring — Real-time metrics and alerting

When to Self-Host Press

• You need to host Frappe for multiple clients/tenants
• You want a managed platform but on your own infrastructure
• You need full data sovereignty and regulatory compliance
• You want to offer Frappe hosting as a service

When NOT to Self-Host Press

• NEVER self-host Press for a single site — use bench directly
• NEVER self-host Press without dedicated DevOps capacity
• NEVER underestimate the operational overhead — Press itself requires maintenance

Self-Hosting Requirements

• Dedicated servers (bare metal or VMs) with Ubuntu
• DNS management for wildcard domains
• Object storage for backups (S3-compatible)
• SMTP service for transactional email
• Familiarity with Ansible, Docker, and Frappe Framework

---

Frappe Cloud Limitations

What You CANNOT Do on Frappe Cloud

• Install system-level packages (no root access on shared benches)
• Modify Nginx/Supervisor configuration directly
• Access raw database files (only SQL access via dashboard)
• Run long-running background processes outside Frappe's job queue
• Use non-standard ports or protocols

Shared Bench Limitations

• No SSH access
• No custom environment variables (use site_config.json instead)
• Shared resources with other sites — performance may vary
• Update schedule controlled by Frappe (not the site owner)

Private Bench Advantages Over Shared

• SSH access for debugging
• Custom environment variables
• Controlled update schedule
• Dedicated resources
• Custom app versions and branches

---

Frappe Cloud Best Practices

Site Configuration

• ALWAYS set maintenance_mode before large data imports
• ALWAYS use the dashboard for site config changes (not direct file edits)
• NEVER disable scheduler on Frappe Cloud — use pause_scheduler instead
• ALWAYS test app updates on a staging site before production

Backup Strategy

• Frappe Cloud creates automatic daily backups
• ALWAYS create a manual backup before major changes
• ALWAYS download and store backups off-platform periodically
• NEVER rely solely on Frappe Cloud backups — maintain your own copies

Performance

• Monitor site usage via the dashboard — upgrade plan before hitting limits
• Use background jobs for heavy operations (not synchronous API calls)
• Enable Redis caching for frequently accessed data
• Review slow query logs via the database analyzer tool

---

Frappe Cloud DevOps Tools

Analytics Integrations

Frappe Cloud sites can connect to external analytics tools:

• Frappe Insights (native)
• Power BI (via API)
• Metabase (via database connection)
• Custom dashboards (via Frappe API)

---

Reference Files

Frappe Cloud Anti-Patterns

Anti-Pattern 1: Self-Hosting Press for a Single Site

WRONG: Setting up Press infrastructure to host one ERPNext instance

Why it breaks: Press requires multiple servers, Ansible, Docker, and ongoing maintenance. For a single site, this overhead is not justified.

Correct approach: Use bench directly for single-site self-hosting, or use Frappe Cloud shared bench.

---

Anti-Pattern 2: Using A Records Instead of CNAME for Custom Domains

WRONG: erp.example.com  A  123.45.67.89

Why it breaks: Frappe Cloud's IP addresses can change. A records will break when infrastructure is migrated.

Correct approach: ALWAYS use CNAME records:

erp.example.com  CNAME  mysite.frappe.cloud

---

Anti-Pattern 3: Editing Files via SSH on Frappe Cloud

WRONG: SSH into private bench → edit app source code directly

Why it breaks: Direct file edits are overwritten on the next deployment. Changes are not tracked in version control.

Correct approach: ALWAYS push changes to the GitHub repository. Frappe Cloud deploys from the repo.

---

Anti-Pattern 4: Relying Solely on Frappe Cloud Backups

WRONG: Assuming Frappe Cloud backups are sufficient disaster recovery

Why it breaks: If your Frappe Cloud account is compromised, suspended, or experiences a billing issue, you may lose access to backups.

Correct approach: ALWAYS maintain off-platform backups:

• Download backups periodically from the dashboard
• Store in your own S3 bucket or local storage
• Test restore procedures regularly

---

Anti-Pattern 5: Testing Updates on Production Directly

WRONG: Deploy new app version → production site updates → discover bugs

Why it breaks: On shared benches, all sites update together. A broken app affects all sites on the bench.

Correct approach: Use a staging site or separate staging bench to test updates before production.

---

Anti-Pattern 6: Using Shared Bench for Sensitive Workloads

WRONG: Running medical/financial/legal ERPNext on a shared bench

Why it breaks: Shared benches share resources with other tenants. You have no SSH access, no control over updates, and limited isolation.

Correct approach: Use a private bench or dedicated server for sensitive workloads requiring compliance or performance guarantees.

---

Anti-Pattern 7: Ignoring Frappe Cloud Plan Limits

WRONG: Running heavy background jobs on a basic plan → site becomes slow

Why it breaks: Each plan has CPU, memory, and storage limits. Exceeding them causes throttling or failures.

Correct approach: Monitor usage via the dashboard. Upgrade plans BEFORE hitting limits, not after performance degrades.

---

Anti-Pattern 8: Disabling Scheduler on Frappe Cloud

WRONG: bench --site mysite scheduler disable  # via SSH

Why it breaks: Frappe Cloud manages the scheduler. Disabling it may interfere with Cloud's internal operations.

Correct approach: Use pause_scheduler via site config if you need to temporarily stop background jobs.

---

Anti-Pattern 9: Not Setting Up Custom Domain Before Go-Live

WRONG: Launch on *.frappe.cloud domain → switch to custom domain later

Why it breaks: Changing the primary domain after go-live causes email delivery issues (SPF/DKIM), bookmark breakage, and OAuth redirect failures.

Correct approach: ALWAYS configure the custom domain and verify SSL BEFORE directing production traffic to the site.

---

Anti-Pattern 10: Storing Secrets in site_config.json Without Private Bench

WRONG: Adding API keys to site_config.json on a shared bench

Why it breaks: On shared benches, site config is accessible to the hosting platform. For sensitive secrets, this may not meet security requirements.

Correct approach: For sensitive credentials, use a private bench with environment variables, or use an external secrets manager accessed via API.

Frappe Cloud Examples

Example 1: Setting Up a New Production Site on Frappe Cloud

Step-by-Step Workflow

1. Create account at frappecloud.com 2. Add your app (if custom):

• Go to Apps → Add App
• Enter GitHub repo URL and branch
• Wait for initial build to complete

3. Create a bench (or use shared):

• Go to Benches → New Bench
• Select Frappe version (e.g., version-15)
• Add apps: frappe, erpnext, your-custom-app
• Choose region closest to your users

4. Create a site:

• Go to Sites → New Site
• Select the bench
• Choose a plan
• Set subdomain (e.g., mycompany.frappe.cloud)
• Select apps to install
• Click Create

5. Configure custom domain:

• Site → Domains → Add Domain
• Enter erp.mycompany.com
• Add CNAME record in your DNS provider:

     erp.mycompany.com  CNAME  mycompany.frappe.cloud

• Wait for DNS propagation and SSL provisioning

---

Example 2: Deploying a Custom App Update

Via GitHub Integration

1. Push code to your app's GitHub repository (configured branch)
2. Frappe Cloud detects the push
3. Navigate to Benches → Your Bench → Updates
4. Click "Deploy" to trigger rebuild
5. Wait for build to complete
6. Sites on the bench are automatically migrated

Manual Trigger

1. Navigate to Benches → Your Bench
2. Click "Update Available" indicator
3. Review changes
4. Click "Deploy" to start update
5. Monitor build progress in the dashboard

---

Example 3: Staging → Production Workflow

1. Create a staging site on the same bench:
   - Sites → New Site → "staging.mycompany.frappe.cloud"
   - Install same apps as production

2. Test updates on staging first:
   - Deploy app update to bench
   - Staging site receives the update
   - Test critical workflows

3. If staging passes:
   - Production site is already updated (same bench)

4. For isolated testing (different app versions):
   - Create a separate private bench for staging
   - Deploy new version to staging bench only
   - After testing, update production bench

---

Example 4: Restoring a Site from Backup

1. Navigate to Sites → Your Site → Backups
2. Find the backup you want to restore
3. Click "Restore" on the desired backup
4. Confirm the restore operation
5. Wait for restore to complete (site is offline during restore)
6. Verify site functionality after restore

Restoring to a New Site

1. Download backup files from the old site's Backups section
2. Create a new site on Frappe Cloud
3. Use the "Restore" option during site creation
4. Upload the backup files
5. Wait for provisioning and restore

---

Example 5: Setting Up Environment Variables (Private Bench)

1. Navigate to Benches → Your Private Bench
2. Go to Configuration → Environment Variables
3. Add variables:
   - STRIPE_SECRET_KEY = sk_live_xxx
   - SENTRY_DSN = https://xxx@sentry.io/123
   - CUSTOM_API_ENDPOINT = https://api.example.com
4. Save and restart bench

For shared benches: Use site_config.json via the dashboard instead:

1. Navigate to Sites → Your Site → Site Config
2. Add key-value pairs
3. Save (takes effect after next request)

---

Example 6: Monitoring and Debugging

Viewing Application Logs

1. Navigate to Sites → Your Site → Logs
2. Select log type:
   - frappe.log — Application logs
   - worker.log — Background job logs
   - scheduler.log — Scheduler event logs
3. Filter by date range and severity

Debugging via SSH (Private Bench Only)

1. Navigate to Benches → Your Private Bench → SSH
2. Click "Enable SSH Access"
3. Add your SSH public key
4. Connect:
   ssh frappe@your-bench-server.frappe.cloud

5. Inside SSH session:
   cd frappe-bench
   bench --site yoursite console
   >>> frappe.get_doc("Error Log", {"error": ("like", "%specific error%")})

Database Analysis

1. Navigate to DevOps → Database Analyzer
2. Select your site
3. Run queries:
   - Slow query analysis
   - Index usage statistics
   - Table size breakdown

---

Example 7: Migrating from Self-Hosted to Frappe Cloud

# On self-hosted server:
# 1. Create full backup
bench --site mysite backup --with-files

# 2. Download backup files:
#    - database.sql.gz
#    - files.tar
#    - private-files.tar

# On Frappe Cloud:
# 3. Create new site (same Frappe/ERPNext version)
# 4. Go to Sites → New Site → "Restore from backup"
# 5. Upload the three backup files
# 6. Wait for restore to complete
# 7. Verify data and functionality
# 8. Configure custom domain
# 9. Switch DNS from old server to Frappe Cloud

---

Example 8: Frappe Cloud API Usage

Accessing Frappe Cloud API

Frappe Cloud exposes a REST API for programmatic management:

# List your sites
curl -H "Authorization: token api_key:api_secret" \
  https://frappecloud.com/api/method/press.api.site.all

# Get site details
curl -H "Authorization: token api_key:api_secret" \
  https://frappecloud.com/api/method/press.api.site.get \
  -d "name=mysite.frappe.cloud"

# Create a backup
curl -X POST \
  -H "Authorization: token api_key:api_secret" \
  https://frappecloud.com/api/method/press.api.site.backup \
  -d "name=mysite.frappe.cloud"

Note: API availability and endpoints may change. ALWAYS check the latest Frappe Cloud documentation for current API reference.