Skip to main content
This guide walks you through setting up the BD Scan Face application from scratch, including database configuration, environment variables, and dependency installation.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (v16 or higher)
  • npm or yarn package manager
  • Docker and Docker Compose (for database)
  • PostgreSQL (if not using Docker)

​
Installation Steps

1

Clone the Repository

Clone the BD Scan Face repository to your local machine:
git clone https://github.com/ErnestoJuarez2708/BD_Scan_Face.git
cd BD_Scan_Face
2

Install Dependencies

Install all required npm packages:
npm install
This will install key dependencies including:
  • @prisma/client (v6.19.2) - Prisma ORM client
  • @prisma/adapter-pg (v7.4.2) - PostgreSQL adapter
  • prisma (v7.4.2) - Prisma CLI and tooling
  • pg (v8.19.0) - PostgreSQL driver
  • dotenv (v17.3.1) - Environment variable management
3

Configure Environment Variables

Create a .env file in the project root with your database connection settings:
.env
DATABASE_URL="postgresql://postgres:prisma@localhost:5432/postgres?schema=public"
The DATABASE_URL format is: postgresql://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]?schema=public

​
Environment Variable Breakdown

VariableDescriptionDefault Value
DATABASE_URLPostgreSQL connection stringRequired
If using the provided Docker Compose setup, the default credentials are:
  • User: postgres
  • Password: prisma
  • Database: postgres
  • Port: 5432
4

Start the Database

Use Docker Compose to start the PostgreSQL database:
docker-compose up -d
Verify the database is running:
docker-compose ps
You should see the postgres service running and healthy.
5

Run Database Migrations

Apply Prisma migrations to set up your database schema:
npx prisma migrate deploy
Or if you’re in development:
npx prisma migrate dev
This creates all necessary tables: users, user_types, faces, devices, and access_logs.
6

Generate Prisma Client

Generate the Prisma Client with the current schema:
npx prisma generate
The client will be generated in the generated/prisma directory as configured in your schema.

​
Database Connection Configuration

​
Prisma Configuration

The project uses a custom Prisma configuration file (prisma.config.ts) that defines the schema location and migration paths:
prisma.config.ts
import "dotenv/config";
import { defineConfig } from "prisma/config";

export default defineConfig({
  schema: "prisma/schema.prisma",
  migrations: {
    path: "prisma/migrations",
  },
  datasource: {
    url: process.env["DATABASE_URL"],
  },
});
The configuration automatically loads environment variables using dotenv/config, so your .env file will be read automatically.

​
Connection String Formats

DATABASE_URL="postgresql://postgres:prisma@localhost:5432/postgres?schema=public"

​
Verifying Your Setup

​
Check Database Connection

Test your database connection using Prisma Studio: 
npx prisma studio
This opens a web interface at http://localhost:5555 where you can view and manage your database.

​
Verify Schema

Check that all tables were created correctly: 
npx prisma db pull
This introspects your database and verifies it matches the schema.

​
Troubleshooting

​
Connection Refused

Error: Error: connect ECONNREFUSED 127.0.0.1:5432
Solution: Ensure PostgreSQL is running: 
# Check if Docker container is running
docker-compose ps

# View container logs
docker-compose logs postgres

# Restart the database
docker-compose restart postgres

​
Authentication Failed

Error: Error: P1001: Can't reach database server
Solution: Verify your credentials in the .env file match the Docker Compose configuration:
  • Check POSTGRES_USER in docker-compose.yml matches the username in DATABASE_URL
  • Check POSTGRES_PASSWORD in docker-compose.yml matches the password in DATABASE_URL
  • Check POSTGRES_DB in docker-compose.yml matches the database name in DATABASE_URL

​
Migration Errors

Error: Migration engine error: Database does not exist
Solution: Create the database first: 
# Using psql
docker exec -it bd_scan_face_postgres_1 psql -U postgres -c "CREATE DATABASE postgres;"

# Or reset the database
npx prisma migrate reset

​
Port Already in Use

Error: Bind for 0.0.0.0:5432 failed: port is already allocated
Solution: Either stop the conflicting service or change the port in docker-compose.yml:
docker-compose.yml
ports:
  - "5433:5432"  # Changed external port
Then update your DATABASE_URL: 
DATABASE_URL="postgresql://postgres:prisma@localhost:5433/postgres?schema=public"

​
Prisma Client Not Found

Error: Cannot find module '@prisma/client'
Solution: Regenerate the Prisma Client: 
npx prisma generate

​
Schema Out of Sync

Error: Prisma schema loaded from prisma/schema.prisma is not in sync with the database
Solution: Apply pending migrations: 
npx prisma migrate deploy
Or reset the database (development only): 
npx prisma migrate reset

​
Next Steps

Prisma Client Usage

Learn how to use Prisma Client for database operations

Docker Configuration

Deep dive into the Docker Compose setup

Database Schema

Explore the complete database schema

API Reference

View model API reference and usage examples

Build docs developers (and LLMs) love

Get started for freeTalk to us