Setup and Deployment

Overview

This guide walks you through the complete setup process for the Church Management System API, from installing dependencies to running the server in production.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v14 or higher)
MongoDB (v4.4 or higher)
npm or yarn package manager
A Stripe account for payment processing
An email service provider (Brevo/SendinBlue or Gmail)

Installation

Clone the repository

Clone the project repository to your local machine:

git clone <repository-url>
cd church_management

Install dependencies

Install all required Node.js packages:

npm install

The following core dependencies will be installed:

express (v5.2.1) - Web application framework
mongoose (v9.1.6) - MongoDB object modeling
bcryptjs (v3.0.3) - Password hashing
jsonwebtoken (v9.0.3) - JWT authentication
stripe (v20.3.1) - Payment processing
nodemailer (v8.0.1) - Email notifications
dotenv (v17.2.4) - Environment variable management

Configure environment variables

Create a .env file in the root directory with the following variables:

# Database Configuration
CONNECTION_STRING=mongodb://localhost:27017/church_management

# JWT Configuration
JWT_SECRET=your_super_secret_jwt_key_here

# Stripe Payment Configuration
STRIPE_KEY=sk_test_your_stripe_secret_key

# Application URLs
BASE_URL=http://localhost:3001

# Email Configuration (Brevo/SendinBlue)
BREVO_USER=your_brevo_smtp_username
BREVO_PASS=your_brevo_smtp_password

# Alternative: Gmail Configuration (uncomment if using Gmail)
# [email protected]
# EMAIL_PASS=your_app_specific_password

Never commit your .env file to version control. Add it to .gitignore to protect sensitive credentials.

Database Setup

MongoDB Configuration

The API uses Mongoose to connect to MongoDB. The connection is established in src/configs/dbconnect.js:

const mongoose = require("mongoose");

const dbConnect = async() => {
  try {
    const connect = await mongoose.connect(`${process.env.CONNECTION_STRING}`);
    console.log(`DB CONNECTED ${connect.connection.host}, ${connect.connection.name}`);
    return true;
  } catch(err) {
    console.log(`connection no work ooo ${err}`);
    return false;
  }
};

module.exports = dbConnect;

Database Models

The system uses four main MongoDB collections:

// User authentication with email and role
{
  email: String,        // Unique, lowercase
  password: String,     // Hashed with bcrypt
  role: String,         // 'pastor' or 'member'
  invitedBy: String,    // Email of inviter
  isProfileComplete: Boolean
}

Email Configuration

Using Brevo (SendinBlue)

The default email configuration uses Brevo’s SMTP relay:

const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: 'smtp-relay.brevo.com',
  port: 587,
  secure: false,
  auth: {
    user: process.env.BREVO_USER,   
    pass: process.env.BREVO_PASS,  
  },
});

module.exports = transporter;

Using Gmail (Alternative)

To use Gmail instead, modify src/configs/mailutil.js:

const transporter = nodemailer.createTransport({
  service: 'gmail', 
  auth: {
    user: process.env.EMAIL_USER,
    pass: process.env.EMAIL_PASS, // Use App Password, not regular password
  },
});

For Gmail, you must enable 2-factor authentication and generate an App Password. Regular passwords won’t work with SMTP.

Stripe Payment Setup

Getting Your Stripe Keys

Create a Stripe account

Get your API keys

Navigate to Developers > API keys in your Stripe dashboard.

For testing: Use the Secret key that starts with sk_test_
For production: Use the Live secret key starting with sk_live_

Add to environment variables

Add your Stripe secret key to .env:

STRIPE_KEY=sk_test_51ABC...xyz123

Payment Flow Configuration

The system uses Stripe Checkout Sessions. Configure your success and cancel URLs in .env:

# For local development
BASE_URL=http://localhost:3001

# For production
BASE_URL=https://yourdomain.com

Payment redirects will use:

Success: ${BASE_URL}/complete?session_id={CHECKOUT_SESSION_ID}
Cancel: ${BASE_URL}/cancel

Running the Server

Development Mode

Run the server with auto-reload on file changes:

npm run dev

This uses nodemon to automatically restart the server when you modify files.

Production Mode

Run the server in production:

npm start

The server typically runs on port 3000. Check your src/app.js file to confirm or modify the port configuration.

Verification Steps

After starting the server, verify your setup:

Check database connection

You should see a console message:

DB CONNECTED <hostname>, church_management

Test the health endpoint

Make a request to verify the API is responding:

curl http://localhost:3001/health

Try creating a user account to verify authentication:

curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password123",
    "role": "member"
  }'

Production Deployment

Environment Checklist

Before deploying to production:

Set NODE_ENV=production in environment variables
Use strong, unique JWT_SECRET (minimum 32 characters)
Switch to Stripe live keys (sk_live_...)
Update BASE_URL to your production domain
Configure MongoDB Atlas or production database
Set up proper email service with verified domain
Enable HTTPS/SSL certificates
Configure CORS for your frontend domain
Set up monitoring and logging

Database Migration

For production, use MongoDB Atlas:

CONNECTION_STRING=mongodb+srv://username:[email protected]/church_management?retryWrites=true&w=majority

Security Recommendations

Critical Security Steps:

Never use default or weak JWT secrets
Always hash passwords with bcrypt (minimum 10 salt rounds)
Validate and sanitize all user inputs
Implement rate limiting on authentication endpoints
Use HTTPS in production (TLS/SSL certificates)
Keep dependencies updated regularly
Enable MongoDB authentication and access controls

Troubleshooting

Common Issues

Database connection fails

Verify MongoDB is running: mongod --version
Check CONNECTION_STRING format in .env
Ensure network connectivity to MongoDB server

Email sending fails

Verify SMTP credentials are correct
Check if email service requires IP whitelisting
Ensure firewall allows outbound SMTP connections (port 587)

Stripe payments don’t work

Confirm you’re using the correct API key (test vs. live)
Verify BASE_URL matches your application URL
Check Stripe dashboard for error logs

JWT token errors

Ensure JWT_SECRET is set in environment variables
Verify token hasn’t expired (default: 1 hour)
Check for typos in Authorization header format

Next Steps

Now that your server is running:

User Management Guide - Learn how to manage user registration and profiles
Church Operations Guide - Set up churches and manage membership
Donation Campaigns Guide - Create and manage donation campaigns

Getting Started

Core Concepts

Guides

Overview

Prerequisites

Installation

Database Setup

MongoDB Configuration

Database Models

Email Configuration

Using Brevo (SendinBlue)

Using Gmail (Alternative)

Stripe Payment Setup

Getting Your Stripe Keys

Payment Flow Configuration

Running the Server

Development Mode

Production Mode

Verification Steps

Production Deployment

Environment Checklist

Database Migration

Security Recommendations

Troubleshooting

Common Issues

Next Steps

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

​Overview

​Prerequisites

​Installation

​Database Setup

​MongoDB Configuration

​Database Models

​Email Configuration

​Using Brevo (SendinBlue)

​Using Gmail (Alternative)

​Stripe Payment Setup

​Getting Your Stripe Keys

​Payment Flow Configuration

​Running the Server

​Development Mode

​Production Mode

​Verification Steps

​Production Deployment

​Environment Checklist

​Database Migration

​Security Recommendations

​Troubleshooting

​Common Issues

​Next Steps

Build docs developers (and LLMs) love

Overview

Prerequisites

Installation

Database Setup

MongoDB Configuration

Database Models

Email Configuration

Using Brevo (SendinBlue)

Using Gmail (Alternative)

Stripe Payment Setup

Getting Your Stripe Keys

Payment Flow Configuration

Running the Server

Development Mode

Production Mode

Verification Steps

Production Deployment

Environment Checklist

Database Migration

Security Recommendations

Troubleshooting

Common Issues

Next Steps