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
- Run it on a server: HTTPS, backups and settings for real use
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 -dLinux
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 -dOn 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.
- Create a company, for example
demo01with the display name “Demo Company 01”, and switch to it with Ctrl+O. - Add a Job Queue line with Object ID to Run
901and ParameterSMALL(20 customers, about 540 ledger entries). - 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 -dThe settings are in prod.env, which is not tracked by git because it holds secrets:
| Setting | What it does |
|---|---|
APP_VERSION | The release to run. |
JWT_SECRET | Signs sessions. Generate it once with openssl rand -hex 32. Without it, every restart logs all users out. |
POSTGRES_PASSWORD | Password of the database user. It is only applied when the database is first created, so choose a strong one now. |
PUBLISH_HOST | Where 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 10mNever 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
| Service | Published |
|---|---|
| nginx | 80 and 443 on all interfaces. This is the way in for users; port 80 redirects to 443. |
| backend | PUBLISH_HOST:8080 |
| frontend | PUBLISH_HOST:3000 |
| database | 127.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 5mDatabase 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>&1Backups 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.