Installation guide
How to install and look after Contractor OS on your server. One installation serves one company. On Standard we help you install it remotely, on Plus we handle it fully.
- Before you start
- Set up the .env file
- Start it
- First-run setup
- Backup and restore
- Updates and rollback
- Logs and monitoring
- Known gaps
Before you start
Prepare one Linux server (a small VPS is enough: 2 vCPU, 2 GB RAM) with Docker and the Compose plugin, and a domain you control. Create an A record (and AAAA if the server has IPv6) pointing at the server's public IP. In the firewall, open only 22 (SSH), 80 and 443. The database and the app are not exposed.
Set up the .env file
Create a .env file from the example that comes with the package, then fill in DOMAIN, ACME_EMAIL, POSTGRES_PASSWORD and NUXT_SESSION_PASSWORD. Generate the passwords with the commands below. SETUP_TOKEN (optional) makes the first-run setup page ask for a code, and COMPANY_CODE is the initials used in project, PO and invoice numbers. Keep a copy of .env somewhere safe: losing POSTGRES_PASSWORD or changing NUXT_SESSION_PASSWORD has consequences (the second signs everyone out).
openssl rand -hex 24 # POSTGRES_PASSWORD
openssl rand -hex 32 # NUXT_SESSION_PASSWORDStart it
Pull the image and start it. The PostgreSQL database runs in the same Docker Compose setup, and the app applies its database migrations on start. Wait for the HTTPS certificate to be issued, then open your domain.
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml logs -f caddy appFirst-run setup
The production database starts empty, with no demo accounts. While there is no user, your domain shows the setup page. Pick Cepat (company name, the Owner account, company size) or Lengkap (also logo, company code, address and bank details, PPN and PO limits, approval rules, and up to five team accounts). If the server is reachable before you get to it, set SETUP_TOKEN. Without a browser, create the Owner from the command line:
docker compose -f docker-compose.prod.yml exec app ./erp create-user --email [email protected] --name "Full Name" --role ownerOptional features (modules) can be switched on or off any time under Pengaturan, Modul. Nothing is deleted when a module is switched off.
Backup and restore
The backup service writes a daily database dump to the backups folder (7 daily, 4 weekly, 6 monthly). That is the same server, so also copy it off the machine. Owner and Admin can also make and download backups from the Backup Database page. Site photos and attachments are not in the database backups. Archive them with this command, then copy both files off the server:
docker compose -f docker-compose.prod.yml exec app ./erp backupA restore replaces ALL current data and signs everyone out. Stop the app first:
docker compose -f docker-compose.prod.yml stop app
docker compose -f docker-compose.prod.yml run --rm app ./erp restore /data/backups/erp-<stamp>.sql.gz --yes
docker compose -f docker-compose.prod.yml up -d appUpdates and rollback
Read the CHANGELOG for every version between yours and the new one, then make a backup. Put the new version in ERP_VERSION in .env, pull, and restart. Migrations run automatically. When the database already has data and the new version brings migrations, the app first writes a safety backup and stops if that backup fails, so nothing is half-changed.
# ERP_VERSION=<new version> in .env
docker compose -f docker-compose.prod.yml pull app
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml logs -f appRolling back means restoring the safety backup, so anything entered after the update is lost. Do a restore drill on a spare machine before go-live, then every quarter.
Logs and monitoring
Every API request is one JSON line in the log. /api/live answers while the process runs, and /api/health also checks the database: point an uptime monitor at the second one.
docker compose -f docker-compose.prod.yml logs -f appKnown gaps
There is no password reset by email and no MFA. An Owner or Admin resets passwords from the user panel. Site photos are stored on local disk, so the server needs a persistent disk.
Need help installing? Write to us through the form below.