# Mongonaut: Self-Hosted MongoDB Web GUI

## Docker setup

---

## 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)

---

# MongoDB GUI with Docker

Run Mongonaut as a self-hosted MongoDB GUI with Docker. This guide includes a minimal `docker run` command, a complete Docker Compose setup with MongoDB, connection string examples and common troubleshooting steps.

## Prerequisites

- Docker installed.
- Docker Compose installed for the Compose example.
- Port `8081` available on the host, or another port chosen by you.
- A generated `MONGONAUT_AUTH_SECRET` for the default account login mode.

Generate a secret:

```bash
openssl rand -base64 32
```

## Option 1: Docker run

Use this when MongoDB is already reachable from the container.

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

Open:

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

Create the first administrator account, then sign in.

## Option 2: Docker Compose with MongoDB and Mongonaut

This setup starts MongoDB and Mongonaut in one private Docker network.

```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 `.env`:

```env name=".env"
MONGONAUT_AUTH_SECRET=<paste a strong random value>
```

Start the stack:

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

Check the containers:

```bash
docker compose ps
```

Open Mongonaut:

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

## Connection strings

Use `MONGO_CONNECTION_URL` for every MongoDB target.

Same Docker Compose network:

```env
MONGO_CONNECTION_URL=mongodb://mongo:27017/
```

MongoDB on the Docker host:

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

MongoDB with credentials:

```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, allow the network or public IP used by the server running Mongonaut.

## Read-only Docker setup

Use `MONGONAUT_READONLY=true` when users should inspect data but not write through Mongonaut.

```yaml name="docker-compose.yml"
services:
  mongonaut:
    image: ghcr.io/withzu/mongonaut
    ports:
      - 8081:8081
    environment:
      MONGO_CONNECTION_URL: mongodb://mongo:27017/
      MONGONAUT_AUTH_SECRET: ${MONGONAUT_AUTH_SECRET}
      MONGONAUT_READONLY: "true"
```

For stronger protection, combine this with a MongoDB user that only has read permissions. See [Read-only configuration](/guides/read-only-configuration).

## Static password Docker setup

For a small trusted setup, use `STATIC_PASSWORD` mode.

```yaml name="docker-compose.yml"
services:
  mongonaut:
    image: ghcr.io/withzu/mongonaut
    ports:
      - 8081:8081
    environment:
      MONGO_CONNECTION_URL: mongodb://mongo:27017/
      MONGONAUT_AUTH_MODE: STATIC_PASSWORD
      MONGONAUT_AUTH_SECRET: ${MONGONAUT_AUTH_SECRET}
      MONGONAUT_AUTH_PASSWORD: ${MONGONAUT_AUTH_PASSWORD}
```

Create `.env`:

```env name=".env"
MONGONAUT_AUTH_SECRET=<strong random secret>
MONGONAUT_AUTH_PASSWORD=<shared login password>
```

## Network configuration

In Docker Compose, service names become DNS names on the same network. That is why `mongodb://mongo:27017/` works in the examples: `mongo` is the service name.

If Mongonaut is in a different Docker network from MongoDB, it will not resolve `mongo`. Put both services on the same network or use a hostname reachable from the Mongonaut container.

## Security notes

- Do not expose Mongonaut publicly without authentication or an external access layer.
- Keep `MONGONAUT_AUTH_SECRET` out of committed Compose files.
- Use `127.0.0.1:8081:8081` when a reverse proxy or tunnel should be the only public entry point.
- Use [Cloudflare Zero Trust Tunnel](/security/zero-trust-tunnel), a VPN or an authenticated reverse proxy for remote access.
- Prefer a MongoDB user with limited permissions for shared deployments.

## Troubleshooting

### `getaddrinfo ENOTFOUND mongo`

The `mongo` hostname is not resolvable from the Mongonaut container. Ensure both services are in the same Compose file and network, or replace `mongo` with a reachable hostname.

### `ECONNREFUSED 127.0.0.1:27017`

Inside a container, `127.0.0.1` points to the container itself. Use the Compose service name, `host.docker.internal`, or a real host/IP address.

### Atlas connection fails

Atlas usually requires an access list entry. Add the egress IP of the server running Mongonaut and verify username, password and database user permissions.

### `/setup` redirects to `/login`

An account already exists. Use `/login` or run the recovery command described in [Authentication](/security/authentication).

### Write buttons are missing or disabled

Check whether `MONGONAUT_READONLY=true` is set or whether your account grant is read-only.

## Related links

- [Install Mongonaut](/installation)
- [Authentication](/security/authentication)
- [Cloudflare Zero Trust Tunnel](/security/zero-trust-tunnel)
- [Troubleshooting](/guides/troubleshooting)
- [Modern mongo-express Alternative](/mongo-express-alternative)