Compooss

A lightweight, self-hosted MongoDB GUI that drops into any Docker stack or runs as a desktop app — no cloud signup, no fuss.

---

Table of Contents

• What is Compooss?
• Features
• Quick Start
• Development Setup
• Monorepo Structure
• Contributing
• Roadmap
• License

---

What is Compooss?

Compooss is a MongoDB GUI built for local and team development. It runs as a Docker container and sits next to your MongoDB service in a docker-compose stack. Open your browser, connect to any MongoDB instance, and explore — no installation, no account required.

---

Features

Database & Collection Explorer	Browse databases and collections from a sidebar with live stats
Document CRUD	Query, filter, sort, paginate, and edit documents with a Monaco JSON editor
Index Management	Create, drop, hide/unhide indexes — all major index types supported
Schema Analysis	Sample documents to infer schema, field types, frequency, and distributions
Aggregation Pipelines	Visual pipeline builder with stage templates, previews, and saved pipelines
Embedded Shell	Browser-based MongoDB shell with autocomplete, history, and syntax highlighting
Multiple Connections	Save, color-code, and switch between connection profiles stored in IndexedDB

See docs/FEATURES.md for the complete feature breakdown by version.

---

Quick Start

Docker Compose (recommended)

Add Compooss next to your MongoDB service:

services:
  mongo:
    image: mongo:7
    ports:
      - "27017:27017"

  compooss:
    image: abdullahmia/compooss:latest
    ports:
      - "8080:3000"
    depends_on:
      - mongo

Then open http://localhost:8080 and connect to mongodb://mongo:27017.

Docker Run

docker run -p 8080:3000 abdullahmia/compooss:latest

Open http://localhost:8080 and connect to your MongoDB instance. A localhost connection string is automatically redirected to your Docker host, so mongodb://localhost:27017 works from inside the container too.

Require a login

By default anyone who can reach the port can use Compooss. If it's reachable by other people, set a username and password; every page and API call then requires signing in:

docker run -p 8080:3000 \
  -e COMPOOSS_USERNAME=admin \
  -e COMPOOSS_PASSWORD='choose-a-strong-password' \
  abdullahmia/compooss:latest

Each browser gets its own MongoDB connection, so teammates sharing one instance don't switch or disconnect each other. Mark a saved connection Read-only to block every write (inserts, edits, deletes, drops, imports, and shell writes) when pointing at staging or production.

Production (self-hosted)

Use the production compose file included in this repo:

MONGO_ROOT_USERNAME=admin MONGO_ROOT_PASSWORD=secret \
  docker compose -f docker/docker-compose.yml up -d

Desktop app

Prefer not to run a container? Compooss is also a desktop app for macOS, Windows and Linux. It bundles everything it needs and keeps your saved connections on your machine.

Platform	Download
macOS 13.5+ (Apple Silicon)	Compooss-macos-arm64.dmg
macOS 13.5+ (Intel)	Compooss-macos-x64.dmg
Windows 10/11 (x64)	Compooss-windows-x64-setup.exe
Linux (x86_64)	AppImage · .deb

The builds aren't signed yet: on macOS use System Settings → Privacy & Security → Open Anyway after the first launch is blocked, and on Windows choose More info → Run anyway. See docs/DESKTOP.md for details and for building it yourself.

---

Development Setup

This repository is a Turborepo monorepo managed with Bun.

Prerequisites

• Bun 1.x
• Docker (for running a local MongoDB)
• Node.js 20+ (only needed for the standalone server in Docker)

Setup

# 1. Clone the repo
git clone https://github.com/abdullahmia/compooss.git
cd compooss

# 2. Install dependencies
bun install

# 3. Start a local MongoDB
docker compose -f docker/docker-compose.dev.yml up -d

# 4. Start the app
bun dev

Open http://localhost:3000, then connect to mongodb://root:example@localhost:27017/?authSource=admin.

Scripts

Command	Description
bun dev	Start all apps in dev mode (Turbo TUI)
bun build	Build all packages and apps
bun lint	Run ESLint across the monorepo
bun type-check	Run TypeScript type checking
bun desktop:dev	Run the desktop app against the dev server (needs Rust)
bun desktop:build	Build desktop installers for this machine (see docs/DESKTOP.md)

See docs/DEVELOPMENT.md for a deeper guide on the codebase and architecture.

---

Monorepo Structure

compooss/
├── apps/
│   ├── compooss/        # Main MongoDB GUI (Next.js 16)
│   ├── desktop/         # Desktop app (Tauri) that bundles the GUI
│   └── docs/            # Landing page / documentation site
├── packages/
│   ├── types/           # Shared TypeScript types (@compooss/types)
│   └── ui/              # Shared UI components (@compooss/ui)
├── docker/
│   ├── docker-compose.dev.yml   # Local dev — MongoDB only
│   └── docker-compose.yml       # Production — MongoDB + app
├── docs/                # Project documentation
└── Dockerfile           # Multi-stage build for the compooss app

---

Contributing

Contributions of all sizes are welcome — bug reports, feature ideas, docs improvements, and code fixes.

New to the project? Look for issues tagged good first issue — these are small, well-scoped tasks with clear instructions.

Quick checklist before opening a PR:

• Branch from development, not main
• Follow Conventional Commits — enforced by Commitlint
• Run bun lint and bun type-check before submitting

Read docs/CONTRIBUTING.md for the full guide and docs/DEVELOPMENT.md for local setup.

---

Roadmap

• Theming — system, dark, and light mode
• Optional auth for shared dev environments
• Richer query builder and UX improvements

See docs/FEATURES.md and docs/CHANGELOG.md for the full history and planned work.

---

License

MIT © Abdullah Mia