513 lines
16 KiB
HTML
513 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>MongoDB Database Utility (Standalone)</title>
|
|
<style>
|
|
* {
|
|
margin: 0;
|
|
padding: 0;
|
|
box-sizing: border-box;
|
|
}
|
|
|
|
body {
|
|
font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
|
|
line-height: 1.6;
|
|
color: #333;
|
|
background-color: #f5f5f5;
|
|
page-break-after: always;
|
|
}
|
|
|
|
.container {
|
|
max-width: 900px;
|
|
margin: 0 auto;
|
|
padding: 0;
|
|
background-color: white;
|
|
}
|
|
|
|
header {
|
|
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
|
|
color: white;
|
|
padding: 50px 40px;
|
|
text-align: center;
|
|
page-break-after: avoid;
|
|
}
|
|
|
|
header h1 {
|
|
font-size: 2.8em;
|
|
margin-bottom: 10px;
|
|
font-weight: 700;
|
|
letter-spacing: -1px;
|
|
}
|
|
|
|
header p {
|
|
font-size: 1.6em;
|
|
opacity: 0.95;
|
|
font-weight: 300;
|
|
color: #FFF;
|
|
text-align: center;
|
|
}
|
|
|
|
.toc {
|
|
background-color: #f8f9fa;
|
|
border-left: 4px solid #667eea;
|
|
padding: 30px 40px;
|
|
margin: 30px 0;
|
|
page-break-inside: avoid;
|
|
}
|
|
|
|
.toc h2 {
|
|
color: #667eea;
|
|
font-size: 1.3em;
|
|
margin-bottom: 20px;
|
|
text-transform: uppercase;
|
|
letter-spacing: 1px;
|
|
}
|
|
|
|
.toc ul {
|
|
list-style: none;
|
|
padding-left: 0;
|
|
}
|
|
|
|
.toc li {
|
|
margin: 8px 0;
|
|
font-size: 1em;
|
|
}
|
|
|
|
.toc a {
|
|
color: #667eea;
|
|
text-decoration: none;
|
|
border-bottom: 1px dotted #667eea;
|
|
transition: all 0.2s;
|
|
}
|
|
|
|
.toc a:hover {
|
|
color: #764ba2;
|
|
border-bottom-style: solid;
|
|
}
|
|
|
|
main {
|
|
padding: 40px;
|
|
}
|
|
|
|
section {
|
|
margin-bottom: 40px;
|
|
page-break-inside: avoid;
|
|
}
|
|
|
|
h2 {
|
|
color: #667eea;
|
|
font-size: 1.8em;
|
|
margin-bottom: 15px;
|
|
margin-top: 30px;
|
|
padding-bottom: 10px;
|
|
border-bottom: 2px solid #667eea;
|
|
font-weight: 700;
|
|
}
|
|
|
|
h3 {
|
|
color: #764ba2;
|
|
font-size: 1.3em;
|
|
margin: 20px 0 12px 0;
|
|
font-weight: 600;
|
|
}
|
|
|
|
p {
|
|
margin-bottom: 15px;
|
|
text-align: justify;
|
|
color: #555;
|
|
}
|
|
|
|
ul, ol {
|
|
margin-left: 25px;
|
|
margin-bottom: 15px;
|
|
}
|
|
|
|
li {
|
|
margin-bottom: 8px;
|
|
color: #555;
|
|
}
|
|
|
|
strong {
|
|
color: #333;
|
|
font-weight: 600;
|
|
}
|
|
|
|
code {
|
|
background-color: #f8f9fa;
|
|
border: 1px solid #e0e0e0;
|
|
border-radius: 3px;
|
|
padding: 2px 6px;
|
|
font-family: 'Courier New', monospace;
|
|
font-size: 0.95em;
|
|
color: #d63384;
|
|
}
|
|
|
|
pre {
|
|
background-color: #2d2d2d;
|
|
color: #f8f8f2;
|
|
padding: 20px;
|
|
border-radius: 5px;
|
|
overflow-x: auto;
|
|
margin: 15px 0;
|
|
font-family: 'Courier New', monospace;
|
|
font-size: 0.9em;
|
|
line-height: 1.4;
|
|
page-break-inside: avoid;
|
|
border-left: 4px solid #667eea;
|
|
}
|
|
|
|
pre code {
|
|
background-color: transparent;
|
|
border: none;
|
|
padding: 0;
|
|
color: #f8f8f2;
|
|
}
|
|
|
|
.highlight {
|
|
background-color: #fff3cd;
|
|
padding: 2px 6px;
|
|
border-radius: 3px;
|
|
}
|
|
|
|
.note {
|
|
background-color: #e7f3ff;
|
|
border-left: 4px solid #2196F3;
|
|
padding: 15px 20px;
|
|
margin: 20px 0;
|
|
border-radius: 3px;
|
|
page-break-inside: avoid;
|
|
}
|
|
|
|
.warning {
|
|
background-color: #fff3cd;
|
|
border-left: 4px solid #ffc107;
|
|
padding: 15px 20px;
|
|
margin: 20px 0;
|
|
border-radius: 3px;
|
|
page-break-inside: avoid;
|
|
}
|
|
|
|
.danger {
|
|
background-color: #f8d7da;
|
|
border-left: 4px solid #dc3545;
|
|
padding: 15px 20px;
|
|
margin: 20px 0;
|
|
border-radius: 3px;
|
|
page-break-inside: avoid;
|
|
}
|
|
|
|
.file-structure {
|
|
background-color: #f8f9fa;
|
|
border: 1px solid #dee2e6;
|
|
padding: 15px;
|
|
border-radius: 3px;
|
|
font-family: 'Courier New', monospace;
|
|
font-size: 0.9em;
|
|
line-height: 1.6;
|
|
white-space: pre-wrap;
|
|
margin: 15px 0;
|
|
page-break-inside: avoid;
|
|
}
|
|
|
|
table {
|
|
width: 100%;
|
|
border-collapse: collapse;
|
|
margin: 20px 0;
|
|
page-break-inside: avoid;
|
|
}
|
|
|
|
th {
|
|
background-color: #667eea;
|
|
color: white;
|
|
padding: 12px;
|
|
text-align: left;
|
|
font-weight: 600;
|
|
}
|
|
|
|
td {
|
|
padding: 12px;
|
|
border-bottom: 1px solid #dee2e6;
|
|
}
|
|
|
|
tr:nth-child(even) {
|
|
background-color: #f8f9fa;
|
|
}
|
|
|
|
tr:hover {
|
|
background-color: #e7f3ff;
|
|
}
|
|
|
|
footer {
|
|
background-color: #f8f9fa;
|
|
border-top: 2px solid #667eea;
|
|
padding: 30px 40px;
|
|
margin-top: 40px;
|
|
text-align: center;
|
|
color: #666;
|
|
font-size: 0.95em;
|
|
page-break-inside: avoid;
|
|
}
|
|
|
|
footer p {
|
|
margin: 8px 0;
|
|
text-align: center;
|
|
}
|
|
|
|
.meta {
|
|
color: #667eea;
|
|
font-weight: 600;
|
|
}
|
|
|
|
a {
|
|
color: #667eea;
|
|
text-decoration: none;
|
|
transition: color 0.2s;
|
|
}
|
|
|
|
a:hover {
|
|
color: #764ba2;
|
|
text-decoration: underline;
|
|
}
|
|
|
|
.command {
|
|
display: inline-block;
|
|
background-color: #e7f3ff;
|
|
border: 1px solid #667eea;
|
|
border-radius: 3px;
|
|
padding: 8px 12px;
|
|
font-family: 'Courier New', monospace;
|
|
font-size: 0.9em;
|
|
color: #0066cc;
|
|
margin: 5px 0;
|
|
}
|
|
|
|
.title-page {
|
|
display: flex;
|
|
flex-direction: column;
|
|
justify-content: center;
|
|
align-items: center;
|
|
min-height: 100vh;
|
|
page-break-after: always;
|
|
}
|
|
|
|
.page-break {
|
|
page-break-after: always;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="container">
|
|
<header>
|
|
<h1>MongoDB Database Utility</h1>
|
|
<p>Standalone Local Development Setup</p>
|
|
</header>
|
|
|
|
<div class="toc">
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><a href="#quick-start">Quick Start</a></li>
|
|
<li><a href="#commands">Common Commands</a></li>
|
|
<li><a href="#accessing">Accessing MongoDB</a></li>
|
|
<li><a href="#persistence">Data Persistence</a></li>
|
|
<li><a href="#collections">Collections</a></li>
|
|
<li><a href="#structure">File Structure</a></li>
|
|
<li><a href="#configuration">Configuration</a></li>
|
|
<li><a href="#requirements">Requirements</a></li>
|
|
<li><a href="#standalone">Standalone Usage</a></li>
|
|
<li><a href="#troubleshooting">Troubleshooting</a></li>
|
|
<li><a href="#notes">Notes</a></li>
|
|
<li><a href="#about">About</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
<main>
|
|
<section>
|
|
<p style="font-style: italic; color: #777; margin-bottom: 20px;">
|
|
This directory contains a standalone MongoDB setup for local development. It is completely independent from the main backend and frontend projects.
|
|
</p>
|
|
</section>
|
|
|
|
<section id="quick-start">
|
|
<h2>Quick Start</h2>
|
|
|
|
<h3>First Run (Setup)</h3>
|
|
<pre><code>./db-start.sh up</code></pre>
|
|
|
|
<p>The script will prompt you for:</p>
|
|
<ul>
|
|
<li><strong>MongoDB username</strong> (default: <code>admin</code>)</li>
|
|
<li><strong>MongoDB password</strong> (default: <code>password</code>)</li>
|
|
<li><strong>Database name</strong> (default: <code>adastradb</code>)</li>
|
|
<li><strong>MongoDB port</strong> (default: <code>27017</code>)</li>
|
|
<li><strong>Mongo Express port</strong> (default: <code>8081</code>)</li>
|
|
</ul>
|
|
|
|
<p>Your configuration will be stored in <code>.env</code> file (automatically git-ignored).</p>
|
|
</section>
|
|
|
|
<section id="commands">
|
|
<h2>Common Commands</h2>
|
|
<pre><code># 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</code></pre>
|
|
</section>
|
|
|
|
<section id="accessing">
|
|
<h2>Accessing MongoDB</h2>
|
|
|
|
<h3>From Your Application</h3>
|
|
<ul>
|
|
<li><strong>Connection String:</strong> <code>mongodb://<username>:<password>@localhost:27017/<database>?authSource=admin</code></li>
|
|
<li><strong>Example:</strong> <code>mongodb://admin:password@localhost:27017/adastradb?authSource=admin</code></li>
|
|
</ul>
|
|
|
|
<h3>Using Mongo Express (GUI)</h3>
|
|
<ul>
|
|
<li><strong>URL:</strong> <a href="http://localhost:8081">http://localhost:8081</a></li>
|
|
<li><strong>Username:</strong> <code>dev</code></li>
|
|
<li><strong>Password:</strong> <code>dev</code></li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="persistence">
|
|
<h2>Data Persistence</h2>
|
|
<p>All data is stored in Docker volumes and persists across container restarts. To permanently delete data, use:</p>
|
|
<pre><code>./db-start.sh clean</code></pre>
|
|
</section>
|
|
|
|
<section id="collections">
|
|
<h2>Collections</h2>
|
|
<p>The database is automatically initialized with the following collection:</p>
|
|
<ul>
|
|
<li><strong>dataImportHistory:</strong> Stores records of all data imports for audit and recovery tracking
|
|
<ul>
|
|
<li>Indexed on <code>importDate</code> (descending) and <code>status</code></li>
|
|
<li>Ready for future data import functionality</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="structure">
|
|
<h2>File Structure</h2>
|
|
<div class="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</div>
|
|
</section>
|
|
|
|
<section id="configuration">
|
|
<h2>Configuration</h2>
|
|
<p>The script uses a <code>.env</code> file to store configuration. You can:</p>
|
|
<ol>
|
|
<li><strong>Let the script generate it:</strong> Run <code>./db-start.sh up</code> and answer the prompts</li>
|
|
<li><strong>Pre-create it:</strong> Copy <code>.env.example</code> to <code>.env</code> and modify values</li>
|
|
<li><strong>Edit it manually:</strong> Edit <code>.env</code> directly and run <code>./db-start.sh up</code></li>
|
|
<li><strong>Reconfigure:</strong> Run <code>./db-start.sh reconfigure</code> to re-run the setup wizard</li>
|
|
</ol>
|
|
</section>
|
|
|
|
<section id="requirements">
|
|
<h2>Requirements</h2>
|
|
<ul>
|
|
<li>Docker</li>
|
|
<li>Docker Compose (included with Docker Desktop)</li>
|
|
<li>Bash shell</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="standalone">
|
|
<h2>Standalone Usage</h2>
|
|
<p>This utility can be used independently from AdAstra projects:</p>
|
|
<pre><code># 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</code></pre>
|
|
</section>
|
|
|
|
<section id="troubleshooting">
|
|
<h2>Troubleshooting</h2>
|
|
|
|
<h3>Port already in use</h3>
|
|
<p>If MongoDB or Mongo Express port is already in use:</p>
|
|
<ol>
|
|
<li>Run <code>./db-start.sh reconfigure</code></li>
|
|
<li>Choose a different port (e.g., 27018 for MongoDB, 8082 for Mongo Express)</li>
|
|
</ol>
|
|
|
|
<h3>Docker not running</h3>
|
|
<pre><code># Check Docker status
|
|
docker info</code></pre>
|
|
|
|
<h3>Permission denied</h3>
|
|
<pre><code># Make script executable
|
|
chmod +x db-start.sh</code></pre>
|
|
</section>
|
|
|
|
<section id="notes">
|
|
<h2>Notes</h2>
|
|
<ul>
|
|
<li>Credentials are stored in <code>.env</code> (git-ignored for security)</li>
|
|
<li>Mongo Express is included for easy database management</li>
|
|
<li>Data persists in Docker volumes</li>
|
|
<li>No initialization scripts are run (unlike the backend docker-compose)</li>
|
|
<li>This is standalone and independent from the main project configuration</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="about">
|
|
<h2>About</h2>
|
|
<p>
|
|
<strong>Author:</strong> Julien Gautier (<a href="mailto:jgautier.webdev@gmail.com">jgautier.webdev@gmail.com</a>)
|
|
</p>
|
|
<p>
|
|
<strong>Organization:</strong> AdAstra
|
|
</p>
|
|
<p>
|
|
<strong>Project:</strong> adastra_scripts
|
|
</p>
|
|
<p style="margin-top: 20px; color: #999;">
|
|
These utilities were created to simplify MongoDB management during local development of AdAstra projects.
|
|
</p>
|
|
</section>
|
|
</main>
|
|
|
|
<footer>
|
|
<p>MongoDB Database Utility Documentation</p>
|
|
<p>Generated with care for <span class="meta">AdAstra</span> projects</p>
|
|
<p style="margin-top: 15px; font-size: 0.9em; border-top: 1px solid #ddd; padding-top: 15px;">
|
|
© 2026 AdAstra - All rights reserved
|
|
</p>
|
|
</footer>
|
|
</div>
|
|
</body>
|
|
</html> |