Linux Setup Guide

Complete installation and configuration guide for Linux distributions

Prerequisites

Before installing ManageX on Linux, ensure you have:

  • Ubuntu 18.04+ or CentOS 7+ or similar Linux distribution
  • Root or sudo privileges
  • At least 4GB of RAM (8GB recommended)
  • 2GB of free disk space
  • Internet connection for downloading packages
  • Basic knowledge of Linux command line

Step 1: Install Node.js

1

Update Package Lists

sudo apt update
2

Install Node.js 18+

Add NodeSource repository and install Node.js:

# Add NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
# Install Node.js
sudo apt-get install -y nodejs

Note

ManageX requires Node.js 16 or higher. Node 18+ is recommended for better performance and security.

3

Verify Installation

node --version
npm --version

You should see Node.js version 18.x or higher and npm version 8.x or higher.

1

Install EPEL Repository

# For CentOS 7
sudo yum install -y epel-release

# For CentOS 8/RHEL 8
sudo dnf install -y epel-release
2

Install Node.js

# For CentOS 7
sudo yum install -y nodejs npm

# For CentOS 8/RHEL 8
sudo dnf install -y nodejs npm

Note

If the default version is too old, use NodeSource repository as shown in Ubuntu section to get Node.js 18+.

1

Install Node.js

sudo pacman -S nodejs npm

Step 2: Install MySQL

1

Install MySQL Server

sudo apt install -y mysql-server
2

Secure MySQL Installation

sudo mysql_secure_installation

Follow the prompts to set root password and configure security options.

3

Start and Enable MySQL

sudo systemctl start mysql
sudo systemctl enable mysql
1

Install MySQL Server

# For CentOS 7
sudo yum install -y mysql-server

# For CentOS 8/RHEL 8
sudo dnf install -y mysql-server
2

Start and Enable MySQL

# For CentOS 7
sudo systemctl start mysqld
sudo systemctl enable mysqld

# For CentOS 8/RHEL 8
sudo systemctl start mysqld
sudo systemctl enable mysqld
1

Install MySQL

sudo pacman -S mysql
2

Initialize MySQL

sudo mysql_install_db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
3

Start and Enable MySQL

sudo systemctl start mysqld
sudo systemctl enable mysqld
4

Create Database

# Login to MySQL
sudo mysql -u root -p

# Create database
CREATE DATABASE managex_db;

# Create user (optional but recommended)
CREATE USER 'managex'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON managex_db.* TO 'managex'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 3: Install ManageX Server

1

Navigate to Server Directory

cd /path/to/manage-x/server

Replace the path with your actual project location.

2

Install Dependencies

npm install

This will install all required Node.js packages including Express.js, Sequelize, JWT, and other dependencies.

3

Create Environment File

Create a .env file in the server directory:

nano .env

Add the following configuration:

Example .env File

# NODE Configuration
PORT=3000     
NODE_ENV=development

# Database Configuration
DB_HOST=localhost
DB_NAME=managex_db
DB_USERNAME=root
DB_PASSWORD=your_password
DB_DIALECT=mysql

# JWT Configuration
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_REFRESH_SECRET=your-refresh-secret-key-change-in-production
JWT_EXPIRES_IN=24h
JWT_REFRESH_EXPIRES_IN=7d

# Demo Mode Configuration
IS_DEMO=0

Security Note

Change the JWT_SECRET and JWT_REFRESH_SECRET to strong, unique values in production. Use a password manager to generate secure secrets.

IS_DEMO Configuration

Set IS_DEMO=0 for production (runs only non-demo seeders) or IS_DEMO=1 for development/testing (runs all seeders including demo data). See the IS_DEMO Configuration section in the home page for more details.

4

Run Database Migrations

npm run db:migrate

This will create all necessary tables in your MySQL database.

5

Seed Initial Data

npm run demo

This will create default roles, users, organization, and configuration data. The IS_DEMO setting in your .env file determines whether demo seeders are included. See the home page documentation for details.

Note

The npm run demo command respects the IS_DEMO environment variable. For production, use IS_DEMO=0 to skip demo data.

6

Start the Server

npm run dev

You should see output indicating the server is running on port 3000 (or the port specified in your .env file).

Step 4: Access the Application

Open your web browser and navigate to:

http://localhost:3000

Default Login Credentials

Use these credentials to log in for the first time:

  • Email: superadmin@managex.com
  • Password: SuperAdmin@123

Important

Change the default password immediately after your first login for security reasons.

First Steps After Login

After logging in, you should:

  • Update your profile and password
  • Configure your organization settings
  • Set up additional users and roles as needed
  • Configure system settings according to your business needs

Step 5: Production Setup with PM2

1

Install PM2 Globally

sudo npm install -g pm2
2

Create PM2 Configuration

Create ecosystem.config.js in the server directory:

module.exports = {
  apps: [{
    name: 'managex-server',
    script: './bin/www',
    instances: 1,
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
};
3

Start with PM2

pm2 start ecosystem.config.js
pm2 save
pm2 startup

The last command will generate a startup script. Follow the instructions it provides.

4

Useful PM2 Commands

# View running processes
pm2 list

# View logs
pm2 logs managex-server

# Restart application
pm2 restart managex-server

# Stop application
pm2 stop managex-server

# Monitor resources
pm2 monit

Troubleshooting

Quick Fixes

  • Permission denied: Check file permissions and ownership, use sudo when necessary
  • Port already in use: Use netstat -tulpn | grep :3000 to find the process, then kill it
  • MySQL connection failed: Verify MySQL is running with sudo systemctl status mysql
  • Node modules not found: Ensure you're in the correct directory and run npm install
  • Migration/Seeder errors: Ensure database exists, MySQL is running, and IS_DEMO is set correctly

Useful Commands

# Check Node.js version
node --version

# Check MySQL status
sudo systemctl status mysql

# Check running processes
ps aux | grep node

# Check port usage
netstat -tulpn | grep :3000

# View PM2 logs
pm2 logs

Need More Help?

For detailed troubleshooting steps, common error solutions, and advanced diagnostics, see the Complete Troubleshooting Guide.