2019년 3월2020년 5월2021년 8월2022년 11월2024년 2월2025년 4월2026년 7월
README
Mongoku
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.
You can even have mappings between documents to navigate your DB easily.
# Install globally
npm install -g mongoku
# Start the server
mongoku
# 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:
# Install compat version globally
npm install -g mongoku@compat
Using the Docker HUB image
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:
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
# 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:
# Build
docker build -t yournamehere/mongoku .
# Build with a custom base path (e.g. to serve at /mongoku)
docker build --build-arg BASE_PATH=/mongoku -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:
npx simple-git-hooks
Configuration
You can configure Mongoku using environment variables.
Build-time
# Serve Mongoku under a sub-path (e.g. behind a reverse proxy at /mongoku)
# Must be set at build time: BASE_PATH=/mongoku pnpm build
BASE_PATH=/mongoku
Runtime
# 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
# --- OAuth2 PKCE authentication ---
# When MONGOKU_OAUTH_CLIENT_ID is set, OAuth is enabled and all users must
# authenticate through the configured OAuth provider. The application state
# (DB connections, etc.) is shared between all authenticated users.
# The callback URL to register with your provider is: {origin}{base_path}/auth/callback
# OAuth2 client ID (setting this enables OAuth)
MONGOKU_OAUTH_CLIENT_ID=my-client-id
# Use "__CIMD__" for automatic client ID discovery.
# In that mode, Mongoku serves the metadata document at:
# {origin}{base_path}/.well-known/cimd.json
# and uses that URL as the OAuth client_id.
# MONGOKU_OAUTH_CLIENT_ID=__CIMD__
# OpenID Connect issuer URL (endpoints are discovered via .well-known/openid-configuration)
MONGOKU_OAUTH_ISSUER_URL=https://idp.example.com
# Secret for signing session cookies (any random string, keep it secret)
MONGOKU_OAUTH_SESSION_SECRET=change-me-to-a-random-string
# Scopes to request (Default = "openid profile email")
MONGOKU_OAUTH_SCOPES="openid profile email"
# Session duration in seconds (Default = 86400 = 24h)
MONGOKU_OAUTH_SESSION_DURATION=86400
# Restrict access to specific users by their "sub" claim (comma-separated)
# When set, only users whose sub is in this list can log in
MONGOKU_OAUTH_ALLOWED_SUBS=user-id-1,user-id-2
# Require a specific claim in the ID token (format: field=value)
# If the claim is an array, checks that the value is included
MONGOKU_OAUTH_REQUIRED_CLAIM=authority=admin
# 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
