Installation

Prerequisites

NodeDR POS runs as a Docker Compose stack. You need:

• Docker Engine with the Compose v2 plugin (bundled in Docker Desktop for Mac/Windows, and in Docker Engine 24+ on Linux). Run docker compose version to check — you need v2.x, not the legacy docker-compose command.
• Git to clone the repository.
• Any modern 64-bit machine: Linux (x86_64 or ARM64), macOS (Intel or Apple Silicon), or Windows with WSL2.

No Node.js, no database setup, no config files — Docker handles everything.

One-command install (recommended)

git clone https://github.com/Raktim94/nodedr-pos.git && cd nodedr-pos && ./install.sh

The install.sh script does the following automatically:

1. Checks that Docker and Compose are installed and healthy.
2. Runs docker compose build — builds both the frontend and backend images from source using multi-stage node:24-alpine builds. First run takes 3–5 minutes; subsequent runs are cached and take under a minute.
3. Runs docker compose up -d — starts both containers in the background and creates the nodedr-pos_data named volume on first run.
4. Polls the backend health endpoint until it reports healthy.
5. Prints http://localhost:1994 and tells you it’s ready.

Re-run ./install.sh any time to rebuild after pulling updates — it handles everything safely.

Manual install (step by step)

If you prefer to run each step yourself or the script doesn’t fit your environment:

# 1. Clone the repository
git clone https://github.com/Raktim94/nodedr-pos.git
cd nodedr-pos

# 2. Build both images (node:24-alpine multi-stage)
#    First run: 3–5 minutes. Subsequent runs: fast (cached).
docker compose build

# 3. Start the stack in the background
#    Creates the nodedr-pos_data volume automatically on first run.
docker compose up -d

# 4. (Optional) Watch logs until you see "listening on port 4000"
#    and the Next.js ready message
docker compose logs -f

# 5. Open in your browser
#    http://localhost:1994

First launch — guided onboarding

When you open the app for the first time, a setup wizard runs before you see the dashboard. You will be asked for:

1. Admin account — your full name, email address, and a password. This becomes the owner/admin login.
2. Shop setup — shop name, address, currency symbol, and a low-stock threshold. You can optionally enter your GSTIN here; GST can be toggled on/off in Settings later.

After completing onboarding you land on the dashboard, ready to add products and start selling.

Changing the port

The default port is 1994. To change it, edit docker-compose.yml:

# In docker-compose.yml, under the frontend service:
ports:
  - "2000:3000"   # Change 1994 to any available port on the left side

# Also update FRONTEND_ORIGIN under the backend service to match:
environment:
  FRONTEND_ORIGIN: http://localhost:2000

The two values must agree — FRONTEND_ORIGIN is used for CORS so the backend only accepts requests from the correct origin.

Accessing from other devices on the LAN

Any device on the same network (a counter tablet, a second PC, a phone) can open the register by navigating to:

http://<IP-of-the-machine-running-Docker>:1994

Find your machine’s LAN IP with ip addr (Linux) or ipconfig (Windows) or System Preferences → Network (macOS). No per-device install is needed — the browser is the client.

Stopping and restarting

# Stop containers (data is preserved in the volume)
docker compose down

# Start again
docker compose up -d

# Stop AND delete all data (use only to start fresh)
docker compose down -v

Updating to a new version

cd nodedr-pos
git pull
docker compose up -d --build

Or re-run ./install.sh — it does exactly the same thing. Your data in the volume is untouched.