dbutils initial commit

dbdump_mongo/.env.example

@@ -1,18 +0,0 @@
-# MongoDB Dump Environment Configuration Example
-# Copy this pattern to create environments: .env.prod, .env.uat, etc.
-# DO NOT commit actual configuration files to version control
-
-# Environment: example
-# Created: 2026-04-14
-
-# MongoDB credentials (no defaults - must be provided)
-MONGO_USERNAME=admin_user
-MONGO_PASSWORD=secure_password_here
-MONGO_HOST=cluster0.mongodb.net
-MONGO_PORT=27017
-APP_NAME=my-app
-
-# Note: The connection string will be constructed as:
-# mongodb://<MONGO_USERNAME>:<MONGO_PASSWORD>@<MONGO_HOST>:<MONGO_PORT>/
-#   ?ssl=true&replicaSet=globaldb&retrywrites=false
-#   &maxIdleTimeMS=120000&appName=@<APP_NAME>@

dbdump_mongo/.gitignore

@@ -1,15 +0,0 @@
-# Environment configuration files (contain sensitive credentials)
-.env
-.env.*
-!.env.example
-
-# Dump directories (can be large)
-dumps/
-*.dump
-
-# OS files
-.DS_Store
-Thumbs.db
-
-# Logs
-*.log

dbdump_mongo/README.md

@@ -1,219 +0,0 @@
-# MongoDB Dump Utility
-
-This directory contains a standalone tool for backing up MongoDB databases from remote servers.
-It manages multiple environment configurations for easy switching between prod, uat, and other environments.
-
-## Quick Start
-
-### First Run
-
-```bash
-./db-dump.sh dump
-```
-
-The script will detect no environments and guide you through creating one. Answer the prompts with:
-- **Environment name** (required): e.g., `prod`, `uat`, `staging`
-- **MongoDB username** (required): The admin user
-- **MongoDB password** (required): The admin password
-- **MongoDB host** (required): e.g., `cluster0.mongodb.net`
-- **MongoDB port** (required): Usually `27017` or `10255`
-- **Application name** (required): Used in connection string and dump folder name
-
-### Subsequent Runs
-
-```bash
-./db-dump.sh dump
-```
-
-The script will show you a list of configured environments and let you choose which one to backup,
-or create a new environment.
-
-## Commands
-
-```bash
-# Perform a backup of a selected environment
-./db-dump.sh dump
-
-# List all configured environments
-./db-dump.sh list
-
-# Add a new environment
-./db-dump.sh add
-
-# Delete an environment
-./db-dump.sh delete
-
-# Show help
-./db-dump.sh help
-```
-
-## How It Works
-
-1. **Environment Selection**: On each run, you select from existing environments or create new ones
-2. **Credential Storage**: Each environment's credentials are stored in `.env.<name>` files
-3. **MongoDB Connection**: Connects using your credentials with MongoDB Atlas parameters (ssl, replicaSet, etc.)
-4. **Dump Creation**: Uses `mongodump` to create a backup
-5. **Timestamped Output**: Dumps are organized as `./dumps/<appName>/<yyyymmdd_hhmm>/`
-
-## Configuration Files
-
-Each environment is stored in a separate file:
-
-```
-.env.prod       # Production environment
-.env.uat        # UAT environment
-.env.staging    # Staging environment (if created)
-```
-
-Each file contains:
-```
-MONGO_USERNAME=<username>
-MONGO_PASSWORD=<password>
-MONGO_HOST=<host>
-MONGO_PORT=<port>
-APP_NAME=<appName>
-```
-
-## Directory Structure
-
-```
-dbdump/
-├── db-dump.sh              # Main script
-├── .env.prod              # Production config (created by user)
-├── .env.uat               # UAT config (created by user)
-├── .env.example           # Example configuration
-├── .gitignore             # Git ignore rules
-├── README.md              # This file
-└── dumps/                 # Created automatically
-    ├── prod/
-    │   ├── 20260414_1632/
-    │   │   ├── admin/
-    │   │   └── myapp/
-    │   └── 20260414_1645/
-    └── uat/
-        └── 20260414_1632/
-```
-
-## Dump Output
-
-Dumps are stored with the following structure:
-
-```
-dumps/<appName>/<yyyymmdd_hhmi>/
-  admin/           # System databases
-  config/
-  myapp/           # Application databases
-  system.profile/
-```
-
-Each backup preserves the complete database structure and is ready to be restored using `mongorestore`.
-
-## Accessing Dumps
-
-To view or restore a dump:
-
-```bash
-# List recent dumps
-ls -lh dumps/prod/
-
-# Restore a dump to local MongoDB
-mongorestore --uri "mongodb://localhost:27017" dumps/prod/20260414_1632/
-
-# Copy dump to another location
-cp -r dumps/prod/20260414_1632/ /backup/prod-backup-20260414/
-```
-
-## Security
-
-- Configuration files have restricted permissions (600)
-- Credentials are stored locally in `.env.*` files
-- These files are git-ignored for security
-- Never commit `.env.*` files to version control
-
-## Requirements
-
-- **MongoDB Database Tools**: Download from https://www.mongodb.com/try/download/database-tools
-  - Specifically requires `mongodump` command
-- Bash shell
-- Network access to MongoDB server
-
-## Installation of MongoDB Database Tools
-
-### macOS
-```bash
-brew tap mongodb/brew
-brew install mongodb-database-tools
-```
-
-### Linux (Ubuntu/Debian)
-```bash
-wget https://fastdl.mongodb.org/tools/db/mongodb-database-tools-ubuntu2004-x86_64-100.8.0.tgz
-tar -xzf mongodb-database-tools-ubuntu2004-x86_64-100.8.0.tgz
-sudo cp mongodb-database-tools-ubuntu2004-x86_64-100.8.0/bin/* /usr/local/bin/
-```
-
-### Windows
-Download the MSI installer from https://www.mongodb.com/try/download/database-tools and run it.
-
-## Troubleshooting
-
-### mongodump not found
-```bash
-# Check if MongoDB Database Tools is installed
-mongodump --version
-
-# If not installed, see "Installation" section above
-```
-
-### Connection refused
-- Verify host and port are correct
-- Check network connectivity to MongoDB server
-- Ensure firewall allows access
-
-### Authentication failed
-- Verify username and password
-- Check the user has admin permissions
-- Confirm the `authSource=admin` parameter
-
-### Port already displaying in error
-The connection string is checked for errors. If you see connection errors, the script displays the exact MongoDB error message.
-
-## Advanced Usage
-
-### Manual mongodump command (for reference)
-
-The script constructs and runs this command automatically:
-
-```bash
-mongodump --uri "mongodb://<username>:<password>@<host>:<port>/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<appName>@" -o ./dumps/<appName>/<yyyymmdd_hhmm>
-```
-
-### Scheduling automated backups
-
-You can schedule regular backups using cron (Linux/macOS):
-
-```bash
-# Add to crontab
-crontab -e
-
-# Daily dump at 3 AM for production environment
-0 3 * * * cd /path/to/dbdump && ./db-dump.sh dump << EOF
-1
-EOF
-```
-
-## Support
-
-For MongoDB connection issues, refer to:
-- MongoDB Documentation: https://docs.mongodb.com/
-- Connection String Reference: https://docs.mongodb.com/manual/reference/connection-string/
-
-## About
-
-**Author:** Julien Gautier ([jgautier.webdev@gmail.com](mailto:jgautier.webdev@gmail.com))
-
-**Organization:** AdAstra
-
-**Project:** adastra_scripts
-
-This utility was created to enable efficient backup and versioning of MongoDB databases from remote servers for AdAstra projects.

dbdump_mongo/db-dump.sh

@@ -1,450 +0,0 @@
-#!/bin/bash
-
-# Author: Julien Gautier <jgautier.webdev@gmail.com>
-# Organization: AdAstra
-# Project: adastra_scripts
-#
-################################################################################
-# MongoDB Dump Utility Script (Standalone)
-# 
-# This script performs backups (dumps) of MongoDB databases from remote or local servers.
-# It manages multiple environments (prod, uat, etc.) with stored credentials.
-#
-# Usage: ./db-dump.sh <command>
-#
-# Commands:
-#   dump               Select environment and perform a dump
-#   list               List all configured environments
-#   add                Add a new environment
-#   delete             Delete an environment
-#   help               Show this help message
-#
-# Examples:
-#   ./db-dump.sh dump
-#   ./db-dump.sh list
-#   ./db-dump.sh add
-#
-# Configuration:
-#   Each environment is stored in a separate .env.<environment> file.
-#   All dumps are stored in ./dumps/<appName>/<yyyymmdd_hhmm>/
-#
-################################################################################
-
-set -e
-
-# Configuration
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-DUMPS_DIR="${SCRIPT_DIR}/dumps"
-
-# Colors
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-CYAN='\033[0;36m'
-NC='\033[0m'
-
-# Helper functions
-print_info() {
-    echo -e "${BLUE}┣━${NC} ${CYAN}${1}${NC}"
-}
-
-print_success() {
-    echo -e "${GREEN}✓ ${1}${NC}"
-}
-
-print_error() {
-    echo -e "${RED}✗ ${1}${NC}"
-}
-
-print_warning() {
-    echo -e "${YELLOW}⚠ ${1}${NC}"
-}
-
-print_separator() {
-    echo -e "${BLUE}┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-}
-
-print_separator_up() {
-    echo -e "${BLUE}┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-}
-
-print_separator_down() {
-    echo -e "${BLUE}┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
-}
-
-print_section() {
-    echo
-    print_separator_up
-    print_info "$1"
-    print_separator_down
-    echo
-}
-
-check_mongodump() {
-    if ! command -v mongodump &> /dev/null; then
-        print_error "mongodump is not installed or not in PATH"
-        print_info "Install MongoDB Database Tools from: https://www.mongodb.com/try/download/database-tools"
-        exit 1
-    fi
-    print_success "mongodump found: $(mongodump --version)"
-}
-
-get_environments() {
-    local envs=()
-    for env_file in "$SCRIPT_DIR"/.env.*; do
-        if [[ -f "$env_file" ]]; then
-            local env_name=$(basename "$env_file" | sed 's/^\.env\.//')
-            # Exclude the example file
-            if [[ "$env_name" != "example" ]]; then
-                envs+=("$env_name")
-            fi
-        fi
-    done
-    echo "${envs[@]}"
-}
-
-env_file_path() {
-    echo "${SCRIPT_DIR}/.env.$1"
-}
-
-create_environment() {
-    print_section "Create New Environment"
-    
-    # Check if environment name already exists
-    read -p "Enter environment name (prod, uat, etc.): " env_name
-    env_name="${env_name,,}"  # Convert to lowercase
-    
-    if [[ -z "$env_name" ]]; then
-        print_error "Environment name cannot be empty"
-        return 1
-    fi
-    
-    if [[ -f "$(env_file_path "$env_name")" ]]; then
-        print_error "Environment '$env_name' already exists"
-        return 1
-    fi
-    
-    print_info "Enter MongoDB connection details for '$env_name'"
-    echo
-    
-    # Read credentials (no defaults)
-    read -p "MongoDB username: " mongo_username
-    if [[ -z "$mongo_username" ]]; then
-        print_error "Username cannot be empty"
-        return 1
-    fi
-    
-    read -sp "MongoDB password: " mongo_password
-    echo
-    if [[ -z "$mongo_password" ]]; then
-        print_error "Password cannot be empty"
-        return 1
-    fi
-    
-    read -p "MongoDB host (e.g., cluster0.mongodb.net): " mongo_host
-    if [[ -z "$mongo_host" ]]; then
-        print_error "Host cannot be empty"
-        return 1
-    fi
-    
-    read -p "MongoDB port (e.g., 27017): " mongo_port
-    if [[ -z "$mongo_port" ]]; then
-        print_error "Port cannot be empty"
-        return 1
-    fi
-    
-    read -p "Application name (appName): " app_name
-    if [[ -z "$app_name" ]]; then
-        print_error "Application name cannot be empty"
-        return 1
-    fi
-    
-    # Create .env file for this environment
-    local env_file=$(env_file_path "$env_name")
-    cat > "$env_file" << EOF
-# Environment: $env_name
-# Created: $(date)
-MONGO_USERNAME=${mongo_username}
-MONGO_PASSWORD=${mongo_password}
-MONGO_HOST=${mongo_host}
-MONGO_PORT=${mongo_port}
-APP_NAME=${app_name}
-EOF
-    chmod 600 "$env_file"  # Restrict permissions for security
-    
-    print_success "Environment '$env_name' created successfully"
-    print_info "Configuration stored in: $(basename "$env_file")"
-}
-
-# Global variable to hold selected environment
-SELECTED_ENVIRONMENT=""
-
-select_environment() {
-    SELECTED_ENVIRONMENT=""
-    local envs=($(get_environments))
-    local count=${#envs[@]}
-    
-    print_separator_up
-    
-    if [[ $count -eq 0 ]]; then
-        print_info "No Environments Configured"
-        print_separator
-        echo
-        print_warning "No existing environments found"
-        echo
-        echo "  1) Create a new environment"
-        echo "  2) Exit"
-        echo
-        echo -n "Enter your choice (1-2): "
-        read choice
-        
-        if [[ "$choice" == "1" ]]; then
-            if create_environment; then
-                # After creating an environment, recursively call to select it
-                select_environment
-                return $?
-            else
-                return 1
-            fi
-        else
-            return 1
-        fi
-    fi
-    
-    print_info "Select Environment"
-    print_separator_down
-    echo
-    
-    for i in "${!envs[@]}"; do
-        echo "  $((i + 1))) ${envs[$i]}"
-    done
-    echo "  $((count + 1))) Create new environment"
-    echo
-    echo -n "Enter your choice (1-$((count + 1))): "
-    read choice
-    
-    if [[ "$choice" =~ ^[0-9]+$ ]] && [[ $choice -ge 1 ]] && [[ $choice -le $((count + 1)) ]]; then
-        if [[ $choice -eq $((count + 1)) ]]; then
-            if create_environment; then
-                # After creating an environment, recursively call to select it
-                select_environment
-                return $?
-            else
-                return 1
-            fi
-        else
-            SELECTED_ENVIRONMENT="${envs[$((choice - 1))]}"
-            return 0
-        fi
-    else
-        print_error "Invalid choice"
-        return 1
-    fi
-}
-
-load_environment() {
-    local env_name="$1"
-    local env_file=$(env_file_path "$env_name")
-    
-    if [[ ! -f "$env_file" ]]; then
-        print_error "Environment file not found: $env_file"
-        return 1
-    fi
-    
-    # shellcheck source=/dev/null
-    source "$env_file"
-}
-
-perform_dump() {
-    local env_name="$1"
-    
-    load_environment "$env_name" || return 1
-    
-    print_section "MongoDB Dump: $env_name"
-    
-    # Create output directory with timestamp
-    local timestamp=$(date +%Y%m%d_%H%M)
-    local output_dir="${DUMPS_DIR}/${APP_NAME}/${timestamp}"
-    
-    mkdir -p "$output_dir"
-    
-    print_separator_up
-    print_info "Environment: $env_name"
-    print_info "App Name: $APP_NAME"
-    print_info "Host: $MONGO_HOST:$MONGO_PORT"
-    print_info "Output: $output_dir"
-    print_separator_down
-    
-    # Construct connection string
-    local connection_uri="mongodb://${MONGO_USERNAME}:${MONGO_PASSWORD}@${MONGO_HOST}:${MONGO_PORT}/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@${APP_NAME}@"
-    
-    # Perform dump
-    if mongodump --uri "$connection_uri" -o "$output_dir" 2>&1; then
-        print_success "Dump completed successfully"
-        print_info "Output directory: $output_dir"
-        
-        # Show dump summary
-        local dump_size=$(du -sh "$output_dir" | cut -f1)
-        print_info "Total size: $dump_size"
-    else
-        print_error "Dump failed"
-        print_warning "Removing incomplete dump directory..."
-        rm -rf "$output_dir"
-        return 1
-    fi
-}
-
-cmd_dump() {
-    print_separator_up
-    print_info "MongoDB Dump Utility"
-    print_separator_down
-    
-    check_mongodump
-    
-    select_environment
-    if [[ $? -ne 0 ]]; then
-        print_error "No environment selected"
-        return 1
-    fi
-    
-    if perform_dump "$SELECTED_ENVIRONMENT"; then
-        print_success "Dump operation completed"
-    else
-        print_error "Dump operation failed"
-        return 1
-    fi
-}
-
-cmd_list() {
-    print_section "Configured Environments"
-    
-    local envs=($(get_environments))
-    
-    if [[ ${#envs[@]} -eq 0 ]]; then
-        print_warning "No environments configured yet"
-        return 0
-    fi
-    
-    for env in "${envs[@]}"; do
-        local env_file=$(env_file_path "$env")
-        # shellcheck source=/dev/null
-        source "$env_file"
-        echo "  • $env"
-        echo "    Host: $MONGO_HOST:$MONGO_PORT"
-        echo "    App:  $APP_NAME"
-        echo
-    done
-}
-
-cmd_add() {
-    if create_environment; then
-        print_success "Environment added successfully"
-    else
-        print_error "Failed to add environment"
-        return 1
-    fi
-}
-
-cmd_delete() {
-    print_section "Delete Environment"
-    
-    local envs=($(get_environments))
-    
-    if [[ ${#envs[@]} -eq 0 ]]; then
-        print_warning "No environments configured"
-        return 0
-    fi
-    
-    for i in "${!envs[@]}"; do
-        echo "  $((i + 1))) ${envs[$i]}"
-    done
-    echo
-    
-    read -p "Enter environment number to delete: " choice
-    
-    if [[ "$choice" =~ ^[0-9]+$ ]] && [[ $choice -ge 1 ]] && [[ $choice -le ${#envs[@]} ]]; then
-        local env_name="${envs[$((choice - 1))]}"
-        read -p "Confirm deletion of '$env_name'? (yes/no): " confirm
-        
-        if [[ "$confirm" == "yes" ]]; then
-            local env_file=$(env_file_path "$env_name")
-            rm -f "$env_file"
-            print_success "Environment '$env_name' deleted"
-        else
-            print_info "Deletion cancelled"
-        fi
-    else
-        print_error "Invalid choice"
-        return 1
-    fi
-}
-
-cmd_help() {
-    cat << EOF
-
-MongoDB Dump Utility Script (Standalone)
-
-Usage: ./db-dump.sh <command>
-
-Commands:
-    dump       Select an environment and perform a backup dump
-    list       List all configured environments
-    add        Add a new environment configuration
-    delete     Delete an environment configuration
-    help       Show this help message
-
-Examples:
-    ./db-dump.sh dump          # Interactive environment selection and dump
-    ./db-dump.sh list          # Show all environments
-    ./db-dump.sh add           # Add new environment
-    ./db-dump.sh delete        # Remove an environment
-
-Environment Configuration:
-    - Each environment is stored in a separate .env.<name> file
-    - Credentials are encrypted (file permissions: 600)
-    - Supported environments: prod, uat, dev, staging, etc.
-
-Dump Output:
-    - Dumps are stored in: ./dumps/<appName>/<yyyymmdd_hhmm>/
-    - Each dump is timestamped for easy identification
-    - Connection string includes MongoDB Atlas parameters
-
-Requirements:
-    - MongoDB Database Tools (mongodump)
-    - Bash shell
-
-MongoDB Connection String Format:
-    mongodb://<username>:<password>@<host>:<port>/
-      ?ssl=true&replicaSet=globaldb&retrywrites=false
-      &maxIdleTimeMS=120000&appName=@<appName>@
-
-EOF
-}
-
-# Main
-COMMAND="${1:-help}"
-
-case "$COMMAND" in
-    dump)
-        cmd_dump
-        ;;
-    list)
-        cmd_list
-        ;;
-    add)
-        cmd_add
-        ;;
-    delete)
-        cmd_delete
-        ;;
-    help|--help|-h)
-        cmd_help
-        ;;
-    *)
-        print_error "Unknown command: $COMMAND"
-        echo
-        cmd_help
-        exit 1
-        ;;
-esac

dbutils_mongo/.env.example

@@ -0,0 +1,11 @@
+# MongoDB Configuration Example
+# Copy this file to .env and update with your values
+# The script will prompt for these values on first run
+
+MONGO_USERNAME=admin
+MONGO_PASSWORD=password
+MONGO_DATABASE=adastradb
+MONGO_PORT=27017
+MONGO_EXPRESS_PORT=8081
+MONGO_EXPRESS_USERNAME=dev
+MONGO_EXPRESS_PASSWORD=dev

dbutils_mongo/.gitignore

@@ -0,0 +1,14 @@
+# Environment variables
+.env
+*.env
+
+# Docker volumes
+mongodb-data/
+mongo-config/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

dbutils_mongo/README.md

@@ -0,0 +1,154 @@
+# 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)
+
+```bash
+./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
+
+```bash
+# 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:
+
+```bash
+./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:
+
+```bash
+# 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
+```bash
+# Check Docker status
+docker info
+```
+
+### Permission denied
+```bash
+# 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](mailto:jgautier.webdev@gmail.com))
+
+**Organization:** AdAstra
+
+**Project:** adastra_scripts
+
+These utilities were created to simplify MongoDB management during local development of AdAstra projects.

dbutils_mongo/db-start.sh

@@ -0,0 +1,412 @@
+#!/bin/bash
+
+# Author: Julien Gautier <jgautier.webdev@gmail.com>
+# Organization: AdAstra
+# Project: adastra_scripts
+#
+################################################################################
+# MongoDB Database Utility Script (Standalone)
+# 
+# This script manages a standalone MongoDB instance for local development.
+# It runs independently and requires no configuration from the backend project.
+#
+# Usage: ./db-start.sh <command>
+#
+# Commands:
+#   up                 Start MongoDB and Mongo Express (interactive setup)
+#   down               Stop MongoDB and Mongo Express
+#   logs               Show database logs (follow mode)
+#   restart            Restart MongoDB and Mongo Express
+#   status             Show container status
+#   clean              Remove database containers and volumes
+#   help               Show this help message
+#
+# Configuration:
+#   The script will prompt for MongoDB credentials on first run.
+#   Configuration is stored in .env file.
+#
+# Examples:
+#   ./db-start.sh up
+#   ./db-start.sh logs
+#   ./db-start.sh down
+#
+################################################################################
+
+set -e
+
+# Configuration
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COMPOSE_FILE="${SCRIPT_DIR}/docker-compose-mongodb.yml"
+ENV_FILE="${SCRIPT_DIR}/.env"
+PROJECT_NAME="dbutils"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+# Helper functions
+print_info() {
+    echo -e "${BLUE}┣━${NC} ${CYAN}${1}${NC}"
+}
+
+print_success() {
+    echo -e "${GREEN}✓ ${1}${NC}"
+}
+
+print_error() {
+    echo -e "${RED}✗ ${1}${NC}"
+}
+
+print_warning() {
+    echo -e "${YELLOW}⚠ ${1}${NC}"
+}
+
+print_separator() {
+    echo -e "${BLUE}┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+}
+
+print_separator_up() {
+    echo -e "${BLUE}┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+}
+
+print_separator_down() {
+    echo -e "${BLUE}┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+}
+
+check_docker() {
+    if ! command -v docker &> /dev/null; then
+        print_error "Docker is not installed or not in PATH"
+        exit 1
+    fi
+    print_success "Docker found: $(docker --version)"
+}
+
+check_docker_running() {
+    if ! docker info > /dev/null 2>&1; then
+        print_error "Docker daemon is not running"
+        exit 1
+    fi
+    print_success "Docker daemon is running"
+}
+
+check_docker_compose() {
+    if ! command -v docker-compose &> /dev/null && ! docker compose version &> /dev/null 2>&1; then
+        print_error "Docker Compose is not installed or not in PATH"
+        exit 1
+    fi
+    print_success "Docker Compose is available"
+}
+
+check_compose_file() {
+    if [[ ! -f "$COMPOSE_FILE" ]]; then
+        print_error "Docker Compose file not found at $COMPOSE_FILE"
+        exit 1
+    fi
+}
+
+get_compose_cmd() {
+    if command -v docker-compose &> /dev/null; then
+        echo "docker-compose"
+    else
+        echo "docker compose"
+    fi
+}
+
+setup_credentials() {
+    print_separator_up
+    print_info "MongoDB Configuration Setup"
+    print_separator_down
+    echo
+    
+    # Read username
+    read -p "Enter MongoDB root username (default: admin): " mongo_username
+    mongo_username="${mongo_username:-admin}"
+    
+    # Read password
+    read -sp "Enter MongoDB root password (default: password): " mongo_password
+    echo
+    mongo_password="${mongo_password:-password}"
+    
+    # Read database name
+    read -p "Enter MongoDB database name (default: adastradb): " mongo_database
+    mongo_database="${mongo_database:-adastradb}"
+    
+    echo
+    print_info "MongoDB port (default: 27017): "
+    read -p "Enter MongoDB port or press Enter for default: " mongo_port
+    mongo_port="${mongo_port:-27017}"
+    
+    print_info "Mongo Express port (default: 8081): "
+    read -p "Enter Mongo Express port or press Enter for default: " mongo_express_port
+    mongo_express_port="${mongo_express_port:-8081}"
+    
+    echo
+    
+    # Create .env file
+    cat > "$ENV_FILE" << EOF
+# MongoDB Configuration
+MONGO_USERNAME=${mongo_username}
+MONGO_PASSWORD=${mongo_password}
+MONGO_DATABASE=${mongo_database}
+MONGO_PORT=${mongo_port}
+MONGO_EXPRESS_PORT=${mongo_express_port}
+MONGO_EXPRESS_USERNAME=dev
+MONGO_EXPRESS_PASSWORD=dev
+EOF
+    
+    print_success "Configuration saved to .env"
+    echo
+}
+
+load_credentials() {
+    if [[ -f "$ENV_FILE" ]]; then
+        print_info "Loading configuration from .env"
+        # shellcheck source=/dev/null
+        source "$ENV_FILE"
+    else
+        print_warning "No configuration found. Running setup..."
+        setup_credentials
+        # shellcheck source=/dev/null
+        source "$ENV_FILE"
+    fi
+}
+
+cmd_up() {
+    print_separator_up
+    print_info "Starting MongoDB Database..."
+    print_separator_down
+    echo
+    
+    check_docker
+    check_docker_running
+    check_compose_file
+    check_docker_compose
+    
+    load_credentials
+    
+    COMPOSE_CMD=$(get_compose_cmd)
+    
+    # Export variables for docker-compose
+    export MONGO_USERNAME
+    export MONGO_PASSWORD
+    export MONGO_DATABASE
+    export MONGO_PORT
+    export MONGO_EXPRESS_PORT
+    export MONGO_EXPRESS_USERNAME
+    export MONGO_EXPRESS_PASSWORD
+    
+    $COMPOSE_CMD -f "$COMPOSE_FILE" -p "$PROJECT_NAME" up -d
+    
+    print_success "MongoDB and Mongo Express have been started"
+    print_separator_up
+    print_info "MongoDB Connection Details:"
+    print_info "  Host:     localhost:${MONGO_PORT}"
+    print_info "  Username: ${MONGO_USERNAME}"
+    print_info "  Password: ${MONGO_PASSWORD}"
+    print_info "  Database: ${MONGO_DATABASE}"
+    print_separator
+    print_info "Mongo Express (GUI) available at: http://localhost:${MONGO_EXPRESS_PORT}"
+    print_info "  Username: ${MONGO_EXPRESS_USERNAME}"
+    print_info "  Password: ${MONGO_EXPRESS_PASSWORD}"
+    print_separator_down
+}
+
+cmd_down() {
+    print_separator_up
+    print_info "Stopping MongoDB and Mongo Express..."
+    print_separator_down
+    
+    check_docker
+    check_compose_file
+    check_docker_compose
+    
+    COMPOSE_CMD=$(get_compose_cmd)
+    
+    $COMPOSE_CMD -f "$COMPOSE_FILE" -p "$PROJECT_NAME" down
+    
+    print_success "MongoDB and Mongo Express have been stopped"
+}
+
+cmd_logs() {
+    print_separator_up
+    print_info "Showing MongoDB logs..."
+    print_separator_down
+    
+    check_docker
+    check_compose_file
+    check_docker_compose
+    
+    COMPOSE_CMD=$(get_compose_cmd)
+    
+    $COMPOSE_CMD -f "$COMPOSE_FILE" -p "$PROJECT_NAME" logs -f
+}
+
+cmd_restart() {
+    print_separator_up
+    print_info "Restarting MongoDB and Mongo Express..."
+    print_separator_down
+    
+    check_docker
+    check_docker_running
+    check_compose_file
+    check_docker_compose
+    
+    load_credentials
+    
+    COMPOSE_CMD=$(get_compose_cmd)
+    
+    # Export variables for docker-compose
+    export MONGO_USERNAME
+    export MONGO_PASSWORD
+    export MONGO_DATABASE
+    export MONGO_PORT
+    export MONGO_EXPRESS_PORT
+    export MONGO_EXPRESS_USERNAME
+    export MONGO_EXPRESS_PASSWORD
+    
+    $COMPOSE_CMD -f "$COMPOSE_FILE" -p "$PROJECT_NAME" restart
+    
+    print_success "MongoDB and Mongo Express have been restarted"
+}
+
+cmd_status() {
+    print_separator_up
+    print_info "Container Status"
+    print_separator_down
+    
+    check_docker
+    check_compose_file
+    check_docker_compose
+    
+    COMPOSE_CMD=$(get_compose_cmd)
+    
+    $COMPOSE_CMD -f "$COMPOSE_FILE" -p "$PROJECT_NAME" ps
+}
+
+cmd_clean() {
+    print_separator_up
+    print_warning "This will remove database containers and volumes"
+    print_warning "All data will be PERMANENTLY LOST!"
+    echo
+    read -p "Are you sure? Type 'yes' to confirm: " response
+    echo
+    
+    if [[ "$response" == "yes" ]]; then
+        print_separator
+        print_info "Removing containers and volumes..."
+        print_separator
+        
+        check_docker
+        check_compose_file
+        check_docker_compose
+        
+        COMPOSE_CMD=$(get_compose_cmd)
+        
+        $COMPOSE_CMD -f "$COMPOSE_FILE" -p "$PROJECT_NAME" down -v --remove-orphans
+        
+        print_success "All containers and volumes have been removed"
+        print_info "Configuration file (.env) has been preserved"
+    else
+        print_info "Clean operation cancelled"
+    fi
+    print_separator_down
+}
+
+cmd_reconfigure() {
+    print_separator_up
+    print_warning "This will reset the MongoDB configuration"
+    echo
+    read -p "Are you sure? Type 'yes' to confirm: " response
+    echo
+    
+    if [[ "$response" == "yes" ]]; then
+        print_info "Stopping services before reconfiguration..."
+        check_docker 2>/dev/null || true
+        check_compose_file 2>/dev/null || true
+        
+        COMPOSE_CMD=$(get_compose_cmd)
+        if command -v $COMPOSE_CMD &> /dev/null; then
+            $COMPOSE_CMD -f "$COMPOSE_FILE" -p "$PROJECT_NAME" down 2>/dev/null || true
+        fi
+        
+        rm -f "$ENV_FILE"
+        print_success "Configuration cleared"
+        
+        setup_credentials
+        print_info "You can now run './db-start.sh up' to start with the new configuration"
+    else
+        print_info "Reconfiguration cancelled"
+    fi
+    print_separator_down
+}
+
+cmd_help() {
+    cat << EOF
+
+MongoDB Database Utility Script (Standalone)
+
+Usage: ./db-start.sh <command>
+
+Commands:
+    up             Start MongoDB and Mongo Express (interactive setup on first run)
+    down           Stop MongoDB and Mongo Express
+    logs           Show database and container logs (follow mode)
+    restart        Restart MongoDB and Mongo Express
+    status         Show container status
+    reconfigure    Reset and reconfigure MongoDB credentials
+    clean          Remove all containers and volumes (DATA LOSS!)
+    help           Show this help message
+
+Examples:
+    ./db-start.sh up
+    ./db-start.sh logs
+    ./db-start.sh down
+    ./db-start.sh reconfigure
+
+Configuration:
+    On first run, 'up' command will prompt for MongoDB credentials.
+    Configuration is stored in .env file (git-ignored).
+    You can reconfigure anytime with 'reconfigure' command.
+
+EOF
+}
+
+# Main
+COMMAND="${1:-help}"
+
+case "$COMMAND" in
+    up|start)
+        cmd_up
+        ;;
+    down|stop)
+        cmd_down
+        ;;
+    logs)
+        cmd_logs
+        ;;
+    restart)
+        cmd_restart
+        ;;
+    status|ps)
+        cmd_status
+        ;;
+    reconfigure)
+        cmd_reconfigure
+        ;;
+    clean|remove)
+        cmd_clean
+        ;;
+    help|--help|-h)
+        cmd_help
+        ;;
+    *)
+        print_error "Unknown command: $COMMAND"
+        echo
+        cmd_help
+        exit 1
+        ;;
+esac

dbutils_mongo/docker-compose-mongodb.yml

@@ -0,0 +1,48 @@
+services:
+  mongodb:
+    image: mongo:latest
+    container_name: dbutils-mongodb
+    ports:
+      - "${MONGO_PORT:-27017}:27017"
+    environment:
+      MONGO_INITDB_ROOT_USERNAME: ${MONGO_USERNAME}
+      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}
+      MONGO_INITDB_DATABASE: ${MONGO_DATABASE}
+    volumes:
+      - mongodb-data:/data/db
+      - mongodb-config:/data/configdb
+      - ./mongo-init.js:/docker-entrypoint-initdb.d/mongo-init.js
+    networks:
+      - dbutils-network
+    restart: unless-stopped
+    healthcheck:
+      test: echo 'db.runCommand("ping").ok' | mongosh localhost:27017/test --quiet
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 40s
+
+  mongo-express:
+    image: mongo-express:latest
+    container_name: dbutils-mongo-express
+    ports:
+      - "${MONGO_EXPRESS_PORT:-8081}:8081"
+    environment:
+      ME_CONFIG_MONGODB_URL: mongodb://${MONGO_USERNAME}:${MONGO_PASSWORD}@mongodb:27017/?authSource=admin
+      ME_CONFIG_MONGODB_ADMINUSERNAME: ${MONGO_USERNAME}
+      ME_CONFIG_MONGODB_ADMINPASSWORD: ${MONGO_PASSWORD}
+      ME_CONFIG_BASICAUTH_USERNAME: ${MONGO_EXPRESS_USERNAME:-dev}
+      ME_CONFIG_BASICAUTH_PASSWORD: ${MONGO_EXPRESS_PASSWORD:-dev}
+    depends_on:
+      - mongodb
+    networks:
+      - dbutils-network
+    restart: unless-stopped
+
+volumes:
+  mongodb-data:
+  mongodb-config:
+
+networks:
+  dbutils-network:
+    driver: bridge

dbutils_mongo/mongo-init.js

@@ -0,0 +1,17 @@
+// Initialize MongoDB database
+
+// Switch to the application database
+db = db.getSiblingDB(process.env.MONGO_INITDB_DATABASE || 'adastradb');
+
+// Create a collection for data import history
+// This collection will track all data imports for audit and recovery purposes
+db.createCollection('dataImportHistory', {
+  capped: false
+});
+
+// Create an index on the importDate for better query performance
+db.dataImportHistory.createIndex({ importDate: -1 });
+db.dataImportHistory.createIndex({ status: 1 });
+
+print(`✓ Database '${db.getName()}' initialized successfully`);
+print(`✓ Collection 'dataImportHistory' created`);