Skip to main content

​
System Requirements

Before getting started, ensure you have the following installed:
  • Node.js (v16 or higher recommended)
  • npm (comes with Node.js)
  • PostgreSQL (v12 or higher)
  • Git (for version control)
We recommend using nvm to manage Node.js versions.

​
Installing Dependencies

The Cognit Backend uses the following key dependencies:

​
Production Dependencies

1

Clone the repository

git clone <repository-url>
cd backend
2

Install npm packages

npm install
This will install all required dependencies including:
  • express (v4.21.1) - Web framework
  • sequelize-typescript (v2.1.6) - ORM for PostgreSQL
  • pg (v8.13.1) - PostgreSQL client
  • helmet (v8.0.0) - Security headers
  • cors (v2.8.5) - Cross-origin resource sharing
  • express-rate-limit (v7.4.1) - Rate limiting
  • jsonwebtoken (v9.0.2) - JWT authentication
  • bcrypt (v5.1.1) - Password hashing
  • nodemailer (v6.9.16) - Email functionality
  • express-validator (v7.2.0) - Input validation
3

Install development dependencies

Development dependencies are automatically installed with npm install and include:
  • typescript (v5.7.2)
  • nodemon (v3.1.7)
  • ts-node (v10.9.2)
  • jest (v29.7.0) - Testing framework

​
PostgreSQL Database Setup

1

Install PostgreSQL

Download and install PostgreSQL from postgresql.org.For macOS using Homebrew:
brew install postgresql@15
brew services start postgresql@15
For Ubuntu/Debian:
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
2

Create a database

Access PostgreSQL and create a database for Cognit:
psql postgres
Then run:
CREATE DATABASE cognit_dev;
CREATE USER cognit_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE cognit_dev TO cognit_user;
\q
3

Note your connection string

Your PostgreSQL connection URL will be:
postgresql://cognit_user:your_secure_password@localhost:5432/cognit_dev
Never commit database credentials to version control. Use environment variables.

​
Environment Variables Configuration

Create a .env file in the root directory with the following variables: 
# Server Configuration
PORT=3005

# Database Configuration
DATABASE_URL=postgresql://cognit_user:your_secure_password@localhost:5432/cognit_dev

# JWT Authentication
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production

# Email Configuration (Nodemailer)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=[email protected]
EMAIL_PASS=your-app-specific-password

# Frontend URL (for CORS and email links)
FRONTEND_URL=http://localhost:5175
For Gmail, you’ll need to generate an App Password instead of using your regular password.

​
Environment Variables Reference

VariableDescriptionRequiredDefault
PORTPort number for the serverNo3005
DATABASE_URLPostgreSQL connection stringYes-
JWT_SECRETSecret key for JWT token signingYes-
EMAIL_HOSTSMTP server hostnameYes-
EMAIL_PORTSMTP server portYes-
EMAIL_USEREmail account usernameYes-
EMAIL_PASSEmail account passwordYes-
FRONTEND_URLFrontend application URLYes-

​
Database Initialization

The application uses Sequelize with TypeScript models. Database tables are automatically created on first run.
1

Automatic schema sync

When you start the development server, Sequelize will automatically:
  • Connect to the database (src/server.ts:10-21)
  • Synchronize the schema with db.sync({ alter: true }) (src/server.ts:13-14)
  • Create or alter tables based on your models
2

Verify database connection

You should see this message when the server starts:
Database connection successfull
The alter: true option modifies existing tables to match models. In production, use proper migrations instead.

​
Running in Development Mode

1

Start the development server

npm run dev
This uses nodemon to watch for file changes and automatically restart the server.
2

Alternative API-only mode

npm run dev:api
Runs with the --api flag for API-specific development.
3

Verify the server is running

You should see:
Database connection successfull
REST Api on port 3005
The API is now accessible at http://localhost:3005

​
Testing the Installation

Test that everything is working: 
curl http://localhost:3005/api/auth/users
You should receive a JSON response (empty array if no users exist yet).
Use tools like Postman or Insomnia to test API endpoints during development.

​
Next Steps

Configuration

Learn about configuring CORS, rate limiting, and email settings

API Reference

Explore available API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us