500 lines
18 KiB
HTML
500 lines
18 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 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.<name></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/<appName>/<yyyymmdd_hhmm>/</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=<username>
|
|
MONGO_PASSWORD=<password>
|
|
MONGO_HOST=<host>
|
|
MONGO_PORT=<port>
|
|
APP_NAME=<appName></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/<appName>/<yyyymmdd_hhmi>/
|
|
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://<username>:<password>@<host>:<port>/?ssl=true&replicaSet=globaldb&retrywrites=false&maxIdleTimeMS=120000&appName=@<appName>@" -o ./dumps/<appName>/<yyyymmdd_hhmm></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> |