julien/adastra_scripts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

(docs): initial docs commit

Browse Source
This commit is contained in:
Julien Gautier
2026-04-28 21:30:54 +02:00
parent 743f7d71c1
commit f804b7abad
3 changed files with 1559 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/dbdump_mongo.html
+500
View File
@@ -0,0 +1,500 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>MongoDB Dump Utility</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;
}
.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;
}
.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;
}
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;
}
</style>
</head>
<body>
<div class="container">
<header>
<h1>MongoDB Dump Utility</h1>
<p>Database Server Backup Management</p>
</header>
<div class="toc">
<h2>Table of Contents</h2>
<ul>
<li><a href="#quick-start">Quick Start</a></li>
<li><a href="#commands">Commands</a></li>
<li><a href="#how-it-works">How It Works</a></li>
<li><a href="#configuration">Configuration Files</a></li>
<li><a href="#directory">Directory Structure</a></li>
<li><a href="#output">Dump Output</a></li>
<li><a href="#accessing">Accessing Dumps</a></li>
<li><a href="#security">Security</a></li>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#installation">Installation</a></li>
<li><a href="#troubleshooting">Troubleshooting</a></li>
<li><a href="#advanced">Advanced Usage</a></li>
<li><a href="#support">Support</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 tool for backing up MongoDB databases from remote or local servers. It manages multiple environment configurations for easy switching between prod, uat, and other environments.
</p>
</section>
<section id="quick-start">
<h2>Quick Start</h2>
<h3>First Run</h3>
<pre><code>./db-dump.sh dump</code></pre>
<p>The script will detect no environments and guide you through creating one. Answer the prompts with:</p>
<ul>
<li><strong>Environment name</strong> (required): e.g., <code>prod</code>, <code>uat</code>, <code>staging</code></li>
<li><strong>MongoDB username</strong> (required): The admin user</li>
<li><strong>MongoDB password</strong> (required): The admin password</li>
<li><strong>MongoDB host</strong> (required): e.g., <code>cluster0.mongodb.net</code></li>
<li><strong>MongoDB port</strong> (required): Usually <code>27017</code> or <code>10255</code></li>
<li><strong>Application name</strong> (required): Used in connection string and dump folder name</li>
</ul>
<h3>Subsequent Runs</h3>
<pre><code>./db-dump.sh dump</code></pre>
<p>The script will show you a list of configured environments and let you choose which one to backup, or create a new environment.</p>
</section>
<section id="commands">
<h2>Commands</h2>
<pre><code># 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</code></pre>
</section>
<section id="how-it-works">
<h2>How It Works</h2>
<ol>
<li><strong>Environment Selection</strong>: On each run, you select from existing environments or create new ones</li>
<li><strong>Credential Storage</strong>: Each environment's credentials are stored in <code>.env.&lt;name&gt;</code> files</li>
<li><strong>MongoDB Connection</strong>: Connects using your credentials with MongoDB Atlas parameters (ssl, replicaSet, etc.)</li>
<li><strong>Dump Creation</strong>: Uses <code>mongodump</code> to create a backup</li>
<li><strong>Timestamped Output</strong>: Dumps are organized as <code>./dumps/&lt;appName&gt;/&lt;yyyymmdd_hhmm&gt;/</code></li>
</ol>
</section>
<section id="configuration">
<h2>Configuration Files</h2>
<p>Each environment is stored in a separate file:</p>
<pre><code>.env.prod # Production environment
.env.uat # UAT environment
.env.staging # Staging environment (if created)</code></pre>
<p>Each file contains:</p>
<pre><code>MONGO_USERNAME=&lt;username&gt;
MONGO_PASSWORD=&lt;password&gt;
MONGO_HOST=&lt;host&gt;
MONGO_PORT=&lt;port&gt;
APP_NAME=&lt;appName&gt;</code></pre>
</section>
<section id="directory">
<h2>Directory Structure</h2>
<div class="file-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/</div>
</section>
<section id="output">
<h2>Dump Output</h2>
<p>Dumps are stored with the following structure:</p>
<pre><code>dumps/&lt;appName&gt;/&lt;yyyymmdd_hhmi&gt;/
admin/ # System databases
config/
myapp/ # Application databases
system.profile/</code></pre>
<p>Each backup preserves the complete database structure and is ready to be restored using <code>mongorestore</code>.</p>
</section>
<section id="accessing">
<h2>Accessing Dumps</h2>
<p>To view or restore a dump:</p>
<pre><code># 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/</code></pre>
</section>
<section id="security">
<h2>Security</h2>
<ul>
<li>Configuration files have restricted permissions (600)</li>
<li>Credentials are stored locally in <code>.env.*</code> files</li>
<li>These files are git-ignored for security</li>
<li>Never commit <code>.env.*</code> files to version control</li>
</ul>
</section>
<section id="requirements">
<h2>Requirements</h2>
<ul>
<li><strong>MongoDB Database Tools</strong>: Download from <a href="https://www.mongodb.com/try/download/database-tools">https://www.mongodb.com/try/download/database-tools</a>
<ul>
<li>Specifically requires <code>mongodump</code> command</li>
</ul>
</li>
<li>Bash shell</li>
<li>Network access to MongoDB server</li>
</ul>
</section>
<section id="installation">
<h2>Installation of MongoDB Database Tools</h2>
<h3>macOS</h3>
<pre><code>brew tap mongodb/brew
brew install mongodb-database-tools</code></pre>
<h3>Linux (Ubuntu/Debian)</h3>
<pre><code>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/</code></pre>
<h3>Windows</h3>
<p>Download the MSI installer from <a href="https://www.mongodb.com/try/download/database-tools">https://www.mongodb.com/try/download/database-tools</a> and run it.</p>
</section>
<section id="troubleshooting">
<h2>Troubleshooting</h2>
<h3>mongodump not found</h3>
<pre><code># Check if MongoDB Database Tools is installed
mongodump --version
# If not installed, see "Installation" section above</code></pre>
<h3>Connection refused</h3>
<ul>
<li>Verify host and port are correct</li>
<li>Check network connectivity to MongoDB server</li>
<li>Ensure firewall allows access</li>
</ul>
<h3>Authentication failed</h3>
<ul>
<li>Verify username and password</li>
<li>Check the user has admin permissions</li>
<li>Confirm the <code>authSource=admin</code> parameter</li>
</ul>
<h3>Port already displaying in error</h3>
<p>The connection string is checked for errors. If you see connection errors, the script displays the exact MongoDB error message.</p>
</section>
<section id="advanced">
<h2>Advanced Usage</h2>
<h3>Manual mongodump command (for reference)</h3>
<p>The script constructs and runs this command automatically:</p>
<pre><code>mongodump --uri "mongodb://&lt;username&gt;:&lt;password&gt;@&lt;host&gt;:&lt;port&gt;/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@&lt;appName&gt;@" -o ./dumps/&lt;appName&gt;/&lt;yyyymmdd_hhmm&gt;</code></pre>
<h3>Scheduling automated backups</h3>
<p>You can schedule regular backups using cron (Linux/macOS):</p>
<pre><code># 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</code></pre>
</section>
<section id="support">
<h2>Support</h2>
<p>For MongoDB connection issues, refer to:</p>
<ul>
<li>MongoDB Documentation: <a href="https://docs.mongodb.com/">https://docs.mongodb.com/</a></li>
<li>Connection String Reference: <a href="https://docs.mongodb.com/manual/reference/connection-string/">https://docs.mongodb.com/manual/reference/connection-string/</a></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;">
This utility was created to enable efficient backup and versioning of MongoDB databases from remote or local servers for AdAstra projects.
</p>
</section>
</main>
<footer>
<p>MongoDB Dump 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>