Backend — Environment & Configuration

Installing dependencies, .env setup, and database initialization

Step 1 — Install Backend Dependencies

In the VS Code terminal with pos-backend open, run:

This downloads all required packages. It takes 1–3 minutes. Wait for the cursor to return.

Step 2 — Create the .env File

In the VS Code file sidebar, right-click in an empty area › New File. Name it exactly: .env (note the leading dot — it is intentional).

Copy every variable from the table below and fill in your values.

Full .env Variable Reference

Variable	Description	Example / Format
NODE_ENV	Runtime environment mode	development	Required
PORT	Backend HTTP server port	5000	Required
DATABASE_URL	PostgreSQL connection string	postgresql://user:pass@host/db	Required
DIRECT_URL	Direct DB URL (Prisma migrations)	postgresql://user:pass@host/db	Required
REDIS_URL	Redis connection string	redis://localhost:6379	Required
JWT_ACCESS_SECRET	Access token signing secret	64-char hex string	Required
JWT_REFRESH_SECRET	Refresh token signing secret	64-char hex string (different)	Required
JWT_ACCESS_EXPIRES_IN	Access token expiry	15m	Required
JWT_REFRESH_EXPIRES_IN	Refresh token expiry	7d	Required
CLOUDINARY_CLOUD_NAME	Cloudinary cloud identifier	my-cloud-name	Required
CLOUDINARY_API_KEY	Cloudinary API key	123456789012345	Required
CLOUDINARY_API_SECRET	Cloudinary API secret	abc123xyz...	Required
FRONTEND_URL	Frontend origin — used for CORS	http://localhost:3000	Required
LOG_LEVEL	Pino log verbosity	info	Optional
RATE_LIMIT_WINDOW_MS	Rate limit window in milliseconds	900000	Optional
RATE_LIMIT_MAX	Max requests per window	100	Optional

Generating Secure JWT Secrets

Run this command twice in any terminal. Use the first output for JWT_ACCESS_SECRET and the second for JWT_REFRESH_SECRET. They must be different values.

Getting Your PostgreSQL Database URL

Neon.tech (Recommended)

Go to neon.tech and create a free account. Click Create Project.
After creation, click Connection Details and copy the Connection String.
It looks like: postgresql://user:pass@host.neon.tech/dbname?sslmode=require
Use this exact string for both DATABASE_URL and DIRECT_URL.

Local PostgreSQL

Download from postgresql.org/download and install with defaults. Create a database named posdb:

Your local URL will be:

Getting Your Redis URL

Upstash (Recommended)

Go to upstash.com, create a free account, and create a Redis database. Copy the Redis URL from the dashboard — it starts with rediss://.

Local Redis

Windows: Install Memurai from memurai.com
macOS: brew install redis then brew services start redis
Linux: sudo apt install redis-server then sudo systemctl start redis
Local URL: redis://localhost:6379

Getting Cloudinary Credentials

Go to cloudinary.com and create a free account.
From your Dashboard, copy the Cloud Name, API Key, and API Secret.
Paste each into the corresponding .env variable.

Step 3 — Database Initialization

Run these four commands in order in your backend terminal. Do not skip any.

Command	What It Does
`npm run db:generate`	Generates the Prisma client — the type-safe database access layer
`npm run db:migrate`	Creates all tables in the database. When prompted, enter: initial_setup
`npm run db:seed`	Populates demo data: products, categories, customers, a sample tenant
`npm run db:seed:super-admin`	Creates the platform Super Admin account. Save the credentials shown

Note

Run db:migrate only once on a fresh database. For future code updates use npm run db:migrate:prod — it applies only new changes without prompts or data loss.