Installation: Linux and macOS

This guide installs GoEasyERP on Linux or macOS, either as a trial on your own computer or on a server. For Windows see Installation: Windows.

GoEasyERP runs in Docker, with its data in a PostgreSQL database. You need about 4 GB of free memory and 10 GB of disk.

Try it on your own computer

macOS

Install Docker Desktop and start it. Then, in Terminal:

mkdir ~/goeasyerp && cd ~/goeasyerp
curl -o docker-compose.yml https://raw.githubusercontent.com/hansjlachmann/goeasyerp/main/docker-compose.local.yml
open -e docker-compose.yml      # replace JWT_SECRET with any long random text, save
docker compose up -d

Linux

Install Docker Engine, for example on Ubuntu, and then start GoEasyERP:

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER   # log out and in again
mkdir ~/goeasyerp && cd ~/goeasyerp
curl -o docker-compose.yml https://raw.githubusercontent.com/hansjlachmann/goeasyerp/main/docker-compose.local.yml
nano docker-compose.yml         # replace JWT_SECRET with any long random text
docker compose up -d

On both systems, wait 2–3 minutes, then open http://localhost:8000 and create the first user.

Stop GoEasyERP with docker compose stop and start it again with docker compose start, in the goeasyerp folder.

Never run docker compose down -v. It deletes the database.

The trial installation is reachable from this computer only. To open it from other computers, change the line "127.0.0.1:8000:80" to "8000:80", set ORIGIN to http://<computer name>:8000 and open port 8000 in the firewall. For anything several people use, follow the server installation below instead.

Upgrade: download docker-compose.local.yml again over docker-compose.yml, keep your JWT_SECRET, then run docker compose pull and docker compose up -d.

Demo data

To look around with sample data, GoEasyERP can fill a company with demo customers and a year of customer ledger entries.

  1. Create a company, for example demo01 with the display name “Demo Company 01”, and switch to it with Ctrl+O.
  2. Add a Job Queue line with Object ID to Run 901 and Parameter SMALL (20 customers, about 540 ledger entries).
  3. Run it with F9.

Never run it in a company with real data. If the company already has customers, it deletes the company’s data first.

Run it on a server

For real use, run GoEasyERP on a Linux server with Docker and git. It serves users over HTTPS through nginx on ports 80 and 443, and uses the same pre-built images as the trial installation.

First installation

git clone https://github.com/hansjlachmann/goeasyerp.git ~/openerp && cd ~/openerp
cp prod.env.example prod.env && chmod 600 prod.env
# edit prod.env: APP_VERSION, JWT_SECRET, POSTGRES_PASSWORD
./generate-cert.sh            # or put your own certificate into certs/
scripts/prod.sh pull && scripts/prod.sh up -d

The settings are in prod.env, which is not tracked by git because it holds secrets:

SettingWhat it does
APP_VERSIONThe release to run.
JWT_SECRETSigns sessions. Generate it once with openssl rand -hex 32. Without it, every restart logs all users out.
POSTGRES_PASSWORDPassword of the database user. It is only applied when the database is first created, so choose a strong one now.
PUBLISH_HOSTWhere the backend and frontend ports are published. The default, 127.0.0.1, means this host only.

prod.env.example lists the optional settings as well.

Always use scripts/prod.sh instead of plain docker compose. It passes prod.env and docker-compose.prod.yml for you:

scripts/prod.sh ps
scripts/prod.sh logs backend --since 10m

Never run docker compose down -v or docker volume prune, and do not rename or move the folder you cloned into. The database lives in a volume named after that folder, so a renamed folder gets a new, empty database.

Ports

ServicePublished
nginx80 and 443 on all interfaces. This is the way in for users; port 80 redirects to 443.
backendPUBLISH_HOST:8080
frontendPUBLISH_HOST:3000
database127.0.0.1:5432. Use an SSH tunnel for admin tools.

Upgrading the server

Take a backup, set the new APP_VERSION in prod.env and pull:

cd ~/openerp
scripts/backup.sh
scripts/prod.sh pull && scripts/prod.sh up -d
scripts/prod.sh logs backend --since 5m

Database migrations run automatically at startup. To roll back, set the previous APP_VERSION and run pull and up -d again. If a migration changed data in a way the old version cannot read, restore the backup you took before upgrading.

Backups

scripts/backup.sh dumps the database into ~/backups and deletes automatic backups older than 14 days. To run it daily at 02:15, add this with crontab -e:

15 2 * * * $HOME/openerp/scripts/backup.sh >> $HOME/backups/backup.log 2>&1

Backups on the same disk do not survive a disk failure, so copy them to another machine as well. Restoring, restoring into a scratch database to inspect a backup, changing the database password and the JWT secret are described in the operations guide on GitHub.