TFGrid ERPNext Guide¶
Open-source ERP system (Frappe/ERPNext) on ThreeFold Grid.
Overview¶
Deploy a complete ERPNext installation for managing your business operations including accounting, inventory, sales, HR, and more.
Key Features:
- 📊 Accounting - Complete financial management
- 📦 Inventory - Stock management and tracking
- 🛒 Sales & Purchase - Order management
- 🏭 Manufacturing - Production planning
- 👥 HR & Payroll - Employee management
- 📋 Projects - Task and project tracking
- 📈 CRM - Customer relationship management
Quick Start¶
Prerequisites¶
- TFGrid account with mnemonic configured
tfgrid-composeinstalled (Installation Guide)- Domain with DNS pointing to your server
- Minimum 4GB RAM recommended
Deploy¶
# Deploy from registry
tfgrid-compose up tfgrid-erpnext
# Or with custom configuration
tfgrid-compose up tfgrid-erpnext --var DOMAIN=erp.example.com
Access Your ERP¶
After deployment completes (10-15 minutes):
- ERPNext:
https://your-domain.com - Username:
Administrator - Password: Found in
/opt/erpnext/config/credentials.txt
Configuration¶
Environment Variables¶
| Variable | Required | Default | Description |
|---|---|---|---|
DOMAIN |
Yes | - | Public domain for ERPNext |
SSL_EMAIL |
No | - | Email for Let's Encrypt |
SITE_NAME |
No | Domain | ERPNext site name |
ADMIN_PASSWORD |
No | Auto-generated | Admin password |
DB_PASSWORD |
No | Auto-generated | Database password |
ERPNEXT_VERSION |
No | v15 | ERPNext version |
TIMEZONE |
No | UTC | Server timezone |
Example Configuration¶
Architecture¶
┌─────────────┐ ┌───────────────┐ ┌──────────────┐
│ Internet │────▶│ Caddy :443 │────▶│ Frontend │
│ │ │ (auto-SSL) │ │ (nginx) │
└─────────────┘ └───────────────┘ └──────┬───────┘
│
┌────────────────────────────┼────────────────────────────┐
│ │ │
┌─────▼─────┐ ┌───────▼───────┐ ┌───────▼───────┐
│ Backend │ │ Scheduler │ │ Workers │
│ (gunicorn)│ │ │ │ (queue-short) │
└─────┬─────┘ └───────────────┘ │ (queue-long) │
│ └───────────────┘
┌─────────┼─────────┐
│ │ │
┌─────▼───┐ ┌───▼───┐ ┌───▼───┐
│ MariaDB │ │ Redis │ │ Redis │
│ DB │ │ Cache │ │ Queue │
└─────────┘ └───────┘ └───────┘
Components:
- Caddy - Reverse proxy with automatic HTTPS
- Frontend - Nginx serving static files
- Backend - Gunicorn running Frappe/ERPNext
- Scheduler - Background job scheduler
- Workers - Queue processors (short and long running)
- MariaDB - Database
- Redis - Caching and job queues
Commands¶
Backup & Restore¶
# Create site backup
tfgrid-compose backup
# List available backups
tfgrid-compose list-backups
# Restore from backup
tfgrid-compose restore --backup /path/to/backup.tar.gz
Logs¶
# All logs
tfgrid-compose logs
# Specific service
tfgrid-compose logs backend
tfgrid-compose logs scheduler
tfgrid-compose logs worker
tfgrid-compose logs db
tfgrid-compose logs redis
tfgrid-compose logs caddy
# Follow logs
tfgrid-compose logs backend --follow
Management¶
# Open backend shell
tfgrid-compose shell
# Run bench commands
tfgrid-compose bench --site erp.example.com list-apps
tfgrid-compose bench --site erp.example.com migrate
tfgrid-compose bench --site erp.example.com clear-cache
# Run database migrations
tfgrid-compose migrate
# Restart services
tfgrid-compose restart
# Health check
tfgrid-compose healthcheck
Resource Requirements¶
| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 2 cores | 4 cores |
| Memory | 4 GB | 8 GB |
| Disk | 50 GB | 100 GB |
Estimated Cost: $30-50/month on ThreeFold Grid
Initial Setup Wizard¶
After first login, ERPNext guides you through:
- Company Setup - Name, abbreviation, country
- Chart of Accounts - Select template for your country
- Fiscal Year - Set your financial year
- Currency - Default currency
- Users - Add initial users
Bench Commands¶
The bench command is the primary management tool for Frappe/ERPNext:
Common Commands¶
# List installed apps
tfgrid-compose bench --site erp.example.com list-apps
# Clear cache
tfgrid-compose bench --site erp.example.com clear-cache
# Run migrations
tfgrid-compose bench --site erp.example.com migrate
# Reset admin password
tfgrid-compose bench --site erp.example.com set-admin-password newpassword
# Enable/disable maintenance mode
tfgrid-compose bench --site erp.example.com set-maintenance-mode on
tfgrid-compose bench --site erp.example.com set-maintenance-mode off
# Rebuild assets
tfgrid-compose bench --site erp.example.com build
# Show site config
tfgrid-compose bench --site erp.example.com show-config
Installing Additional Apps¶
# Get an app
tfgrid-compose bench get-app hrms
# Install app on site
tfgrid-compose bench --site erp.example.com install-app hrms
Popular apps: - HRMS - Human Resource Management - Payments - Payment gateway integrations - eCommerce - Online store integration - Healthcare - Hospital management
Backup Details¶
What's Backed Up¶
- Database - Full MariaDB dump
- Public files - Attachments, images
- Private files - Reports, backups
- Configuration - Site config
Backup Location¶
Backups stored in /opt/erpnext/backups/:
Automated Backups¶
ERPNext has built-in scheduled backups. Configure in: Settings → System Settings → Backup
Or set up cron:
SSL Configuration¶
Automatic SSL (Default)¶
Caddy automatically obtains Let's Encrypt certificates.
Requirements¶
- Domain DNS points to server IP
- Ports 80 and 443 accessible
- Valid domain name
Local Development¶
For local development:
Troubleshooting¶
Common Issues¶
"Site not found" error
ERPNext takes 5-10 minutes to initialize. Wait and retry.
Check initialization status:
Slow performance
- Check memory usage:
- Ensure Redis is running:
- Clear cache:
Database connection errors
- Check MariaDB status:
- Verify credentials in
/opt/erpnext/.env
Background jobs not running
Check scheduler and workers:
Restart if needed:
PDF generation fails
Install wkhtmltopdf (usually included):
Health Check¶
Checks: - Docker service - All container status - HTTP response - Disk space
Updating ERPNext¶
Minor Updates¶
# Pull latest images
cd /opt/erpnext/frappe_docker
docker compose -f pwd.yml pull
# Restart containers
docker compose -f pwd.yml up -d
# Run migrations
tfgrid-compose migrate
Major Version Upgrades¶
-
Backup first:
-
Update version in .env:
-
Pull and restart:
-
Run migrations:
Data Import¶
From CSV¶
- Go to the DocType list (e.g., Customer)
- Click Menu → Import Data
- Download template
- Fill in data
- Upload and import
From Another ERPNext¶
- Export data using Data Export tool
- Import using Data Import tool
Customization¶
Custom Fields¶
Settings → Customize Form
Add fields to any DocType without coding.
Custom Scripts¶
Settings → Client Script
Add JavaScript for client-side customization.
Custom Reports¶
Settings → Report Builder
Create custom reports with filters and charts.
Security Best Practices¶
- Strong admin password - Change default immediately
- Role-based access - Configure user permissions
- Regular backups - Enable scheduled backups
- Keep updated - Apply security patches
- HTTPS only - Already enabled by default
- Audit logs - Review activity logs regularly
Integration¶
REST API¶
ERPNext provides a full REST API:
# Get list
curl https://erp.example.com/api/resource/Customer
# Get single record
curl https://erp.example.com/api/resource/Customer/CUST-0001
# Create record
curl -X POST https://erp.example.com/api/resource/Customer \
-H "Authorization: token api_key:api_secret" \
-d '{"customer_name": "New Customer"}'
Webhooks¶
Configure webhooks in: Settings → Webhook
Related Documentation¶
TFGrid Studio Ecosystem
Integrated tools and resources