# Mongonaut: Self-Hosted MongoDB Web GUI

## Installation

---

## Pages

- [Overview](https://mongonaut.org/about-mongonaut)
- [Installation](https://mongonaut.org/installation)
- [Docker setup](https://mongonaut.org/mongodb-gui-docker)

### Compare

- [Mongonaut vs mongo-express](https://mongonaut.org/compare/mongonaut-vs-mongo-express)
- [Mongonaut vs MongoDB Compass](https://mongonaut.org/compare/mongonaut-vs-mongodb-compass)

### Guides

- [Migrate from mongo-express](https://mongonaut.org/guides/migrate-from-mongo-express)
- [Read-only configuration](https://mongonaut.org/guides/read-only-configuration)
- [Troubleshooting](https://mongonaut.org/guides/troubleshooting)

### Security

- [Authentication](https://mongonaut.org/security/authentication)
- [Cloudflare Zero Trust Tunnel](https://mongonaut.org/security/zero-trust-tunnel)

### Community

- [FAQ](https://mongonaut.org/community/faq)
- [Contributing](https://mongonaut.org/community/contributing)

---

# Install Mongonaut

Mongonaut is a self-hosted MongoDB web GUI that runs as a Docker container and connects to MongoDB through a standard connection string.

Use this guide when you want to run Mongonaut locally, on a private server, or next to a MongoDB container in Docker Compose.

## Prerequisites

- Docker or Docker Compose installed.
- A MongoDB instance reachable from the Mongonaut container.
- A MongoDB connection string for that instance.
- A strong `MONGONAUT_AUTH_SECRET` unless you explicitly run behind another access control layer with `MONGONAUT_AUTH_MODE=NONE`.

## Quick start with Docker

Mongonaut uses `ACCOUNT` authentication mode by default. On first run, open `/setup` and create the initial administrator account.

```bash
docker run -it --rm \
  -p 8081:8081 \
  -e MONGO_CONNECTION_URL="mongodb://mongo:27017/" \
  -e MONGONAUT_AUTH_SECRET="$(openssl rand -base64 32)" \
  ghcr.io/withzu/mongonaut
```

Open:

```text
http://localhost:8081/setup
```

If MongoDB is not running in the same Docker network under the hostname `mongo`, replace `MONGO_CONNECTION_URL` with the correct URI.

## Docker Compose with MongoDB

This example starts MongoDB and Mongonaut in the same Docker network. It is a good starting point for local development, staging and private internal deployments.

```yaml name="docker-compose.yml"
services:
  mongo:
    image: mongo:latest
    restart: unless-stopped
    volumes:
      - mongo-data:/data/db
    networks:
      - mongo-network

  mongonaut:
    image: ghcr.io/withzu/mongonaut
    restart: unless-stopped
    ports:
      - 8081:8081
    environment:
      MONGO_CONNECTION_URL: mongodb://mongo:27017/
      MONGONAUT_AUTH_SECRET: ${MONGONAUT_AUTH_SECRET}
    depends_on:
      - mongo
    networks:
      - mongo-network

volumes:
  mongo-data:

networks:
  mongo-network:
    driver: bridge
```

Create a `.env` file next to `docker-compose.yml`:

```env name=".env"
MONGONAUT_AUTH_SECRET=<paste output from openssl rand -base64 32>
```

Start both services:

```bash
docker compose up -d
```

Then open `http://localhost:8081/setup` and create the first administrator.

## Connect to an existing MongoDB

Use `MONGO_CONNECTION_URL` to point Mongonaut at your database.

Local MongoDB on the Docker host:

```env
MONGO_CONNECTION_URL=mongodb://host.docker.internal:27017/
```

MongoDB with username and password:

```env
MONGO_CONNECTION_URL=mongodb://app_user:change-me@mongo:27017/app?authSource=admin
```

MongoDB Atlas:

```env
MONGO_CONNECTION_URL=mongodb+srv://user:password@cluster.example.mongodb.net/?retryWrites=true&w=majority
```

For Atlas, make sure the server running Mongonaut is allowed in the Atlas network access list.

## Authentication modes

Mongonaut supports four authentication modes. Configure them with `MONGONAUT_AUTH_MODE`.

| Mode | Use case |
| --- | --- |
| `ACCOUNT` | Default. Create individual Mongonaut accounts with database and collection permissions. |
| `STATIC_PASSWORD` | One shared password for a personal or small trusted setup. |
| `OIDC` | Sign in through an external OpenID Connect provider. |
| `NONE` | No Mongonaut authentication. Only use behind another trust boundary. |

Read the full setup on [Configure Mongonaut authentication](/security/authentication).

## Read-only mode

Set `MONGONAUT_READONLY=true` to disable write operations in the UI and server actions.

```yaml
services:
  mongonaut:
    image: ghcr.io/withzu/mongonaut
    environment:
      MONGO_CONNECTION_URL: mongodb://mongo:27017/
      MONGONAUT_AUTH_SECRET: ${MONGONAUT_AUTH_SECRET}
      MONGONAUT_READONLY: "true"
```

For stronger isolation, also use a MongoDB user whose database permissions are read-only. See [Read-only configuration](/guides/read-only-configuration).

## Environment variables

### Core

| Variable | Description | Default |
| --- | --- | --- |
| `MONGO_CONNECTION_URL` | MongoDB connection string used by Mongonaut. | `mongodb://localhost:27017` |
| `MONGONAUT_READONLY` | If `true`, write operations are disabled. | `false` |
| `MONGONAUT_TIMEOUT` | MongoDB connection and server selection timeout in milliseconds. | `5000` |

### Authentication

| Variable | Description | Default |
| --- | --- | --- |
| `MONGONAUT_AUTH_MODE` | One of `ACCOUNT`, `STATIC_PASSWORD`, `OIDC`, `NONE`. | `ACCOUNT` |
| `MONGONAUT_AUTH_SECRET` | Secret used to sign session cookies. Required for every mode except `NONE`. | unset |
| `MONGONAUT_SESSION_TTL` | Session lifetime in seconds. | `86400` |
| `MONGONAUT_AUTH_PASSWORD` | Shared password for `STATIC_PASSWORD` mode. | unset |

### Accounts

Only used with `MONGONAUT_AUTH_MODE=ACCOUNT`.

| Variable | Description | Default |
| --- | --- | --- |
| `MONGONAUT_SYSTEM_DB` | Hidden internal database used to store Mongonaut accounts. | `__mongonaut` |
| `MONGONAUT_RECOVERY_TTL_MINUTES` | Lifetime of a temporary recovery password. | `30` |

### Login rate limiting

Applies to `STATIC_PASSWORD` and `ACCOUNT` login attempts.

| Variable | Description | Default |
| --- | --- | --- |
| `MONGONAUT_LOGIN_MAX_ATTEMPTS` | Failed attempts per IP before a temporary lockout. | `5` |
| `MONGONAUT_LOGIN_WINDOW_SECONDS` | Window for per-IP attempts. | `900` |
| `MONGONAUT_LOGIN_LOCKOUT_SECONDS` | Lockout duration after the per-IP limit is reached. | `900` |
| `MONGONAUT_LOGIN_GLOBAL_MAX_ATTEMPTS` | Failed attempts instance-wide before a temporary global lockout. | `50` |
| `MONGONAUT_LOGIN_GLOBAL_WINDOW_SECONDS` | Window for instance-wide attempts. | `300` |

### OIDC

Only used with `MONGONAUT_AUTH_MODE=OIDC`.

| Variable | Description | Default |
| --- | --- | --- |
| `MONGONAUT_OIDC_ISSUER` | OIDC issuer URL used for discovery. | unset |
| `MONGONAUT_OIDC_CLIENT_ID` | OIDC client ID. | unset |
| `MONGONAUT_OIDC_CLIENT_SECRET` | OIDC client secret. | unset |
| `MONGONAUT_OIDC_SCOPES` | Requested OIDC scopes. | `openid profile email` |
| `MONGONAUT_OIDC_ALLOWED_EMAILS` | Comma-separated allow list of email addresses. Empty allows every verified user from the IdP. | unset |
| `MONGONAUT_OIDC_REDIRECT_URL` | Full callback URL. If unset, Mongonaut derives it from the incoming request. | derived |

## Security checklist

Before exposing Mongonaut beyond your own machine:

1. Keep `MONGONAUT_AUTH_MODE=ACCOUNT`, `STATIC_PASSWORD` or `OIDC`, or put Mongonaut behind a separate access layer.
2. Set a strong `MONGONAUT_AUTH_SECRET`.
3. Avoid publishing the port directly to the internet without authentication.
4. Use HTTPS at the proxy, tunnel or load balancer layer.
5. Use `MONGONAUT_READONLY=true` when users only need inspection access.
6. Prefer a MongoDB user with the minimum database permissions needed.

For external access, start with [Cloudflare Zero Trust Tunnel](/security/zero-trust-tunnel), a VPN or an authenticated reverse proxy.

## Common errors

### Mongonaut cannot connect to MongoDB

Check that the hostname in `MONGO_CONNECTION_URL` is resolvable from inside the Mongonaut container. In Docker Compose, service names such as `mongo` resolve only when both containers share the same network.

### `/setup` does not appear

`/setup` is only available in `ACCOUNT` mode before the first account exists. After an account is created, use `/login`.

### Missing authentication secret

If `MONGONAUT_AUTH_MODE` is not `NONE`, set `MONGONAUT_AUTH_SECRET` to a strong random value.

### Atlas connection times out

Add the public IP or egress network of the server running Mongonaut to the Atlas access list. Also verify that the URI includes valid database user credentials.

### Login loops behind a proxy

Make sure the public hostname and protocol are forwarded correctly by your proxy. For OIDC, set `MONGONAUT_OIDC_REDIRECT_URL` if Mongonaut cannot derive the correct callback URL.

## Related links

- [MongoDB GUI with Docker](/mongodb-gui-docker)
- [Configure Mongonaut authentication](/security/authentication)
- [Read-only configuration](/guides/read-only-configuration)
- [Troubleshooting](/guides/troubleshooting)
- [Migrate from mongo-express](/guides/migrate-from-mongo-express)