webERP 5.0.1 on AWS User Guide

Overview

This guide covers launching and using the webERP 5.0.1 Accounting on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg accounting, HR and finance listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

webERP is a long running open source, web based accounting and business administration system written in PHP. It covers a double entry general ledger, accounts receivable and payable, sales and purchase orders, inventory and multi location stock control, manufacturing with bills of materials, fixed assets and petty cash, with every module in one browser interface.

What the cloudimg image adds:

• A clean company, ready to configure. The image ships one company (weberp) with the English (UK) chart of accounts (146 general ledger accounts), currencies, tax and security roles loaded, and no sample customers, suppliers, stock or transactions. The upstream demo databases, which carry the well known admin / weberp login and fictional ledgers, are removed from the image.
• No web installer. Upstream webERP's installer makes whoever reaches it first the administrator. On this image the company is built at image build time with webERP's own installer functions, then the install/ directory is deleted, and nginx returns 404 for /install/ as well.
• Passwords unique to your instance. The webERP admin password and the MariaDB password webERP uses are generated on first boot and written to /root/weberp-credentials.txt (root only). The image ships with the admin account blocked and the database account locked, and nginx and PHP-FPM refuse to start until first boot has finished.
• HTTPS from the first boot. nginx serves webERP on port 443 with a certificate generated on your instance, port 80 redirects to HTTPS, requests for a host name the instance does not serve are dropped, and webERP's own "HTTPS only" setting is on.
• Only the application on the web. The Composer vendor/ tree (its XML-RPC debugger can send requests to any address), SQL scripts, command line tools, configuration files and company data files other than logos and part pictures answer 404.
• Hardened defaults. MariaDB listens on 127.0.0.1 only. nginx, PHP-FPM, MariaDB and the first boot service are blocked from the instance metadata service, the AMI requires IMDSv2, PHP is handed the configured host name and the real client address from the connection (never values a client sends), the session cookie is Secure and HttpOnly, and cross site form posts are refused.
• Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: webERP 5.0.1 (the upstream v5.0.1 release, checksum verified), nginx, PHP 8.3 FPM with OPcache, MariaDB, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet (or a private route you use for management).
• A security group that allows TCP 22 (SSH) from your admin network, and TCP 443 (webERP) and TCP 80 (redirects to HTTPS) from the networks your users work from. Never open 3306.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick webERP 5.0.1 Accounting on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large, your key pair and a security group as above. The database lives on the root volume, so for production give the root volume room to grow (20 GiB or more).

With the AWS CLI (replace the values in angle brackets):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --block-device-mappings 'DeviceName=/dev/sda1,Ebs={VolumeSize=20,VolumeType=gp3}' \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=weberp}]'

First boot takes well under a minute after the instance is running.

Step 2: Connect to your instance

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

Step 3: Check the services

First boot sets the passwords and the certificate, then nginx and PHP-FPM start:

systemctl is-active nginx php8.3-fpm mariadb weberp-firstboot
sudo test -f /var/lib/cloudimg/weberp-firstboot.done && echo FIRSTBOOT_DONE

All four units are active and the first boot marker is present:

active
active
active
active
FIRSTBOOT_DONE

Only SSH and nginx listen on network ports; MariaDB listens on the loopback address and PHP-FPM uses a local socket:

sudo ss -lntp | awk 'NR>1 {print $4, $6}' | grep -v '127.0.0.5' | sort

0.0.0.0:22 users:(("sshd",...))
0.0.0.0:443 users:(("nginx",...))
0.0.0.0:80 users:(("nginx",...))
127.0.0.1:3306 users:(("mariadbd",...))
[::]:22 users:(("sshd",...))
[::]:443 users:(("nginx",...))
[::]:80 users:(("nginx",...))

Step 4: Get your URL and passwords

sudo cat /root/weberp-credentials.txt

The file is readable by root only:

# webERP 5.0.1 - generated on first boot by weberp-firstboot.service
# These credentials are unique to this instance; none was baked into the image. Keep this file secret.

WEBERP_URL=https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/
WEBERP_COMPANY=weberp
WEBERP_ADMIN_USER=admin
WEBERP_ADMIN_PASSWORD=<WEBERP_ADMIN_PASSWORD>

MARIADB_DATABASE=weberp
MARIADB_USER=weberp
MARIADB_PASSWORD=<MARIADB_PASSWORD>

# The certificate is self signed (minted on this instance); port 80 redirects to https.
# Change the name webERP is served as:  sudo weberp-set-hostname <your-dns-name>
# MariaDB listens on 127.0.0.1 only; on-box maintenance: sudo mariadb
# User guide: https://www.cloudimg.co.uk/guides/weberp-5-0-1-on-ubuntu-24-04-aws/

The URL uses the instance's public DNS name from the EC2 instance metadata. The certificate also names the public and private IP addresses, so https://<public-ip>/ works too. If you stop and start the instance without an Elastic IP, the boot service picks up the new address and issues a new certificate for it. To serve webERP under your own DNS name, see Step 8.

You only need the MariaDB password for your own tools; webERP already has it in /var/www/weberp/config.php.

Step 5: Sign in

Open the WEBERP_URL in your browser. The certificate is self signed, so your browser asks you to confirm it the first time (or install your own, Step 8). The company webERP Company is preselected; sign in as admin with the password from Step 4:

The main menu has a tab for each module (Sales, Receivables, Purchases, Payables, Inventory, Manufacturing, General Ledger, Asset Manager, Petty Cash, Setup and Utilities). The footer shows the webERP version:

General Ledger, then GL Account (under Maintenance) lists the chart of accounts the company ships with, where you can add, rename or remove accounts:

Reports such as the trial balance, profit and loss and balance sheet run from the General Ledger tab, on screen, as PDF or as a spreadsheet:

You can also check the sign in from the instance. This script signs in through the real login form over HTTPS with the instance's password, then shows that a blank password, the upstream default weberp and common weak passwords are refused (each attempt uses a new session, so the checks never lock the account):

sudo weberp-cred-roundtrip.sh

OK per-instance admin signs in over HTTPS; blank, admin/weberp and weak guesses refused

Step 6: Set up your company

Open Setup. The options you need first, in order:

1. Company Preferences: company name, address, tax reference, home currency and the default GL accounts.
2. System Parameters: date format, credit limits, overdue terms and other defaults.
3. Currency Maintenance, Tax Authorities and Rates Maintenance and Tax Group Maintenance for your tax rules.
4. Sales Types (price lists) and Customer Types: webERP requires at least one of each before you can add a customer; Supplier Types before suppliers.
5. Inventory Locations Maintenance and Inventory Categories Maintenance before stock items.
6. Users Maintenance to add a user for each person, with a security role that matches their job.

Step 7: E-mail (optional)

webERP sends e-mail for statements, purchase orders and alerts. Set your SMTP relay under Setup, SMTP Server Details. Amazon SES works as the relay (port 587 with STARTTLS); allow outbound 587 in your security group or network ACLs if you restrict egress.

Step 8: Your own DNS name and certificate

Point a DNS record at the instance (an Elastic IP keeps the address stable), then set the name webERP is served as. This mints a new self signed certificate for the name, updates nginx and the URL in /root/weberp-credentials.txt, and keeps the name across reboots:

sudo weberp-set-hostname <your-domain>

To use a certificate from a public or internal certificate authority instead (for example one issued by Let's Encrypt for <your-domain>), copy it over the generated pair and reload nginx (running weberp-set-hostname again replaces it with a self signed one):

sudo install -m 0644 <your-domain>.crt /etc/ssl/weberp/weberp.crt
sudo install -m 0600 <your-domain>.key /etc/ssl/weberp/weberp.key
sudo nginx -t && sudo systemctl reload nginx

Step 9: Security checks

The installer is gone, and nginx serves only the application. The vendor debugger, the configuration file, SQL scripts and company data files answer 404, and plain HTTP redirects to HTTPS:

H=$(sudo grep '^WEBERP_URL=' /root/weberp-credentials.txt | cut -d= -f2- | sed -E 's#https://([^/]+)/#\1#')
for p in /index.php /install/ /vendor/phpxmlrpc/phpxmlrpc/debugger/ /config.php /sql/config.sql /companies/weberp/Companies.php; do
  curl -sk -o /dev/null -w "%{http_code}  $p\n" --resolve "$H:443:127.0.0.1" "https://$H$p"
done
curl -s -o /dev/null -w 'http:// -> %{http_code} %{redirect_url}\n' --resolve "$H:80:127.0.0.1" "http://$H/"
ls /var/www/weberp/install 2>&1 | sed 's/^ls: //'
[ "$(curl -sk -o /dev/null -w '%{http_code}' --resolve "$H:443:127.0.0.1" "https://$H/install/")" = "404" ]

200  /index.php
404  /install/
404  /vendor/phpxmlrpc/phpxmlrpc/debugger/
404  /config.php
404  /sql/config.sql
404  /companies/weberp/Companies.php
http:// -> 301 https://ec2-<public-ip-dashed>.compute-1.amazonaws.com/
cannot access '/var/www/weberp/install': No such file or directory

webERP reports version 5.0.1 and runs with its "HTTPS only" setting on:

grep "VersionNumber'\] =" /var/www/weberp/includes/GetConfig.php
sudo mariadb -N -B weberp -e "SELECT confname, confvalue FROM config WHERE confname IN ('VersionNumber','HTTPS_Only');"

$_SESSION['VersionNumber'] = '5.0.1';
HTTPS_Only  1
VersionNumber   5.0.1

The certificate was generated on this instance and names its own addresses:

H=$(sudo grep '^WEBERP_URL=' /root/weberp-credentials.txt | cut -d= -f2- | sed -E 's#https://([^/]+)/#\1#')
echo | openssl s_client -connect 127.0.0.1:443 -servername "$H" 2>/dev/null | openssl x509 -noout -subject -ext subjectAltName

subject=CN = ec2-<public-ip-dashed>.compute-1.amazonaws.com, O = cloudimg
X509v3 Subject Alternative Name:
    DNS:ec2-<public-ip-dashed>.compute-1.amazonaws.com, IP Address:<public-ip>, IP Address:<private-ip>, IP Address:127.0.0.1, DNS:localhost

None of the services can reach the instance metadata service:

systemctl show nginx php8.3-fpm mariadb weberp-firstboot -p Id -p IPAddressDeny

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128
Id=nginx.service

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128
Id=php8.3-fpm.service

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128
Id=mariadb.service

IPAddressDeny=169.254.169.254/32 168.63.129.16/32 fd00:ec2::254/128
Id=weberp-firstboot.service

nginx hands PHP the configured host name and the client address from the connection, never values a client sends:

grep -E 'fastcgi_param (HTTP_HOST|HTTPS|HTTP_X_FORWARDED_FOR|HTTP_X_REAL_IP|HTTP_CLIENT_IP) ' /etc/nginx/sites-available/cloudimg-weberp

        fastcgi_param HTTP_HOST $weberp_host;
        fastcgi_param HTTPS on;
        fastcgi_param HTTP_X_FORWARDED_FOR $remote_addr;
        fastcgi_param HTTP_X_REAL_IP $remote_addr;
        fastcgi_param HTTP_CLIENT_IP $remote_addr;

nginx also refuses a form post whose Origin is another web site (HTTP 403). webERP's XML-RPC API clients send no Origin and are unaffected.

Files webERP writes for download under companies/weberp/reports (sales and GL graph images, CSV exports) stay on the instance: upstream webERP links to them without a login, so this image does not serve them over the web. Copy them with scp from /var/www/weberp/companies/weberp/reports/ when you need them.

Step 10: Changing passwords

• webERP admin password: sign in as admin, open Setup, Users Maintenance, Edit on the admin row, enter a new password and save the record. Then update or delete WEBERP_ADMIN_PASSWORD in /root/weberp-credentials.txt so it does not hold an old password.
• Give each person their own webERP user rather than sharing admin. After five wrong passwords in one session webERP blocks the account until an administrator unblocks it in Users Maintenance.
• MariaDB password: only change it together with $DBPassword in /var/www/weberp/config.php, then restart PHP-FPM.

Step 11: Backup and maintenance

The company database lives in MariaDB (/var/lib/mysql), and logos, part pictures and generated files live under /var/www/weberp/companies/weberp. The simplest backup is an EBS snapshot of the root volume. For a consistent file level copy while webERP is running:

sudo mariadb-dump --single-transaction --routines --triggers weberp | gzip > <backup-dir>/weberp-$(date +%F).sql.gz
sudo tar -czf <backup-dir>/weberp-companies-$(date +%F).tar.gz -C /var/www/weberp companies/weberp

Operating system security updates install automatically; run sudo apt-get update && sudo apt-get upgrade to apply everything else. nginx, PHP-FPM and MariaDB restart cleanly and webERP keeps all of its data.

Step 12: Security recommendations

• Allow port 22 from your admin network only, and ports 80 and 443 only from the networks your users work from. Never open 3306.
• Use your own DNS name and a certificate your users' browsers trust (Step 8).
• Give each person their own webERP user and role, and change the admin password if it may have been shared (Step 10).
• Keep the operating system patched, and snapshot the root volume regularly.

Support and licensing

webERP is open source under the GNU General Public License version 2; there is no per user or per CPU licence fee. The AMI price covers cloudimg's hardening, first boot setup and support.

• Email: support@cloudimg.co.uk
• Website: https://www.cloudimg.co.uk
• Support: 24/7, with a 24 hour response SLA