Installation guides

Three ways to run Laundrix: on your own computer for development, on Vercel with a Neon database, or on a server with Docker. Whichever you use, finish with the production checklist.

Requirements

Node.js 20.9 or newer (22 LTS recommended) and npm
PostgreSQL 14 or newer (16 recommended)
Git (optional if you downloaded a ZIP)
For production: a domain with HTTPS. On serverless hosts such as Vercel, an S3-compatible storage bucket.
Optional: an SMTP account, Paystack keys, and SMS, WhatsApp or AI provider keys

A. On your computer (Windows Command Prompt)

Install Node.js, PostgreSQL (keep port 5432 and remember the postgres password) and Git.
Make psql available for the current window: set PATH=%PATH%;C:\Program Files\PostgreSQL\16\bin (use your installed version number).
Open the project folder and install dependencies:
```
npm install
```

Create the database user and databases (you are asked for the postgres password each time):

psql -U postgres -c "CREATE USER laundry WITH PASSWORD 'laundry' CREATEDB;"
psql -U postgres -c "CREATE DATABASE laundry_dev OWNER laundry;"
psql -U postgres -c "CREATE DATABASE laundry_test OWNER laundry;"

Create your settings file and edit it:
```
copy .env.example .env
notepad .env
```
Set DATABASE_URL, APP_SECRET (32+ random characters) and JOBS_SECRET. Generate a secret with node -e "console.log(require('crypto').randomBytes(32).toString('hex'))".
Create the tables, then (optionally) load the demo company:
```
npx prisma migrate deploy
npm run db:seed
```
Start the app and open http://localhost:3000:
```
npm run dev
```

On macOS or Linux the steps are the same; use cp instead of copy and your own PostgreSQL tooling. The seed creates a fictional company, “FreshPress Laundry”, so you can explore with realistic data. Choose it from the company list on the sign-in page.

Never seed production

The demo seed is for development and demos. It refuses to run in production unless forced.

Windows troubleshooting

Problem	Fix
`psql is not recognized`	Add the PostgreSQL bin folder to PATH (step 2).
password authentication failed for user	The password in DATABASE_URL must match the one used in CREATE USER. If you forgot the postgres password, reset it in pg_hba.conf (temporarily set local connections to trust, restart the service, run ALTER USER, then restore).
Can’t reach database server	Start the PostgreSQL service (services.msc) and check the port.
EPERM during prisma generate	Stop npm run dev (it locks the engine file) and run it again.
Port 3000 in use	Run `npx next dev -p 3001` and set `APP_URL` to match.
Company list shows a code box instead of a drop-down	Run npx prisma migrate deploy and npx prisma generate, then restart. The sign-in page explains the cause.
Camera scanning does not work	Browsers allow the camera only on https:// or localhost. Use a USB or Bluetooth barcode scanner, or serve over HTTPS.

B. Vercel with Neon

Neon: create a project. Copy the pooled connection string (host contains -pooler) and the direct one.
Vercel: import the repository and add environment variables: DATABASE_URL (pooled string with &pgbouncer=true&connection_limit=1 appended), APP_URL (your https address), APP_SECRET, JOBS_SECRET and CRON_SECRET (same value as JOBS_SECRET), SUPPORT_EMAIL.
File storage: create a bucket (Cloudflare R2 is simple) and set STORAGE_DRIVER=s3, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY and, for R2, B2 or MinIO, S3_ENDPOINT. Without this, uploads are refused on Vercel instead of being lost.

Migrate from your computer against the direct string:

set DATABASE_URL=postgresql://USER:PASSWORD@ep-xxxx.region.aws.neon.tech/neondb?sslmode=require
npx prisma migrate deploy

Scheduled jobs: vercel.json calls /api/jobs/run daily. Hobby plans allow daily schedules only; on a paid plan change the schedule to */15 * * * *.
Deploy and open /api/health; it should return {"status":"ok"}.

C. Docker on a server

Copy .env.example to .env and fill it in (set APP_URL to your https address).
Start the stack:
```
docker compose up --build -d
```
Put a reverse proxy with HTTPS (Caddy or Nginx) in front of the app.
Mount a persistent volume for UPLOAD_DIR, or use STORAGE_DRIVER=s3.
Run npx prisma migrate deploy on every release.
Schedule the jobs endpoint every 15 minutes:
```
curl -X POST -H "Authorization: Bearer $JOBS_SECRET" https://YOUR-DOMAIN/api/jobs/run
```
On Windows use Task Scheduler with the schtasks command in the setup guide.

Key settings

Variable	Purpose
`DATABASE_URL`	PostgreSQL connection string
`APP_URL`	Public address, used in emails, payment callbacks and links
`APP_SECRET`	32+ random characters. Encrypts company provider keys and derives delivery OTPs. Changing it later invalidates stored provider keys.
`JOBS_SECRET`	Authorises the scheduled-jobs endpoint (CRON_SECRET also works)
`STORAGE_DRIVER, S3_*`	File storage: local disk or an S3-compatible bucket
`SMTP_*`	Email for password reset and notifications
`PAYSTACK_*`	Online card payments and platform billing
`SUPPORT_EMAIL, PARENT_COMPANY_*`	Shown in footers, About and legal pages

The full list is in .env.example. At startup in production the server logs a warning for each important setting that is missing.

After installing

Open the site and choose Start free trial to create your first company, then follow the guided setup.
Create the platform admin who operates the whole platform: npm run admin:create -- you@company.com "Your Name" (you are asked for a password; sign in at /platform/login).
Work through the production checklist in DEPLOYMENT.md: HTTPS, backups with a restore test, Paystack webhook, a password-reset email test, an upload that survives a redeploy, reviewed legal pages and real plan prices.