Install it and get your first employee logged in

This is the abbreviated version. The complete reference, including deployment topologies and backup strategy, is docs/self-hosting.md in the repository.

What you need

• Node.js 20 or later and npm.
• PostgreSQL 14 or later. Managed (Neon, Supabase, RDS) or your own — the app speaks standard Postgres.
• Somewhere to run it. Your own machine, a cloud server, or Vercel. Nothing here is Vercel-specific except the pre-declared cron schedule.
• A domain with HTTPS. Not optional. This application handles NRIC numbers and salary data.

1. Clone and install

git clone https://github.com/on-the-ground-ai/otg-hrms.git
cd otg-hrms
npm install

2. Configure

cp .env.example .env.local

Two variables are mandatory. DATABASE_URL is your Postgres connection string. AUTH_SECRET signs session tokens — generate a fresh one, do not reuse a secret from anywhere else:

openssl rand -base64 32

Generate NRIC_ENCRYPTION_KEY the same way. Without it the NRIC field is unavailable, which is the safe failure mode — the app refuses to store an identifier it cannot encrypt.

3. Create the schema

npm run db:migrate

This runs every migration in order and then the reference-data seeds: default leave types, and Singapore public holidays for 2026 and 2027. It is idempotent — running it twice is safe, and it is how you apply upgrades later.

4. Start it

npm run dev     # development

npm run build   # production
npm start

5. Create your company

Go to /signup. This is the only unauthenticated write path in the application besides password reset, and it is rate-limited per IP. Creating a company gives you:

• The company record.
• Your account, as super admin — the highest role.
• A default set of leave types you can rename, deactivate or add to.

6. Add people

Use Admin → Onboarding rather than the plain create form: the wizard also sets up approvers and sends the welcome email. Each new joiner gets a one-time activation link and sets their own password. You never send anyone a password.

7. Before you invite the company

1. 1Check the holiday calendar under Admin → Settings. Wrong holidays mean wrong leave deductions, and it is the mistake people notice.
2. 2Check the leave entitlements for two or three employees with different join dates against what you actually promised them.
3. 3Send yourself a leave request and approve it from the email link, to confirm outbound email and the approval tokens work end to end.
4. 4Upload a receipt on a test claim, to confirm file storage is configured.
5. 5Take a database backup and restore it somewhere else. An untested backup is a hypothesis, not a backup.

Optional pieces

Everything below is off by default and the system runs without it. Email is the one you will actually want.