adastra_scripts/dbutils_mongo

MongoDB Database Utility (Standalone)

This directory contains a standalone MongoDB setup for local development. It is completely independent from the main backend and frontend projects.

Quick Start

First Run (Setup)

./db-start.sh up

The script will prompt you for:

• MongoDB username (default: admin)
• MongoDB password (default: password)
• Database name (default: adastradb)
• MongoDB port (default: 27017)
• Mongo Express port (default: 8081)

Your configuration will be stored in .env file (automatically git-ignored).

Common Commands

# Start MongoDB (prompts for credentials on first run)
./db-start.sh up

# View logs
./db-start.sh logs

# Stop MongoDB
./db-start.sh down

# Restart MongoDB
./db-start.sh restart

# Check container status
./db-start.sh status

# Reconfigure credentials
./db-start.sh reconfigure

# Remove all containers and volumes (DATA LOSS!)
./db-start.sh clean

# Show help
./db-start.sh help

Accessing MongoDB

From Your Application

• Connection String: mongodb://<username>:<password>@localhost:27017/<database>?authSource=admin
• Example: mongodb://admin:password@localhost:27017/adastradb?authSource=admin

Using Mongo Express (GUI)

• URL: http://localhost:8081
• Username: dev
• Password: dev

Data Persistence

All data is stored in Docker volumes and persists across container restarts. To permanently delete data, use:

./db-start.sh clean

Collections

The database is automatically initialized with the following collection:

• dataImportHistory: Stores records of all data imports for audit and recovery tracking
  • Indexed on importDate (descending) and status
  • Ready for future data import functionality

File Structure

dbutils/
├── db-start.sh                     # Main script
├── docker-compose-mongodb.yml      # Docker Compose configuration
├── mongo-init.js                   # Database initialization script
├── .env                            # Configuration (generated on first run, git-ignored)
├── .env.example                    # Example configuration
├── .gitignore                      # Git ignore rules
└── README.md                       # This file

Configuration

The script uses a .env file to store configuration. You can:

1. Let the script generate it: Run ./db-start.sh up and answer the prompts
2. Pre-create it: Copy .env.example to .env and modify values
3. Edit it manually: Edit .env directly and run ./db-start.sh up
4. Reconfigure: Run ./db-start.sh reconfigure to re-run the setup wizard

Requirements

• Docker
• Docker Compose (included with Docker Desktop)
• Bash shell

Standalone Usage

This utility can be used independently from AdAstra projects:

# From anywhere
cd /path/to/dbutils
./db-start.sh up

# Or add to PATH and use globally (optional)
export PATH=$PATH:/path/to/dbutils
db-start.sh up

Troubleshooting

Port already in use

If MongoDB or Mongo Express port is already in use:

1. Run ./db-start.sh reconfigure
2. Choose a different port (e.g., 27018 for MongoDB, 8082 for Mongo Express)

Docker not running

# Check Docker status
docker info

Permission denied

# Make script executable
chmod +x db-start.sh

Notes

• Credentials are stored in .env (git-ignored for security)
• Mongo Express is included for easy database management
• Data persists in Docker volumes
• No initialization scripts are run (unlike the backend docker-compose)
• This is standalone and independent from the main project configuration

About

Author: Julien Gautier (jgautier.webdev@gmail.com)

Organization: AdAstra

Project: adastra_scripts

These utilities were created to simplify MongoDB management during local development of AdAstra projects.