Installation Guide

This guide provides detailed instructions for installing and configuring POS Nest API in your development or production environment.

Prerequisites

Before installing POS Nest API, ensure you have the following prerequisites:

Node.js

Version 18.x or higherDownload from nodejs.org

PostgreSQL

Version 12 or higherOr use Supabase for hosted PostgreSQL

Package Manager

npm, yarn, or pnpmComes with Node.js (npm) or install separately

Supabase Account

Free tier availableSign up at supabase.com

This guide assumes you have basic knowledge of Node.js, TypeScript, and REST APIs.

Installation Steps

1. Clone the Repository

First, clone the POS Nest API repository:

git clone <repository-url>
cd pos-nest

2. Install Dependencies

Install all required npm packages using your preferred package manager:

npm install

This will install the following key dependencies:

@nestjs/core (v11.0.1) - NestJS framework core
@nestjs/typeorm (v11.0.0) - TypeORM integration for NestJS
@supabase/supabase-js (v2.97.0) - Supabase client library
typeorm (v0.3.28) - ORM for TypeScript and JavaScript
pg (v8.18.0) - PostgreSQL client for Node.js
class-validator (v0.14.3) - Validation decorators
class-transformer (v0.5.1) - Object transformation
date-fns (v4.1.0) - Date utility library

3. Environment Configuration

Create a .env file in the root directory of the project:

touch .env

Add the following environment variables to your .env file:

.env

# Server Configuration
PORT=3000

# PostgreSQL Database Configuration
DATABASE_HOST=your-database-host.supabase.co
DATABASE_PORT=5432
DATABASE_USER=postgres
DATABASE_PASS=your-database-password
DATABASE_NAME=postgres

# Supabase Configuration
SUPABASE_URL=https://your-project-id.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPABASE_BUCKET=products

Environment Variables Explained

PORT

number

default:"3000"

The port number where the API server will listen. Configured in src/main.ts:21

DATABASE_HOST

string

required

PostgreSQL database host. For Supabase, find this in your project settings under Database > Connection String

DATABASE_PORT

number

default:"5432"

PostgreSQL port (default is 5432)

DATABASE_USER

string

required

Database username (usually “postgres” for Supabase)

DATABASE_PASS

string

required

Database password. Set during Supabase project creation

DATABASE_NAME

string

required

Database name (usually “postgres” for Supabase)

SUPABASE_URL

string

required

Your Supabase project URL. Found in Supabase Dashboard > Settings > API > Project URL

SUPABASE_SERVICE_ROLE_KEY

string

required

Supabase service role key for admin operations. Found in Supabase Dashboard > Settings > API > service_role key

SUPABASE_BUCKET

string

default:"products"

Supabase Storage bucket name for product images. Used in src/upload-image/upload-image.service.ts:14

Security Best Practices:

Never commit your .env file to version control
The .env file is already included in .gitignore
Keep your SUPABASE_SERVICE_ROLE_KEY secret - it bypasses Row Level Security
Use environment-specific .env files for development, staging, and production

4. Supabase Setup

If you’re using Supabase (recommended), follow these steps:

Create a Supabase Project

Go to supabase.com and sign in
Click “New Project”
Enter your project details and set a strong database password
Wait for the project to be provisioned (usually 1-2 minutes)

Get Your Connection Details

In your Supabase Dashboard:

Go to Settings > Database
Find the “Connection string” section
Copy the connection parameters for your .env file

Alternatively, go to Settings > API:

Copy the URL for SUPABASE_URL
Copy the service_role key for SUPABASE_SERVICE_ROLE_KEY

Create a Storage Bucket

For product image uploads:

Go to Storage in the Supabase Dashboard
Click “New bucket”
Name it products (or match your SUPABASE_BUCKET env var)
Set it to Public if you want images to be publicly accessible
Click “Create bucket”

Configure Authentication

The API uses Supabase Authentication:

Go to Authentication > Settings
Configure your auth settings as needed
The API uses email/password authentication by default
You can enable additional providers if desired

5. Database Setup

The application uses TypeORM with synchronization enabled for development:

// From src/config/typeorm.config.ts
{
  type: 'postgres',
  ssl: {
    rejectUnauthorized: false,
  },
  synchronize: true,  // Auto-creates tables based on entities
  entities: [join(__dirname, '..', '**', '*.entity.{ts,js}')],
}

Production Warning: The synchronize: true option automatically creates/updates database tables based on your entities. This is convenient for development but should be disabled in production. Use migrations instead.To disable synchronization for production, set synchronize: false in src/config/typeorm.config.ts:19

Database Entities

The following tables will be automatically created when you start the application:

Category - Product categories (src/categories/entities/category.entity.ts)
Product - Products with inventory (src/products/entities/product.entity.ts)
Transaction - Sales transactions (src/transactions/entities/transaction.entity.ts)
Coupon - Discount coupons (src/coupons/entities/coupon.entity.ts)

Optional: Seed Database

If your project includes a seeder script:

npm run seed

6. Running the Application

Development Mode

Run the application in development mode with hot reload:

npm run start:dev

The API will start on http://localhost:3000 (or your configured PORT).

Production Mode

For production deployment:

# Build the application
npm run build

# Start the production server
npm run start:prod

Debug Mode

To run with debugging enabled:

npm run start:debug

This starts the application with the Node.js inspector on port 9229.

7. Verify Installation

Once the application is running, verify the installation:

curl http://localhost:3000

You should receive a response from the API. Try the signup endpoint to ensure everything is working:

curl -X POST http://localhost:3000/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "password123"}'

Application Configuration

CORS Configuration

CORS is configured in src/main.ts:9-14 with the following settings:

app.enableCors({
  origin: true,  // Allows all origins in development
  methods: 'GET,HEAD,PUT,PATCH,POST,DELETE,OPTIONS',
  allowedHeaders: 'Content-Type,Authorization',
  credentials: true,
});

For production, you should restrict the origin to your specific frontend domain(s) instead of allowing all origins.

Global Validation

The application uses global validation pipes configured in src/main.ts:15-19:

app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,  // Strips properties not defined in DTOs
  }),
);

This ensures all incoming requests are validated against their respective DTOs using class-validator decorators.

Static Assets

Static files (like uploaded images) are served from the public directory:

app.useStaticAssets(join(__dirname, '..', 'public'));

Create a public directory in the root if it doesn’t exist:

mkdir -p public

Testing

Run the test suite to ensure everything is set up correctly:

npm run test

Additional Scripts

Other useful commands from package.json:

# Format code with Prettier
npm run format

# Lint code with ESLint
npm run lint

# Build for production
npm run build

# Run tests in watch mode
npm run test:watch

Troubleshooting

SSL/TLS connection errors

If you encounter SSL connection errors with your database, verify that SSL is properly configured in src/config/typeorm.config.ts:14-16:

ssl: {
  rejectUnauthorized: false,
},

For Supabase, SSL is required and this configuration should work by default.

Module not found errors

If you get “Cannot find module” errors:

Delete node_modules and lock file:
```
rm -rf node_modules package-lock.json
```
Reinstall dependencies:
```
npm install
```
Clear TypeScript build cache:
```
rm -rf dist
```

TypeORM synchronization issues

If tables aren’t being created automatically:

Verify synchronize: true in src/config/typeorm.config.ts:19
Check database connection credentials
Ensure your database user has CREATE TABLE permissions
Check the console for any TypeORM error messages

Supabase authentication not working

Verify your Supabase configuration:

Ensure you’re using the service_role key, not the anon key
Check that your SUPABASE_URL includes the full URL with https://
Verify the Supabase project is active in the dashboard
Check that email authentication is enabled in Supabase Auth settings

Next Steps

Now that you have POS Nest API installed and running:

Quickstart

Make your first API calls

Authentication

Learn about auth and authorization

API Reference

Explore all available endpoints

Deployment

Deploy to production

Get Started

Core Concepts

Guides

Installation

Installation Guide

Prerequisites

Node.js

PostgreSQL

Package Manager

Supabase Account

Installation Steps

1. Clone the Repository

2. Install Dependencies

3. Environment Configuration

Environment Variables Explained

4. Supabase Setup

5. Database Setup

Database Entities

Optional: Seed Database

6. Running the Application

Development Mode

Production Mode

Debug Mode

7. Verify Installation

Application Configuration

CORS Configuration

Global Validation

Static Assets

Testing

Additional Scripts

Troubleshooting

Next Steps

Quickstart

Authentication

API Reference

Deployment

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Installation Guide

​Prerequisites

Node.js

PostgreSQL

Package Manager

Supabase Account

​Installation Steps

​1. Clone the Repository

​2. Install Dependencies

​3. Environment Configuration

​Environment Variables Explained

​4. Supabase Setup

​5. Database Setup

​Database Entities

​Optional: Seed Database

​6. Running the Application

​Development Mode

​Production Mode

​Debug Mode

​7. Verify Installation

​Application Configuration

​CORS Configuration

​Global Validation

​Static Assets

​Testing

​Additional Scripts

​Troubleshooting

​Next Steps

Quickstart

Authentication

API Reference

Deployment

Build docs developers (and LLMs) love

Installation Guide

Prerequisites

Installation Steps

1. Clone the Repository

2. Install Dependencies

3. Environment Configuration

Environment Variables Explained

4. Supabase Setup

5. Database Setup

Database Entities

Optional: Seed Database

6. Running the Application

Development Mode

Production Mode

Debug Mode

7. Verify Installation

Application Configuration

CORS Configuration

Global Validation

Static Assets

Testing

Additional Scripts

Troubleshooting

Next Steps