(docs): initial docs commit
This commit is contained in:
@@ -0,0 +1,513 @@
|
||||
<!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>
|
||||
Reference in New Issue
Block a user