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>
docs/dbrestore_mongo.html
+546
View File
@@ -0,0 +1,546 @@
<!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://&lt;username&gt;:&lt;password&gt;@&lt;host&gt;:&lt;port&gt;/&lt;database&gt;?authSource=&lt;authSource&gt;</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>
docs/dbutils_mongo.html
+513
View File
@@ -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://&lt;username&gt;:&lt;password&gt;@localhost:27017/&lt;database&gt;?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>