546 lines
19 KiB
HTML
546 lines
19 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 Restore 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 Restore Utility</h1>
|
|
<p>Standalone Backup Restoration Tool</p>
|
|
</header>
|
|
|
|
<div class="toc">
|
|
<h2>Table of Contents</h2>
|
|
<ul>
|
|
<li><a href="#quick-start">Quick Start</a></li>
|
|
<li><a href="#how-it-works">How It Works</a></li>
|
|
<li><a href="#interactive">Interactive Navigation</a></li>
|
|
<li><a href="#backup-detection">Backup Detection</a></li>
|
|
<li><a href="#example">Example Use Case</a></li>
|
|
<li><a href="#summary">Restore Summary</a></li>
|
|
<li><a href="#connection">Connection String</a></li>
|
|
<li><a href="#directory">Directory Structure</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="#manual">Manual Restore Command</a></li>
|
|
<li><a href="#related">Related Tools</a></li>
|
|
<li><a href="#workflow">Workflow Example</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 restoring MongoDB database backups created with <code>db-dump.sh</code>. It provides interactive navigation through backup directories and restores them to a configured MongoDB instance.
|
|
</p>
|
|
</section>
|
|
|
|
<section id="quick-start">
|
|
<h2>Quick Start</h2>
|
|
|
|
<h3>1. Configure Connection Details</h3>
|
|
<pre><code>cp .env.example .env</code></pre>
|
|
|
|
<p>Edit <code>.env</code> with your MongoDB connection details:</p>
|
|
<pre><code>MONGO_USERNAME=admin
|
|
MONGO_PASSWORD=password
|
|
MONGO_HOST=localhost
|
|
MONGO_PORT=27017
|
|
MONGO_DATABASE=adastradb
|
|
MONGO_AUTHSOURCE=admin</code></pre>
|
|
|
|
<h3>2. Restore a Backup</h3>
|
|
<pre><code>./db-restore.sh</code></pre>
|
|
|
|
<p>The script will:</p>
|
|
<ol>
|
|
<li>Verify MongoDB tools are installed</li>
|
|
<li>Load your configuration</li>
|
|
<li>Ask for the path to your backups directory</li>
|
|
<li>Guide you through the directory structure</li>
|
|
<li>Show a summary of what will be restored</li>
|
|
<li>Ask for confirmation</li>
|
|
<li>Restore the backup</li>
|
|
</ol>
|
|
</section>
|
|
|
|
<section id="how-it-works">
|
|
<h2>How It Works</h2>
|
|
|
|
<h3>Configuration</h3>
|
|
|
|
<p>The script requires a <code>.env</code> file with these variables:</p>
|
|
<ul>
|
|
<li><code>MONGO_USERNAME</code> - MongoDB admin username</li>
|
|
<li><code>MONGO_PASSWORD</code> - MongoDB admin password</li>
|
|
<li><code>MONGO_HOST</code> - MongoDB server hostname/IP</li>
|
|
<li><code>MONGO_PORT</code> - MongoDB server port</li>
|
|
<li><code>MONGO_DATABASE</code> - Target database name</li>
|
|
<li><code>MONGO_AUTHSOURCE</code> - Authentication source (usually <code>admin</code>)</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="interactive">
|
|
<h2>Interactive Navigation</h2>
|
|
|
|
<p>The script intelligently navigates through your backup directory structure:</p>
|
|
<div class="file-structure">dumps/
|
|
├── prod/ - Choose this
|
|
│ ├── 20260414_1632/ - Then this
|
|
│ │ └── (database folders) - Then this
|
|
│ └── 20260414_1645/
|
|
└── uat/
|
|
└── 20260414_1700/</div>
|
|
|
|
<p>At each level, the script:</p>
|
|
<ol>
|
|
<li>Shows available subdirectories</li>
|
|
<li>Asks you to choose one</li>
|
|
<li>Continues until it finds <code>.bson</code> files (backup data)</li>
|
|
</ol>
|
|
</section>
|
|
|
|
<section id="backup-detection">
|
|
<h2>Backup Detection</h2>
|
|
|
|
<p>The script automatically stops navigation when it finds a directory containing <code>.bson</code> files, which are the actual backup data files.</p>
|
|
|
|
<p>Example backup structure:</p>
|
|
<pre><code>~/Works/dbdump/dumps/
|
|
└── bo-uat-cosmodb/
|
|
└── 20260414_1732/
|
|
└── admin/ - BSON files here
|
|
├── system.profile.bson
|
|
└── system.version.bson</code></pre>
|
|
</section>
|
|
|
|
<section id="example">
|
|
<h2>Example Use Case</h2>
|
|
|
|
<p>Given this backup structure:</p>
|
|
<pre><code>~/Works/dbdump/dumps/
|
|
├── bo-prod-cosmodb/
|
|
│ └── 20260414_1600/
|
|
│ └── AdAstra/
|
|
│ ├── collection1.bson
|
|
│ └── collection1.metadata.json
|
|
└── bo-uat-cosmodb/
|
|
└── 20260414_1732/
|
|
└── AdAstra/
|
|
├── orders.bson
|
|
└── orders.metadata.json</code></pre>
|
|
|
|
<p>Restore process:</p>
|
|
<pre><code>./db-restore.sh
|
|
|
|
# Script asks: Dumps path: ~/Works/dbdump/dumps
|
|
# Shows: 1) bo-prod-cosmodb 2) bo-uat-cosmodb
|
|
# You choose: 2
|
|
# Shows: 1) 20260414_1732
|
|
# You choose: 1
|
|
# Shows: 1) AdAstra
|
|
# You choose: 1
|
|
# Script finds BSON files and shows summary</code></pre>
|
|
</section>
|
|
|
|
<section id="summary">
|
|
<h2>Restore Summary</h2>
|
|
|
|
<p>Before executing the restore, the script displays:</p>
|
|
<pre><code>MongoDB Connection:
|
|
Host: localhost
|
|
Port: 27017
|
|
Username: admin
|
|
Database: adastradb
|
|
AuthSource: admin
|
|
|
|
Backup Source:
|
|
Location: /home/user/Works/dbdump/dumps/bo-uat-cosmodb/20260414_1732
|
|
Backup files: 42
|
|
Total size: 250M</code></pre>
|
|
|
|
<p>You must confirm with "yes" to proceed.</p>
|
|
</section>
|
|
|
|
<section id="connection">
|
|
<h2>Connection String</h2>
|
|
|
|
<p>The script constructs the MongoDB connection string as:</p>
|
|
<pre><code>mongodb://<username>:<password>@<host>:<port>/<database>?authSource=<authSource></code></pre>
|
|
|
|
<p>Example:</p>
|
|
<pre><code>mongodb://admin:password@localhost:27017/adastradb?authSource=admin</code></pre>
|
|
</section>
|
|
|
|
<section id="directory">
|
|
<h2>Directory Structure</h2>
|
|
<div class="file-structure">dbrestore/
|
|
├── db-restore.sh # Main script
|
|
├── .env # Configuration (created by you, git-ignored)
|
|
├── .env.example # Example configuration
|
|
├── .gitignore # Git ignore rules
|
|
└── README.md # This file</div>
|
|
</section>
|
|
|
|
<section id="security">
|
|
<h2>Security</h2>
|
|
<ul>
|
|
<li>Configuration file (<code>.env</code>) has restricted permissions</li>
|
|
<li>Contains sensitive credentials (username, password)</li>
|
|
<li>Never commit actual <code>.env</code> file to version control</li>
|
|
<li>Use <code>.env.example</code> as template</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>mongorestore</code> command</li>
|
|
</ul>
|
|
</li>
|
|
<li>Bash shell</li>
|
|
<li>Network access to MongoDB server</li>
|
|
<li>Backup files created by <code>db-dump.sh</code> or <code>mongodump</code></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>mongorestore not found</h3>
|
|
<pre><code># Check if MongoDB Database Tools is installed
|
|
mongorestore --version
|
|
|
|
# If not installed, see "Installation" section above</code></pre>
|
|
|
|
<h3>.env file not found</h3>
|
|
<pre><code># Copy the example configuration
|
|
cp .env.example .env
|
|
|
|
# Edit with your values
|
|
nano .env # or your favorite editor</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>
|
|
<li>Verify MongoDB service is running (if local)</li>
|
|
</ul>
|
|
|
|
<h3>Authentication failed</h3>
|
|
<ul>
|
|
<li>Verify username and password in <code>.env</code></li>
|
|
<li>Check user has sufficient permissions</li>
|
|
<li>Confirm <code>authSource</code> is correct (usually <code>admin</code>)</li>
|
|
</ul>
|
|
|
|
<h3>No BSON files found</h3>
|
|
<ul>
|
|
<li>Make sure you're pointing to the root of dumps directory</li>
|
|
<li>Navigate through subdirectories until you reach the folder with actual backup files</li>
|
|
<li>BSON files are typically deep in the directory structure</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="manual">
|
|
<h2>Manual Restore Command</h2>
|
|
|
|
<p>For reference, here's the command the script executes:</p>
|
|
<pre><code>mongorestore --uri "mongodb://user:pass@host:port/db?authSource=admin" /path/to/dumps</code></pre>
|
|
</section>
|
|
|
|
<section id="related">
|
|
<h2>Related Tools</h2>
|
|
<ul>
|
|
<li><strong>dbutils/db-start.sh</strong> - Start MongoDB in Docker for restoring locally</li>
|
|
<li><strong>dbdump/db-dump.sh</strong> - Create backups from remote MongoDB servers</li>
|
|
<li><strong>dbrestore/db-restore.sh</strong> - Restore backups to a MongoDB instance (this tool)</li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section id="workflow">
|
|
<h2>Workflow Example</h2>
|
|
|
|
<p>Complete workflow to backup and restore:</p>
|
|
<pre><code># 1. Backup from production MongoDB (in dbdump folder)
|
|
cd ~/Works/dbdump
|
|
./db-dump.sh dump
|
|
# Select prod environment and wait for backup</code></pre>
|
|
</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 Restore 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> |