Skip to main content
This guide covers everything you need to install and configure the Kioto Teteria Backend for development or production environments.

​
System Requirements

​
Required Software

Node.js

Version 18 or higherDownload from nodejs.org

PostgreSQL

Version 12 or higherDownload from postgresql.org

pnpm

Latest versionInstall: npm install -g pnpm

Git

Version 2.0 or higherDownload from git-scm.com

​
Installation Steps

​
1. Clone the Repository

git clone <your-repository-url>
cd backend

​
2. Install Dependencies

The project uses pnpm for package management. Install all dependencies: 
pnpm install
This will install the following key dependencies: Core Framework:
  • @nestjs/core - NestJS framework
  • @nestjs/common - Common utilities and decorators
  • @nestjs/platform-express - Express adapter
Database:
  • @prisma/client - Prisma ORM client
  • @prisma/adapter-pg - PostgreSQL adapter
  • pg - PostgreSQL driver
Authentication:
  • @nestjs/jwt - JWT authentication
  • @nestjs/passport - Passport integration
  • passport-jwt - JWT strategy
  • bcrypt - Password hashing
Validation:
  • class-validator - DTO validation
  • class-transformer - Object transformation

​
3. Configure Environment Variables

Create a .env file in the project root:
.env
# Database Configuration
DATABASE_URL="postgresql://username:password@localhost:5432/kioto_teteria?schema=public"

# JWT Configuration
JWT_SECRET="your-secure-random-jwt-secret-key-change-this-in-production"

# Server Configuration
PORT=3000
NODE_ENV=development
DATABASE_URLPostgreSQL connection string format:
postgresql://[user]:[password]@[host]:[port]/[database]?schema=public
  • user - Database username
  • password - Database password
  • host - Database host (localhost for local development)
  • port - Database port (default: 5432)
  • database - Database name
JWT_SECRETSecret key for signing JWT tokens. Must be:
  • At least 32 characters long
  • Random and unpredictable
  • Different for each environment
Generate a secure secret:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
PORTPort number for the HTTP server (default: 3000)NODE_ENVEnvironment mode: development, production, or test

​
4. Database Setup

​
Create the Database

If the database doesn’t exist, create it: 
# Using psql
psql -U postgres -c "CREATE DATABASE kioto_teteria;"

# Or using createdb
createdb -U postgres kioto_teteria

​
Generate Prisma Client

Generate the Prisma Client based on your schema: 
pnpm run prisma:generate
This reads the schema from prisma/schema.prisma and generates TypeScript types and client methods.

​
Run Migrations

Apply database migrations to create all tables: 
pnpm run prisma:migrate
This creates the following database schema:
Stores administrator accounts for backend management.
model Admin {
  id           Int     @id @default(autoincrement())
  email        String  @unique
  passwordHash String
  isActive     Boolean @default(true)
  role         String  @default("ADMIN")
}
Product categories for organizing the menu.
model Category {
  id        Int       @id @default(autoincrement())
  name      String
  slug      String    @unique
  isActive  Boolean   @default(true)
  createdAt DateTime  @default(now())
  products  Product[]
}
Tea and beverage products available for order.
model Product {
  id          Int      @id @default(autoincrement())
  name        String
  slug        String   @unique
  description String
  price       Decimal  @db.Decimal(10, 2)
  isActive    Boolean  @default(false)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  categoryId  Int
  category    Category @relation(fields: [categoryId], references: [id])
  orderItems  OrderItem[]
}
Customer orders and their line items.
model Order {
  id            Int         @id @default(autoincrement())
  customerEmail String
  totalAmount   Decimal     @db.Decimal(10, 2)
  status        OrderStatus @default(PENDING)
  createdAt     DateTime    @default(now())
  items         OrderItem[]
}

model OrderItem {
  id        Int     @id @default(autoincrement())
  quantity  Int
  unitPrice Decimal @db.Decimal(10, 2)
  orderId   Int
  productId Int
  order     Order   @relation(fields: [orderId], references: [id], onDelete: Cascade)
  product   Product @relation(fields: [productId], references: [id])
  @@unique([orderId, productId])
}
Email addresses for newsletter subscriptions.
model NewsletterSubscriber {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  isActive  Boolean  @default(true)
  createdAt DateTime @default(now())
}

​
Running the Application

​
Development Mode

Start the server with hot-reload: 
pnpm run start:dev
The server will automatically restart when you make code changes.

​
Production Mode

First, build the application: 
pnpm run build
Then start the production server: 
pnpm run start:prod

​
Debug Mode

Start with debugging enabled: 
pnpm run start:debug
Attach your debugger to port 9229.

​
Verification

After installation, verify everything is working:
1

Check server status

Start the server and confirm you see:
🚀 Server ready at http://localhost:3000
2

Test API endpoints

Make a test request:
curl http://localhost:3000/products
Expected response:
{
  "data": [],
  "meta": {
    "page": 1,
    "pageSize": 10,
    "total": 0,
    "totalPages": 0
  }
}
3

Verify database connection

Check Prisma Studio to browse your database:
npx prisma studio
This opens a GUI at http://localhost:5555

​
Additional Configuration

​
Global Validation

The application uses global validation pipes configured in src/main.ts:
src/main.ts
app.useGlobalPipes(
  new ValidationPipe({
    whitelist: true,           // Strip non-whitelisted properties
    forbidNonWhitelisted: true, // Throw error on non-whitelisted properties
    transform: true,            // Auto-transform payloads to DTO instances
  }),
);
This ensures all incoming requests are validated against DTOs using class-validator.

​
Available Scripts

The following npm scripts are available:
ScriptDescription
pnpm run startStart the server
pnpm run start:devStart with hot-reload
pnpm run start:prodStart production build
pnpm run start:debugStart with debugger
pnpm run buildBuild for production
pnpm run prisma:generateGenerate Prisma Client
pnpm run prisma:migrateRun database migrations
pnpm run testRun unit tests
pnpm run test:e2eRun end-to-end tests
pnpm run test:covRun tests with coverage
pnpm run formatFormat code with Prettier
pnpm run lintLint code with ESLint

​
Troubleshooting

​
Common Installation Issues

Install pnpm globally:
npm install -g pnpm
Ensure PostgreSQL is running:
# macOS with Homebrew
brew services start postgresql

# Linux with systemd
sudo systemctl start postgresql

# Windows
# Start from Services panel or pg_ctl
Regenerate the Prisma Client:
pnpm run prisma:generate
Reset the database and migrations (WARNING: deletes all data):
npx prisma migrate reset
Change the port in .env:
PORT=3001
Or kill the process using port 3000:
# Find process
lsof -i :3000

# Kill process
kill -9 <PID>

​
Next Steps

Quickstart Guide

Follow the quickstart to make your first API request

Authentication Setup

Create admin users and secure your endpoints

API Reference

Explore all available API endpoints

Database Schema

Deep dive into the database structure

Build docs developers (and LLMs) love

Get started for freeTalk to us