ERPNext on AWS User Guide

Overview

This image runs ERPNext, the comprehensive open source Enterprise Resource Planning suite that covers accounting, order management, inventory, manufacturing, CRM, projects, HR and payroll, helpdesk and asset management in one integrated web application. ERPNext is built on the Frappe framework, a full stack Python and JavaScript metadata driven platform, and is delivered here as a complete production system so a full ERP is running within minutes of launch.

ERPNext runs as a Frappe bench under a dedicated frappe service account at /home/frappe/frappe-bench. The production stack is wired by bench setup production: gunicorn web workers and Frappe background workers managed by supervisor, a Node.js socket.io server for realtime desk updates, Redis for caching and the job queue, and a MariaDB database. nginx on port 80 is the single public listener; it serves the built static assets and reverse proxies dynamic and realtime traffic to the loopback services. The MariaDB database lives at /var/lib/mysql, which is a dedicated, independently resizable EBS data volume that survives instance replacement. Systemd manages MariaDB, Redis, supervisor and nginx, starting them on boot and restarting them on failure.

ERPNext secures its desk with the built in Administrator account. On the first boot of every deployed instance a one shot service generates a fresh Administrator password, unique to that instance, applies it to the live site and pins the site address to the instance, so two instances launched from the same Amazon Machine Image never share credentials. The password is written to /root/erpnext-aws-credentials.txt with mode 0600 so that only the root user can read it.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the ERPNext desk
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for ERPNext. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.large or larger; ERPNext runs several services (the web workers, background workers, the socket.io server, Redis and MariaDB) and benefits from the memory. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the desk. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a short time after the instance state becomes Running and the status checks pass, while the per instance Administrator password is generated and applied and the production stack starts.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg ERPNext Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=erpnext}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Administrator Password

The ERPNext Administrator password is unique to your instance and was generated on first boot. Read it as root:

sudo cat /root/erpnext-aws-credentials.txt

The file lists the desk URL, the Administrator login (Administrator) and the generated password. Keep this password somewhere safe.

Step 5: Sign In to the ERPNext Desk

The desk is served on port 80 by nginx in front of the gunicorn web workers. In a browser, go to:

http://<instance-public-ip>/

Sign in as Administrator with the password from the credentials file. On the first sign in ERPNext launches the setup wizard, where you choose your language and region, create your company and chart of accounts, and add your first users.

Step 6: Confirm ERPNext Is Running

Over SSH, confirm the database, Redis, the supervisor process group and the nginx proxy are active and that the application answers:

sudo systemctl is-active mariadb redis-server supervisor nginx
curl -s -o /dev/null -w 'ping HTTP %{http_code}\n' 'http://127.0.0.1/api/method/ping'

You should see all four services reported as active and the Frappe API answering 200 on /api/method/ping. To see the individual Frappe processes (the gunicorn web workers, the background workers, the realtime socket.io server and the bench Redis instances) that supervisor manages, run:

sudo supervisorctl status

MariaDB, Redis and the application workers all listen on loopback only and are never exposed publicly; only nginx on port 80 is reachable from outside the instance.

Step 7: Complete the Setup Wizard and Explore the Modules

After the setup wizard, you land on the desk home with the module workspaces. Open Accounting to manage your chart of accounts, journal entries, sales and purchase invoices and financial reports; Stock for items, warehouses and stock entries; Selling and Buying for the order to cash and procure to pay cycles; Manufacturing for bills of materials and work orders; CRM for leads and opportunities; Projects, HR and Support for the remaining suites. Each workspace lists the masters, transactions and reports for that area.

Every record in ERPNext is a Frappe DocType rendered through a consistent list and form interface. Open any list, for example the list of Items or Sales Invoices, to filter, sort, bulk edit and export records, and select + Add to create a new document.

Step 8: Use the Frappe REST API

Every ERPNext operation is also available programmatically through the Frappe REST API on the same port 80. Authenticate by posting your credentials to /api/method/login, which returns a session cookie, then call the resource endpoints. The following example logs in and fetches the list of companies, replacing <public-ip> with your instance address and <new-password> with your Administrator password:

curl -s -c /tmp/erpnext-cookies.txt \
  --data-urlencode 'usr=Administrator' \
  --data-urlencode 'pwd=<new-password>' \
  'http://<public-ip>/api/method/login'
curl -s -b /tmp/erpnext-cookies.txt \
  'http://<public-ip>/api/resource/Company'

For server to server integrations, generate an API key and secret for a user under the user's settings in the desk and send them in an Authorization: token <key>:<secret> header instead of the cookie flow. Treat API keys like passwords and scope each integration to the minimum role it needs.

Step 9: Bench and the Site

ERPNext is managed through the Frappe bench command line as the frappe user. The bench lives at /home/frappe/frappe-bench and the site name is stored in /etc/cloudimg-erpnext-site. To run a bench command, switch to the bench directory as the frappe user. For example, to print the installed app versions:

sudo -u frappe -H bash -lc 'cd /home/frappe/frappe-bench && bench version'

Common operations include bench --site <site> set-admin-password <new-password> to change the Administrator password, bench --site <site> backup to take a database and files backup, and bench --site <site> clear-cache after configuration changes. The site name to substitute for <site> is the value in /etc/cloudimg-erpnext-site.

Step 10: The Data Volume

The ERPNext database lives on a dedicated EBS volume mounted at /var/lib/mysql. This keeps the database off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /var/lib/mysql

To grow the database store, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device. Because the database is on its own volume, you can snapshot it for backup or detach and reattach it to a replacement instance.

Step 11: Custom Domain and HTTPS

The desk is served over plain HTTP on port 80 by nginx. For production use, place it behind a custom domain and TLS. First boot pins the site host name to your instance public IP so the desk is reachable immediately. To use a domain name, set the site host name to your domain as the frappe user, replacing <your-domain> with your domain:

sudo -u frappe -H bash -lc 'cd /home/frappe/frappe-bench && bench --site $(cat /etc/cloudimg-erpnext-site) set-config host_name "https://<your-domain>"'

Point the domain's DNS A record at the instance public IP. To terminate TLS, place the instance behind an Application Load Balancer with a managed certificate, or install Certbot on the instance and configure nginx to listen on 443 with your certificate, proxying to the Frappe upstreams exactly as the bundled site does for port 80. Restrict the security group so ports 80 and 443 are reachable only from the networks that need the desk.

Step 12: Backup and Maintenance

Back up ERPNext by snapshotting the /var/lib/mysql EBS volume, which captures the entire database, and by keeping a copy of the site directory under /home/frappe/frappe-bench/sites, which holds the site configuration and the uploaded files. You can also take a logical backup with the bench backup command, which writes a database dump and a files archive into the site's private/backups directory:

sudo -u frappe -H bash -lc 'cd /home/frappe/frappe-bench && bench --site $(cat /etc/cloudimg-erpnext-site) backup --with-files'

Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; MariaDB, Redis, supervisor and nginx start automatically on boot and the Administrator password is preserved across reboots. Upgrade ERPNext and the Frappe framework with the bench update workflow after taking a backup; see the Frappe documentation for the upgrade procedure appropriate to your version.

Support

This image is published and supported by cloudimg. Support covers deployment, the setup wizard, company and chart of accounts configuration, custom DocTypes and workflows, the REST API, background jobs, database tuning, custom domains, TLS and scaling. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.