155 lines
3.9 KiB
Markdown
155 lines
3.9 KiB
Markdown
# 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.
|