Skip to main content

​
MongoDB Requirements

Ceboelha API uses MongoDB as its database, accessed through Mongoose ODM. Minimum version: MongoDB 6.0 or higher

​
Installation Options

Install MongoDB locally on your machine:macOS (Homebrew):
brew tap mongodb/brew
brew install mongodb-community
brew services start mongodb-community
Ubuntu/Debian:
sudo apt-get install -y mongodb-org
sudo systemctl start mongod
sudo systemctl enable mongod
Windows: Download and install from MongoDB Download Center

​
Connection Configuration

Configure the MONGODB_URI environment variable in your .env file based on your setup:

​
Local MongoDB (No Authentication)

MONGODB_URI=mongodb://localhost:27017/ceboelha
This is the default for local development without authentication.

​
Local MongoDB (With Authentication)

MONGODB_URI=mongodb://admin:password@localhost:27017/ceboelha?authSource=admin
Use this when running MongoDB with authentication (e.g., via Docker).

​
MongoDB Atlas

MONGODB_URI=mongodb+srv://user:[email protected]/ceboelha?retryWrites=true&w=majority
Replace user, password, and cluster with your actual credentials and cluster name.
Always use environment variables for database credentials. Never hardcode them in your source code.

​
Database Connection

Ceboelha API handles database connection automatically on startup using Mongoose. The connection includes:
  • Automatic reconnection on disconnection
  • Connection monitoring with event logging
  • Graceful shutdown handling

​
Connection Events

The API logs various connection events: 
✅ MongoDB connected: localhost
Successful connection established. 
⚠️ MongoDB disconnected
Connection lost (will attempt to reconnect). 
✅ MongoDB reconnected
Connection restored after disconnection. 
❌ MongoDB connection error: [error details]
Connection error occurred.

​
Testing the Connection

Verify your MongoDB connection before starting the application: 
bun run test:db
This script will:
  1. Attempt to connect to MongoDB using your MONGODB_URI
  2. Report the connection status
  3. Display the connected host
  4. Exit gracefully
Successful output: 
✅ MongoDB connected: localhost
👋 MongoDB disconnected gracefully

​
Database Seeding

Ceboelha API provides scripts to populate your database with initial data.

​
Seed All Data

bun run db:seed
Populates the database with:
  • Sample users
  • Initial configuration
  • Test data for development

​
Seed FODMAP Foods

bun run db:seed-foods
Populates the database with FODMAP food data, including:
  • Food names and categories
  • FODMAP levels (high, medium, low)
  • Serving sizes
  • Nutritional information
Seeding is optional and primarily useful for development and testing. Production databases typically start empty and are populated through the API.

​
Data Models

Ceboelha API uses Mongoose schemas for data modeling. The main collections are:
CollectionDescription
usersUser accounts and authentication
symptomsIBS symptom tracking entries
foodsFODMAP food database
mealsUser meal logs
diariesDaily health diaries

​
Schema Validation

All models include:
  • Type validation - Ensures data types are correct
  • Required fields - Enforces mandatory fields
  • Custom validators - Business logic validation
  • Timestamps - Automatic createdAt and updatedAt fields

​
Database Connection Flow

The application handles database connection in the following sequence:
1

Validate environment

Check that MONGODB_URI is set in environment variables.
2

Attempt connection

Mongoose attempts to connect to MongoDB using the provided URI.
3

Setup event handlers

Register event handlers for connection monitoring:
  • error - Log connection errors
  • disconnected - Log disconnection warnings
  • reconnected - Log successful reconnections
4

Start server

Once connected, the HTTP server starts accepting requests.

​
Graceful Shutdown

When the application receives a shutdown signal (SIGTERM, SIGINT), it:
  1. Stops accepting new HTTP requests
  2. Waits for in-flight requests to complete
  3. Closes the database connection gracefully
  4. Exits the process
⚠️ Received SIGTERM, shutting down gracefully...
✅ Server stopped accepting new requests
👋 MongoDB disconnected gracefully
✅ Database connection closed

​
Troubleshooting

​
Connection Refused

Error: 
❌ Failed to connect to MongoDB: MongoServerError: connect ECONNREFUSED
Solutions:
  • Verify MongoDB is running: mongosh or check service status
  • Check the port (default: 27017)
  • Verify firewall settings

​
Authentication Failed

Error: 
❌ MongoDB connection error: MongoServerError: Authentication failed
Solutions:
  • Verify username and password in MONGODB_URI
  • Check authSource parameter (usually admin)
  • Ensure user has appropriate permissions

​
Network Timeout

Error: 
❌ Failed to connect to MongoDB: MongoServerError: connection timeout
Solutions:
  • Check network connectivity
  • Verify MongoDB Atlas IP whitelist
  • Check if MongoDB is accessible from your network

​
Production Considerations

When deploying to production, follow these best practices:
  • Use authentication - Never run MongoDB without authentication in production
  • Enable SSL/TLS - Encrypt database connections
  • Whitelist IPs - Only allow connections from your application servers
  • Regular backups - Set up automated database backups
  • Monitor performance - Use MongoDB Atlas monitoring or similar tools
  • Set replica sets - Use replica sets for high availability
  • Resource limits - Configure appropriate memory and connection limits

​
Next Steps

Authentication

Learn how to authenticate and manage users

API Reference

Explore the API endpoints and data models

Build docs developers (and LLMs) love

Get started for freeTalk to us