← Back to Contractor OS

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.

  1. Before you start
  2. Set up the .env file
  3. Start it
  4. First-run setup
  5. Backup and restore
  6. Updates and rollback
  7. Logs and monitoring
  8. 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_PASSWORD

Start 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 app

First-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 owner

Optional 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 backup

A 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 app

Updates 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 app

Rolling 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 app

Known 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.

Contact - answered 09:00–21:00 WIB

Fastest on WhatsApp.

Tell us about your project in a few lines. We reply with a demo link, the price list and answers to your questions.

samapp - Contractor OS

Hi, I run an interior contracting business. Can I use it for 3 projects at once?

Yes, users and projects are unlimited. Here is the demo link, you can try it right away without signing up. Shall I send the price list too?

Sure, the subscription please.

An example conversation, not a real one.
prefer email?[email protected]
prefer telegram?@samappdev

Or send it through the form

About

samapp is a software studio in Indonesia. One developer owns your project from start to launch, not a rotating team. The code is in your repository from day one, so you are never locked in to us. Scope, timeline, and price are written down before work begins.

Portrait of Sultan Atha Maulana, founder of samapp
Sultan Atha MaulanaFounder / Developer

Built Contractor OS solo: seven roles, BOQ, Gantt, approvals, and invoicing, all of which you can try right now. Kotlin, Nuxt, and Node. Direct, and easy to work with.

GitHub
© 2026 samappSet in JetBrains Mono and Geist