The Problem ContainDB Solves

As developers, we often face these frustrating scenarios:

- Spending hours configuring database environments across different projects
- Dealing with conflicting versions of databases on our development machines
- Struggling with complex Docker commands for simple database tasks
- Managing database persistence, networking, and tools separately
- Lack of a unified interface for different database systems
- MongoDB "Core Dumped" errors on Debian-based systems that are nearly impossible for beginners to troubleshoot

This last point was a major motivation for creating ContainDB. As a developer working on Debian-based systems, I repeatedly encountered the dreaded "Core Dumped" error when trying to install MongoDB natively. After spending countless hours troubleshooting compatibility issues, library dependencies, and system configurations, I realized there needed to be a better way.

ContainDB was born out of these pain points. I wanted a simple CLI tool that could handle all database container operations with minimal effort, allowing me to focus on actual development rather than environment setup.

What is ContainDB?

ContainDB is an open-source CLI tool that automates the creation, management, and monitoring of containerized databases using Docker. It provides a simple, interactive interface for running popular databases and their management tools without needing to remember complex Docker commands or container configurations.

Features

- 🚀 Instant Setup: Get databases running in seconds with sensible defaults
- 🔄 Seamless Integration: All databases run on the same Docker network for easy inter-container communication
- 💾 Data Persistence: Optional volume management for data durability
- 🔐 Security Controls: Interactive prompts for credentials and access control
- 🧩 Extensible Design: Support for multiple database types and management tools
- ⚙️ Customization: Configure ports, restart policies, and environment variables
- 📊 Management Tools: One-click setup for phpMyAdmin, pgAdmin, RedisInsight, and MongoDB Compass
- 🧹 Easy Cleanup: Simple commands to remove containers, images, and volumes
- 🧠 Smart Detection: Checks for existing resources to avoid conflicts
- 🔄 Auto-Rollback: Automatic cleanup of resources if any errors occur during setup
- 📦 Docker Compose Export: Export your database configurations as a docker-compose.yml file that you can run anytime, anywhere
- 📥 Docker Compose Import: Import and deploy services from existing docker-compose.yml files with automatic conflict resolution

Installation

$3

Since these platforms usually have Node.js installed, this is the easiest way:

``bash
npm install -g containdb
`

$3

Use our automated installer script:

`bash
curl -fsSL https://raw.githubusercontent.com/nexoral/ContainDB/main/Scripts/installer.sh | sudo bash -
`

$3

If you have Node.js installed, you can install ContainDB anywhere:

`bash
npm install -g containdb
`

$3

`bash


Clone the repository

`bash
sudo containDB
`

You'll be greeted with an attractive banner and a simple menu system that guides you through the process.

Supported Databases & Tools

| Databases | Management Tools |
|------------|-----------------|
| MongoDB | MongoDB Compass |
| MySQL | phpMyAdmin |
| PostgreSQL | pgAdmin |
| MariaDB | (uses phpMyAdmin)|
| Redis | RedisInsight |

Usage Examples

$3

`bash
sudo containDB


Select "Install Database"

`
✅ PostgreSQL started! Access it at http://localhost:5432
Link it to your DB container 'postgresql-container' inside pgAdmin.
📋 Connection information:
- Container name: postgresql-container
- IP Address: 172.18.0.2
- Port: 5432
🔐 pgAdmin login credentials:
- Email: admin@local.com
- Password: yourpassword
`

$3

`bash
sudo containDB


Select "Install Database"

1. Access the RedisInsight web interface at http://localhost:8001 (or your custom port)
2. Add a new Redis database connection using:
- Host: Your Redis container name (e.g., redis-container)
- Port: 6379
- Use the Docker network's built-in DNS to connect automatically

`
✅ RedisInsight started. Access it at: http://localhost:8001
👉 In the RedisInsight UI, add a Redis database with host: redis-container, port: 6379
(RedisInsight will resolve container name using Docker network DNS.)
`

$3

`bash
sudo containDB


Select "List Databases" to see running containers

`bash
sudo containDB --export
`

Or from the interactive menu:

`bash
sudo containDB


Select "Export Services"

This creates a docker-compose.yml file in your current directory that you can use to recreate your entire database environment on any system with Docker:

`bash


Move the docker-compose.yml to your project

`
┌────────────────────────────┐ ┌─────────────────────┐
│ ContainDB CLI │ │ Running Docker │
│ (export command) │ │ Containers │
└─────────────┬──────────────┘ └──────────┬──────────┘
│ │
│ 1. Identify running containers │
├──────────────────────────────────────────┘
│
│ ┌─────────────────────┐
│ 2. Inspect container details │ Container │
├─────────────────────────────────> Configuration Data │
│ └─────────────────────┘
│
│ 3. Extract settings:
│ - Image name & tag
│ - Container name
│ - Port mappings
│ - Environment variables
│ - Volume mounts
│ - Network configuration
│ - Restart policies
│ - Command overrides
│
▼
┌────────────────────────────┐
│ docker-compose.yml │ ┌─────────────────────┐
│ Generation │ │ Local File System │
└─────────────┬──────────────┘ └──────────┬──────────┘
│ │
│ 4. Write docker-compose.yml file │
└───────────────────────────────────────────┘
`

This diagram shows how the ContainDB export feature captures the configuration of your running containers without copying the actual data stored in volumes. The generated docker-compose.yml provides a template for recreating your database infrastructure but requires separate data migration for full restoration.

---------------------------------------

$3

Import and deploy services from an existing docker-compose.yml file:

`bash
sudo containDB --import /path/to/docker-compose.yml
`

Or from the interactive menu:

`bash
sudo containDB


Select "Import Services"

`bash


Example docker-compose.yml import

`
┌────────────────────────────┐ ┌─────────────────────┐
│ ContainDB CLI │ │ docker-compose.yml │
│ (import command) │ │ File │
└─────────────┬──────────────┘ └──────────┬──────────┘
│ │
│ 1. Read & parse compose file │
├──────────────────────────────────────────┘
│
│ 2. Validate Docker installation
│
│ 3. Check for existing services ┌─────────────────────┐
├─────────────────────────────────>│ Running Docker │
│ │ Containers │
│ └─────────────────────┘
│
│ 4. Check for port conflicts ┌─────────────────────┐
├─────────────────────────────────>│ Host System Ports │
│ └─────────────────────┘
│
│ 5. Set up volumes ┌─────────────────────┐
├─────────────────────────────────>│ Docker Volumes │
│ └─────────────────────┘
│
▼
┌────────────────────────────┐
│ Docker Compose Command │ ┌─────────────────────┐
│ Execution │---------------->│ Deployed Services │
└────────────────────────────┘ └─────────────────────┘
`

This diagram illustrates how ContainDB imports services from a docker-compose.yml file, checking for conflicts and setting up the necessary resources before deploying the services to ensure a smooth integration with your existing environment.

---------------------------------------

Architecture

ContainDB follows a layered architecture that separates concerns and promotes code organization.

`
User Interaction
↓
+-------------------------------------------+
| Main CLI Interface |
+-------------------------------------------+
↑ ↑
| |
+------------------+ +------------------+
| Base Operations | | Tool Helpers |
+------------------+ +------------------+
↑ ↑
| |
+------------------+ +------------------+
| Docker Interface | | System Utilities |
+------------------+ +------------------+
↓
Docker Engine & Host System
`

$3

---------------------------------------

1. Network Creation

ContainDB first ensures that a dedicated Docker network (ContainDB-Network) exists, which allows all containers to communicate with each other using container names as hostnames.

`
┌────────────────────────────┐ creates ┌─────────────────────┐
│ ContainDB CLI │ ───────────────> Docker Network │
└────────────────────────────┘ └─────────────────────┘
`

---------------------------------------

2. Container Orchestration

When you select a database to install, ContainDB:
- Pulls the latest image (if needed)
- Checks for port conflicts
- Sets up necessary volumes for persistence
- Configures environment variables
- Creates and starts the container

`
┌────────────────────────────┐ ┌─────────────────────┐
│ ContainDB CLI │ │ Docker Hub │
└─────────────┬──────────────┘ └──────────┬──────────┘
│ │
│ 1. Pull image │
├──────────────────────────────────────────┘
│
│ 2. Create volume ┌─────────────────────┐
├─────────────────────────────────> Data Volume │
│ └─────────────────────┘
│
│ 3. Run container ┌──────────────────────┐
└────────────────────────────────> Database Container │
└──────────────────────┘
`

---------------------------------------

3. Management Tool Integration

For tools like phpMyAdmin, pgAdmin, or MongoDB Compass, ContainDB handles:
- Tool installation and configuration
- Linking to the appropriate database container
- Providing connection details and credentials

`
┌────────────────────────────┐ ┌─────────────────────┐
│ ContainDB CLI │ ─────────────┐ │ Database Container │
└────────────────────────────┘ │ └─────────────────────┘
│
│ links
▼
┌─────────────────────┐
│ Management Tool │
│ Container/App |
└─────────────────────┘
`

---------------------------------------

4. Auto-Rollback Mechanism

ContainDB implements a robust error handling system that automatically cleans up any partially created resources if something goes wrong:

`
┌────────────────────────────┐
│ Operation Started │
└─────────────┬──────────────┘
│
▼
┌────────────────────────────┐
│ Resource Creation │
└─────────────┬──────────────┘
│
▼
┌───────/\───────┐
│ Error Occurs? │
└───────┬\───────┘
│
Yes │ ┌─────────────────────┐
├─────────────> Stop Containers │
│ └─────────┬───────────┘
│ │
│ ┌─────────▼───────────┐
│ │ Remove Containers │
│ └─────────┬───────────┘
│ │
│ ┌─────────▼───────────┐
│ │ Clean Temp Files │
│ └─────────────────────┘
│
No ▼
┌────────────────────────────┐
│ Operation Completed │
└────────────────────────────┘
`

This ensures your system stays clean even if an operation fails midway, preventing orphaned containers or dangling resources.

---------------------------------------

The Origin Story

ContainDB was created after I found myself repeatedly setting up the same database environments across different projects. The challenges included:

1. Remembering specific Docker commands for each database
2. Managing network connectivity between containers
3. Ensuring data persistence with proper volume configuration
4. Setting up administration tools for each database type

The final straw came when I needed to set up a multi-database project that required MongoDB, PostgreSQL, and Redis - all with different configurations, management tools, and persistence requirements. I spent hours on environment setup instead of actual coding.

The MongoDB Crisis: The breaking point was when I tried to deploy MongoDB on a new Debian-based system. Instead of a working database, I got the cryptic "Illegal instruction (core dumped)" error - a common issue on certain Debian systems due to CPU instruction set incompatibilities with pre-built MongoDB binaries. After wasting a full day on troubleshooting this single issue, I realized containerization was the answer.

I realized that these repetitive tasks could be automated, and ContainDB was born. What started as a personal script evolved into a comprehensive tool that I now use daily and want to share with the developer community.

How ContainDB Helps in Daily Development

ContainDB has become an essential part of my development workflow by:

- Saving Setup Time: What used to take 30+ minutes now takes seconds
- Standardizing Environments: Ensuring consistent database setups across projects
- Simplifying Management: Providing easy access to admin tools and interfaces
- Isolating Services: Preventing conflicts between different database versions
- Managing Resources: Making cleanup and maintenance straightforward
- Bypassing System Compatibility Issues: Avoiding the notorious MongoDB "core dumped" errors on Debian systems
- Visual Database Management: Quick setup of GUI tools like RedisInsight for better productivity

Real-world example: When working on a new microservice project, I can spin up a PostgreSQL instance, link it to pgAdmin, and have a fully functional development environment in less than a minute - all with proper network configuration and persistence.

Troubleshooting

$3

| Issue | Solution |
|-------|----------|
| "Permission Denied" | Ensure you run ContainDB with sudo |
| "Docker Not Found" | Let ContainDB install Docker or run with --install-docker flag |
| "Port Already in Use" | Choose a different port when prompted |
| "Volume Already Exists" | Select to reuse or recreate the volume |
| "Cannot Connect to Database" | Check network settings and credentials |

Contributing

ContainDB is an open-source project that welcomes contributions from everyone. Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. **Open a Pull Request

For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

- The Docker team for creating an amazing containerization platform
- The Go community for providing excellent libraries and tools
- Redis Labs for the RedisInsight tool
- All contributors who have helped improve ContainDB

---