From 5ba3645e2a192e17fd65ad2d4cb9d2c2c3dc82b0 Mon Sep 17 00:00:00 2001 From: Julien Gautier Date: Tue, 28 Apr 2026 21:27:46 +0200 Subject: [PATCH] dbutils initial commit --- dbutils_mongo/.env.example | 11 + dbutils_mongo/.gitignore | 14 + dbutils_mongo/README.md | 154 +++++++++ dbutils_mongo/db-start.sh | 412 +++++++++++++++++++++++ dbutils_mongo/docker-compose-mongodb.yml | 48 +++ dbutils_mongo/mongo-init.js | 17 + 6 files changed, 656 insertions(+) create mode 100644 dbutils_mongo/.env.example create mode 100644 dbutils_mongo/.gitignore create mode 100644 dbutils_mongo/README.md create mode 100755 dbutils_mongo/db-start.sh create mode 100644 dbutils_mongo/docker-compose-mongodb.yml create mode 100644 dbutils_mongo/mongo-init.js diff --git a/dbutils_mongo/.env.example b/dbutils_mongo/.env.example new file mode 100644 index 0000000..1a6cd3e --- /dev/null +++ b/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 diff --git a/dbutils_mongo/.gitignore b/dbutils_mongo/.gitignore new file mode 100644 index 0000000..bc19f33 --- /dev/null +++ b/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 diff --git a/dbutils_mongo/README.md b/dbutils_mongo/README.md new file mode 100644 index 0000000..8f62382 --- /dev/null +++ b/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://:@localhost:27017/?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. diff --git a/dbutils_mongo/db-start.sh b/dbutils_mongo/db-start.sh new file mode 100755 index 0000000..0de319e --- /dev/null +++ b/dbutils_mongo/db-start.sh @@ -0,0 +1,412 @@ +#!/bin/bash + +# Author: Julien Gautier +# 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 +# +# 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 + +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 diff --git a/dbutils_mongo/docker-compose-mongodb.yml b/dbutils_mongo/docker-compose-mongodb.yml new file mode 100644 index 0000000..d18f183 --- /dev/null +++ b/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 diff --git a/dbutils_mongo/mongo-init.js b/dbutils_mongo/mongo-init.js new file mode 100644 index 0000000..04253eb --- /dev/null +++ b/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`);