Skip to main content

​
Prerequisites

Before setting up MinistryHub locally, ensure you have the following installed:
  • Node.js 18.x or higher
  • PHP 8.0 or higher
  • MySQL 8.0 or higher
  • A local web server (Apache, Nginx, or PHP’s built-in server)
  • Package manager: npm, yarn, or pnpm

​
Project Structure

MinistryHub uses a secure architecture that separates public and private code: 
/ (Server Root)
├── backend/                # PRIVATE CORE (Sibling of public_html)
│   ├── config/             # Database credentials (.env)
│   ├── src/                # Controllers, Repositories, Helpers
│   └── bootstrap.php       # PSR-4 Autoloader & Initialization
└── public_html/            # PUBLIC ACCESS
    ├── assets/             # Compiled JS/CSS from React
    ├── api/                # index.php (API entry point)
    ├── .htaccess           # Routing logic
    └── index.html          # React SPA Entry point

​
Clone the Repository

First, clone the MinistryHub repository: 
git clone <repository-url>
cd ministryhub

​
Database Setup

MinistryHub uses two separate databases for better organization:

​
1. Create Databases

Create two MySQL databases: 
CREATE DATABASE ministryhub_main CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE DATABASE ministryhub_music CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

​
2. Import SQL Files

Import the schema files located in your project: 
mysql -u your_user -p ministryhub_main < "User SQL/main.sql"
mysql -u your_user -p ministryhub_music < "Music SQL/music.sql"

​
3. Configure Database Connection

Create the configuration file at backend/config/database.env:
backend/config/database.env
# Main Database Configuration
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_database_user
DB_PASS=your_database_password
DB_NAME=ministryhub_main

# Music Database Configuration
MUSIC_DB_HOST=localhost
MUSIC_DB_USER=your_database_user
MUSIC_DB_PASS=your_database_password
MUSIC_DB_NAME=ministryhub_music

# JWT Secret (Change this to a secure random string)
JWT_SECRET=your_secure_random_jwt_secret_key_here

# reCAPTCHA Configuration (Optional for development)
RECAPTCHA_SECRET=your_recaptcha_secret_key
Make sure to generate a strong, random JWT_SECRET for security. Never commit the database.env file to version control.

​
Backend Setup

The backend uses vanilla PHP with PSR-4 autoloading and requires no additional dependencies.

​
1. Verify PHP Configuration

Ensure PHP has the required extensions: 
php -m | grep -E 'pdo|pdo_mysql|json'

​
2. Create Logs Directory

Ensure the logs directory exists and is writable: 
mkdir -p backend/logs
chmod 755 backend/logs

​
3. Start PHP Development Server

You can use PHP’s built-in server for local development: 
cd public_html
php -S localhost:8000
The .htaccess file handles routing for both API calls (/api/*) and SPA routes. All API requests are routed to api/index.php.

​
Frontend Setup

The frontend is built with React 19, TypeScript, and Vite.

​
1. Navigate to Frontend Directory

cd frontend

​
2. Install Dependencies

npm install

​
3. Configure Environment Variables

Create a .env file in the frontend directory:
frontend/.env
VITE_API_URL=/api
The frontend uses a relative API URL (/api) which works seamlessly in development when both frontend and backend are served from the same origin.

​
4. Start Development Server

npm run dev
The development server will start at http://localhost:5173 by default.

​
Development Workflow

​
Hot Module Replacement

Vite provides instant hot module replacement (HMR) for React components. Your changes will appear immediately without a full page reload.

​
API Development

When making changes to the backend:
  1. Edit PHP files in backend/src/
  2. No build step required - changes are reflected immediately
  3. Check backend/logs/ for error logs if needed

​
Frontend Development

When working on the React frontend:
  1. Edit files in frontend/src/
  2. Vite automatically recompiles and hot-reloads
  3. Use the browser console for debugging

​
Request Lifecycle

Understanding how requests flow through the system:
  1. Client Request: Browser visits localhost:5173/worship/songs
  2. .htaccess Intervention:
    • If it’s an /api/* call → routes to api/index.php
    • If it’s a page route → serves index.html (React Router takes over)
  3. API Handling: api/index.php extracts JWT, identifies user, routes to Controller
  4. Data Layer: Controller asks Repository for data using PDO

​
Development Tools

​
DevProfileSelector

In development mode, MinistryHub includes a profile selector for testing: 
{import.meta.env.DEV && <DevProfileSelector />}
This component only appears when import.meta.env.DEV is true.

​
TypeScript

Run TypeScript type checking: 
npm run build

​
Linting

Run ESLint to check code quality: 
npm run lint

​
Troubleshooting

​
Database Connection Issues

Ensure backend/config/database.env exists and contains all required variables:
  • DB_HOST, DB_USER, DB_PASS, DB_NAME
  • MUSIC_DB_HOST, MUSIC_DB_USER, MUSIC_DB_PASS, MUSIC_DB_NAME
Verify your MySQL service is running:
# macOS
brew services list

# Linux
sudo systemctl status mysql

# Windows
net start MySQL80
Ensure your databases use UTF-8:
ALTER DATABASE ministryhub_main CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER DATABASE ministryhub_music CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

​
Frontend Issues

If you’re running frontend and backend on different ports, you may encounter CORS issues. The backend initializes CORS in backend/src/bootstrap.php:
\App\Helpers\Cors::init();
Check your CORS configuration in the Cors helper.
Clear Vite cache and reinstall dependencies:
rm -rf node_modules .vite
npm install
Run type checking to see detailed errors:
npx tsc --noEmit

​
PHP Issues

The .htaccess file ensures the Authorization header is passed to PHP:
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
If this doesn’t work, check your Apache configuration.
Ensure mod_rewrite is enabled in Apache:
# Enable mod_rewrite
sudo a2enmod rewrite
sudo systemctl restart apache2

​
Next Steps

Configuration

Learn about advanced configuration options

Production

Deploy MinistryHub to production

Build docs developers (and LLMs) love

Get started for freeTalk to us