IFSC 78603-Graduate Project Setup Guide

Abdullah Al Amin

Information Science-MS

University of Arkansas at Little Rock

Complete setup documentation for local server and live cPanel deployment.

This project is a Flask-based web application using Python, MySQL, SQLAlchemy, Pandas, Openpyxl, and Bootstrap. It supports both local development and live deployment on cPanel using Passenger.

1. Important Note About .env and run.py

The files .env and run.py are included in .gitignore because they are different in local and live environments.

Why `.env` is ignored

It contains private configuration values such as SECRET_KEY and database credentials.
Local computer and cPanel server use different MySQL database names, users, and paths.

Why `run.py` is ignored

Local setup runs Flask using app.run(debug=True).
cPanel Passenger requires a WSGI entry point using application = app.

Local `run.py`

from app import create_app

app = create_app()

if __name__ == "__main__":
    app.run(debug=True)

cPanel `run.py`

from app import create_app

app = create_app()

application = app

2. Local Server Setup

Step 1: Install Python

Install Python 3.9 or a compatible version.

python --version

Step 2: Install MySQL / MariaDB

Install MySQL or MariaDB on your computer and make sure the database server is running.

Step 3: Get the source code from GitLab

git clone git@gitlab.com:devdict/grad_project.git
cd your-project

If the project already exists locally, update it using:

git pull origin main

Step 4: Create virtual environment

python -m venv venv

Step 5: Activate virtual environment

Windows:

venv\Scripts\activate

Linux / Mac:

source venv/bin/activate

Step 6: Install required packages

pip install -r requirements.txt

Step 7: Create local database

CREATE DATABASE vizapp;

Step 8: Create local `.env`

SECRET_KEY=your_local_secret_key
SQLALCHEMY_DATABASE_URI=mysql+pymysql://root:your_password@localhost/vizapp
FLASK_ENV=development
FLASK_DEBUG=1

Step 9: Create local `run.py`

from app import create_app

app = create_app()

if __name__ == "__main__":
    app.run(debug=True)

Step 10: Start the application

python run.py

Then open:

http://127.0.0.1:5000

3. Live Server Setup on cPanel

Step 1: Create MySQL database in cPanel

In cPanel, open MySQL Databases and create:

Database
Database User
Assign user to database with all privileges

Step 2: Create Python App in cPanel

Go to Setup Python App and configure:

Python version
Application root
Application URL / domain

Step 3: Open cPanel terminal

cd /home/yourcpaneluser/your-project-directory

Step 4: Get code from GitLab

git clone git@gitlab.com:devdict/grad_project.git .

If code is already there, update using:

git pull origin main

Step 5: Install dependencies

pip install -r requirements.txt

Step 6: Create live `.env`

SECRET_KEY=your_live_secret_key
SQLALCHEMY_DATABASE_URI=mysql+pymysql://cpaneluser_dbuser:your_password@localhost/cpaneluser_dbname
FLASK_ENV=production
FLASK_DEBUG=0

Step 7: Create cPanel `run.py`

from app import create_app

app = create_app()

application = app

Step 8: Restart the application

touch tmp/restart.txt

4. MySQL Startup SQL

The following SQL can be used as the startup structure for the local database. This includes the main system tables: users, datasets, and saved_queries.

CREATE TABLE `datasets` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `title` varchar(200) NOT NULL,
  `table_name` varchar(64) NOT NULL,
  `original_filename` varchar(255) NOT NULL,
  `stored_name` varchar(80) NOT NULL,
  `n_rows` int(11) DEFAULT NULL,
  `n_cols` int(11) DEFAULT NULL,
  `uploaded_at` datetime DEFAULT current_timestamp(),
  `file_size_bytes` bigint(20) DEFAULT NULL,
  `duplicate_rows` int(11) DEFAULT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `table_name` (`table_name`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;

CREATE TABLE `users` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `role` varchar(255) DEFAULT NULL,
  `name` varchar(255) DEFAULT NULL,
  `email` varchar(255) DEFAULT NULL,
  `phone` varchar(255) DEFAULT NULL,
  `designation` varchar(255) DEFAULT NULL,
  `username` varchar(50) NOT NULL,
  `password` varchar(100) NOT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `username` (`username`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;

CREATE TABLE `saved_queries` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `name` varchar(150) NOT NULL,
  `user_id` int(11) NOT NULL,
  `dataset_id` int(11) NOT NULL,
  `query_config` text NOT NULL,
  `created_at` datetime DEFAULT current_timestamp(),
  PRIMARY KEY (`id`),
  KEY `user_id` (`user_id`),
  KEY `dataset_id` (`dataset_id`),
  CONSTRAINT `saved_queries_ibfk_1` FOREIGN KEY (`user_id`) REFERENCES `users` (`id`) ON DELETE CASCADE,
  CONSTRAINT `saved_queries_ibfk_2` FOREIGN KEY (`dataset_id`) REFERENCES `datasets` (`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COLLATE=utf8_general_ci;

Optional default users:

INSERT INTO `users` (`role`, `username`, `password`)
VALUES
('admin', 'admin', 'pass123'),
('manager', 'jack', 'pass123');

5. GitLab Update Workflow

Local update

git pull origin main
pip install -r requirements.txt

Live server update

cd /home/yourcpaneluser/your-project-directory
git pull origin main
pip install -r requirements.txt
touch tmp/restart.txt

6. Recommended .gitignore

venv/
__pycache__/
*.pyc
.env
run.py
uploads/