# Mongoku

**Repository Path**: mirrors_huggingface/Mongoku

## Basic Information

- **Project Name**: Mongoku
- **Description**: 🔥The Web-scale GUI for MongoDB
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-08
- **Last Updated**: 2025-12-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mongoku

[![CI](https://github.com/huggingface/Mongoku/actions/workflows/ci.yml/badge.svg)](https://github.com/huggingface/Mongoku/actions/workflows/ci.yml)

MongoDB client for the web. Query your data directly from your browser. You can host it locally,
or anywhere else, for you and your team.

It scales with your data (at Hugging Face we use it on a 1TB+ cluster) and is blazing fast for all
operations, including sort/skip/limit. Built on TypeScript/Node.js/SvelteKit.

### Demo

![mongoku](https://huggingface.co/landing/assets/mongoku/mongoku-demo.gif)

## Installation & Usage

### Install Globally

This is the easiest way to use Mongoku:

```bash
# Install globally
npm install -g mongoku

# Start the server
mongoku
mongoku start

# Start with PM2
mongoku --pm2
# Start on a custom port
mongoku --port 8080
# Start in read-only mode
mongoku --readonly

# Stop the server with pm2
mongoku stop
```

#### Compatibility Version

For older MongoDB versions (< 4.2) or AWS DocumentDB (< 5.0), use the `compat` tag which includes an older driver:

```bash
# Install compat version globally
npm install -g mongoku@compat
```

### Using the Docker HUB image

```bash
docker run -d --name mongoku -p 3100:3100 huggingface/mongoku

# Run with customized default hosts
docker run -d --name mongoku -p 3100:3100 \
  --env MONGOKU_DEFAULT_HOST="mongodb://user:password@myhost.com:8888" \
  huggingface/mongoku
```

#### Compatibility Docker Image

For older MongoDB versions (< 4.2) or AWS DocumentDB (< 5.0), use the `compat` tag which includes an older driver:

```bash
docker run -d --name mongoku -p 3100:3100 huggingface/mongoku:compat

# Or use a specific version
docker run -d --name mongoku -p 3100:3100 huggingface/mongoku:2.4.3-compat
```

## Local Development

### Prerequisites

- Node.js 20+
- pnpm (will be auto-installed if using the `packageManager` field)

### Setup & Run

```bash
# Install dependencies
pnpm install

# Start development server (runs on port 3100)
pnpm dev
```

### Formatting

You can use `pnpm lint` and `pnpm format` to format the code.

You can use `npx simple-git-hooks` to set up git hooks

### Docker

#### Build your own image

If you want to build your own docker image, just clone this repository and run the following:

```bash
# Build
docker build -t yournamehere/mongoku .

# Run
docker run -d --name mongoku -p 3100:3100 yournamehere/mongoku

# Run with custom origin (if behind a reverse proxy)
docker run -d --name mongoku -p 3100:3100 \
  --env MONGOKU_SERVER_ORIGIN=https://mongoku.example.com \
  yournamehere/mongoku

# You can also use other MONGOKU_SERVER_* envs to let the reverse proxy determine
# the origin: MONGOKU_SERVER_HOST_HEADER, MONGOKU_SERVER_PROTOCOL_HEADER, ...
```

### Git hooks

You can run this command to set up pre-commit git hooks:

```shell
npx simple-git-hooks
```

## Configuration

You can configure Mongoku using environment variables:

```bash
# Use customized default hosts (Default = localhost:27017)
MONGOKU_DEFAULT_HOST="mongodb://user:password@localhost:27017"

# Exclude specific databases from being displayed (comma-separated list)
MONGOKU_EXCLUDE_DATABASES="admin,config,local"

# See https://svelte.dev/docs/kit/adapter-node#environment-variables-port-and-host
MONGOKU_SERVER_PORT=8000
MONGOKU_SERVER_ORIGIN=https://mongoku.example.com

# Use a specific file to store hosts (Default = $HOME/.mongoku.db)
MONGOKU_DATABASE_FILE="/tmp/mongoku.db"

# Timeout for count in ms (Default = 30000)
MONGOKU_COUNT_TIMEOUT=5000

# Timeout for find queries in ms (Default = undefined, no timeout)
MONGOKU_QUERY_TIMEOUT=30000

# Read preference for queries (primary, primaryPreferred, secondary, secondaryPreferred, nearest)
MONGOKU_READ_PREFERENCE=secondaryPreferred

# Read preference tags as JSON array (used with MONGOKU_READ_PREFERENCE)
# Example: route to analytics nodes with fallback to any node
MONGOKU_READ_PREFERENCE_TAGS='[{"nodeType":"ANALYTICS"},{}]'

# Read-only mode (prevent write queries to mongodb)
MONGOKU_READ_ONLY_MODE=true

# Enable basic auth
MONGOKU_AUTH_BASIC=user:password

# Enable structured logging (JSON output)
# When enabled, all logs are output as JSON with timestamp, level, and request context
# HTTP requests are logged in both modes (simple text format when false, JSON when true)
MONGOKU_STRUCTURED_LOG=true

# Additional headers to log in structured logging (comma-delimited)
MONGOKU_LOG_HEADERS=x-amzn-oidc-identity,x-forwarded-for,x-custom-header

# Other reverse-proxy vars
MONGOKU_SERVER_HOST=127.0.0.1
MONGOKU_SERVER_PROTOCOL_HEADER=x-forwarded-proto
MONGOKU_SERVER_HOST_HEADER=x-forwarded-host
MONGOKU_SERVER_ADDRESS_HEADER=X-Forwarded-For
MONGOKU_SERVER_XFF_DEPTH=1
MONGOKU_SERVER_SHUTDOWN_TIMEOUT=30
MONGOKU_SERVER_SOCKET_PATH=/tmp/socket
```

## License

MIT