Installation

vLife DGO is an employee background evaluation system built with Node.js, Express, and MySQL. This guide covers detailed installation for both development and production environments.

System Requirements

Software Prerequisites

Node.js: v16.x or higher (v18.x recommended)
MySQL: v5.7 or higher (v8.0 recommended)
npm: v7.x or higher (comes with Node.js)
Git: For version control

Hardware Requirements

Minimum: 2GB RAM, 2 CPU cores, 10GB disk space
Recommended: 4GB RAM, 4 CPU cores, 20GB disk space

Development Installation

Verify Node.js Installation

Check your Node.js version:

node --version
npm --version

If Node.js is not installed, download it from nodejs.org.

Clone the Repository

git clone <repository-url>
cd vlife

Install Dependencies

Install all required packages defined in package.json:

npm install

This installs the following core dependencies:

package.json

{
  "dependencies": {
    "express": "^4.18.2",
    "mysql2": "^3.6.1",
    "express-handlebars": "^7.1.2",
    "express-session": "^1.17.3",
    "bcrypt": "^5.1.1",
    "jsonwebtoken": "^9.0.2",
    "passport": "^0.6.0",
    "puppeteer": "^15.5.0",
    "qrcode": "^1.5.4",
    "multer": "^2.0.2",
    "dotenv": "^16.3.1"
  },
  "devDependencies": {
    "nodemon": "^3.0.1"
  }
}

Configure MySQL Database

Create Database

Connect to MySQL and create the database:

CREATE DATABASE vlifedgo_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Create MySQL User (Optional)

For production, create a dedicated user:

CREATE USER 'vlife_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON vlifedgo_db.* TO 'vlife_user'@'localhost';
FLUSH PRIVILEGES;

Set Up Environment Variables

Create a .env file in the project root directory:

.env

# Server Configuration
PORT=4001

# Database Configuration
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASS=your_mysql_password
DB_DATABASE=vlifedgo_db

# Security Key for Encryption
SUPER_KEY=key_cecc

Never commit the .env file to version control. It contains sensitive credentials.

Environment Variables Explained

Variable	Description	Default
`PORT`	HTTP server port	`4001`
`DB_HOST`	MySQL server hostname	`localhost`
`DB_PORT`	MySQL server port	`3306`
`DB_USER`	MySQL username	`root`
`DB_PASS`	MySQL password	(empty)
`DB_DATABASE`	Database name	`vlifedgo_db`
`SUPER_KEY`	Encryption key for sensitive data	`key_cecc`

Create Required Directories

The application uses a directory for file uploads. Create it:

mkdir -p src/public/uploads

This directory is automatically excluded from Git via .gitignore to prevent committing uploaded files.

Start the Development Server

Run the application with auto-reload enabled:

npm run dev

The server will start with nodemon, which watches for file changes:

[nodemon] 3.0.1
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,json
[nodemon] starting `node src/index.js`
vLife v3 running on 4001

Production Installation

Using PM2 Process Manager

For production environments, use PM2 to manage the Node.js process:

Install PM2 Globally

npm install -g pm2

Start the Application

pm2 start src/index.js --name vlife-dgo

Configure Auto-Restart on Boot

pm2 startup
pm2 save

Monitor the Application

pm2 status
pm2 logs vlife-dgo
pm2 monit

Using Nginx as Reverse Proxy

Configure Nginx to proxy requests to vLife DGO:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:4001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Database Connection

The application uses MySQL2 connection pooling for optimal performance. Here’s how it’s configured:

src/database/Connection.js

import { createPool } from "mysql2/promise";
import {
  DB_HOST,
  DB_PORT,
  DB_USER,
  DB_PASS,
  DB_DATABASE
} from "../config.js";

export const PoolvLife = createPool({
  host: DB_HOST,
  user: DB_USER,
  password: DB_PASS,
  port: DB_PORT,
  database: DB_DATABASE,
  dateStrings: true,
});

The connection pool is automatically managed and reused across requests.

Application Structure

After installation, your application structure will be:

vlife/
├── src/
│   ├── index.js              # Entry point
│   ├── app.js                # Express app configuration
│   ├── config.js             # Environment configuration
│   ├── controllers/          # Request handlers
│   ├── database/
│   │   └── Connection.js     # Database connection pool
│   ├── models/               # Data models
│   ├── routes/               # API routes
│   ├── views/                # Handlebars templates
│   ├── public/               # Static assets
│   │   └── uploads/          # User uploaded files
│   ├── middlewares/          # Custom middleware
│   └── helpers/              # Utility functions
├── package.json
├── .env                      # Environment variables (create this)
└── README.md

Troubleshooting

Database Connection Errors

Error: ER_ACCESS_DENIED_ERRORSolution: Verify your MySQL credentials:

mysql -u root -p

If successful, update your .env file with the correct credentials.

Error: ECONNREFUSEDSolution: Ensure MySQL is running:

# Linux
sudo systemctl status mysql
sudo systemctl start mysql

# macOS
brew services start mysql

# Windows
net start MySQL80

Port Already in Use

Error: EADDRINUSE: address already in use :::4001Solution: Either change the port in .env:

.env

PORT=4002

Or find and kill the process using port 4001:

# Linux/macOS
lsof -i :4001
kill -9 <PID>

# Windows
netstat -ano | findstr :4001
taskkill /PID <PID> /F

File Upload Issues

Error: Files not uploading or directory errorsSolution: Ensure the uploads directory exists with proper permissions:

mkdir -p src/public/uploads
chmod 755 src/public/uploads

The application is configured to accept files up to 20MB:

src/app.js

app.use(multer({
  storage: storage,
  limits: { fileSize: 20000000 }, // 20MB
}).single('file'))

Puppeteer Installation Issues

Error: Chromium download fails during npm installSolution: Install Chromium dependencies:

# Ubuntu/Debian
sudo apt-get install -y chromium-browser

# Or skip Chromium download and use system Chrome
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true npm install

Session Issues

Problem: Users getting logged out frequentlySolution: The application uses memory-based sessions. For production, consider using MySQL session store:

import MySQLStore from 'express-mysql-session';

const sessionStore = MySQLStore(session);
const sessionStoreConfig = new sessionStore({
  host: DB_HOST,
  port: DB_PORT,
  user: DB_USER,
  password: DB_PASS,
  database: DB_DATABASE
});

Verifying Installation

Test that all components are working:

Check Server Status

curl http://localhost:4001

Should return HTML or redirect to /auth/home.

Check Database Connection

The application will log any database connection errors to the console. If you see:

vLife v3 running on 4001

Without any errors, the database connection is successful.

Access the Application

Navigate to http://localhost:4001 in your browser. You should see the authentication interface.

Security Considerations

Important: Before deploying to production:

Change SUPER_KEY to a strong, unique value
Use strong MySQL passwords
Never commit .env to version control
Enable HTTPS with SSL certificates
Configure firewall rules to restrict database access
Keep dependencies updated: npm audit fix

Next Steps

Now that vLife DGO is installed:

Review Environment Configuration for advanced settings
Explore the Authentication API to understand available endpoints
Learn about Evaluation Types and system design
Review Database Configuration and connection setup

Get Started

Core Features

User Guides

System Configuration

System Requirements

Software Prerequisites

Hardware Requirements

Development Installation

Create Database

Create MySQL User (Optional)

Environment Variables Explained

Production Installation

Using PM2 Process Manager

Using Nginx as Reverse Proxy

Database Connection

Application Structure

Troubleshooting

Verifying Installation

Security Considerations

Next Steps

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

System Configuration

​System Requirements

​Software Prerequisites

​Hardware Requirements

​Development Installation

​Create Database

​Create MySQL User (Optional)

​Environment Variables Explained

​Production Installation

​Using PM2 Process Manager

​Using Nginx as Reverse Proxy

​Database Connection

​Application Structure

​Troubleshooting

​Verifying Installation

​Security Considerations

​Next Steps

Build docs developers (and LLMs) love

System Requirements

Software Prerequisites

Hardware Requirements

Development Installation

Create Database

Create MySQL User (Optional)

Environment Variables Explained

Production Installation

Using PM2 Process Manager

Using Nginx as Reverse Proxy

Database Connection

Application Structure

Troubleshooting

Verifying Installation

Security Considerations

Next Steps