# Mongonaut

## Installation

---

## Pages

- [About Mongonaut](https://mongonaut.org/about-mongonaut)
- [Installation](https://mongonaut.org/installation)

### Security

- [Authentication](https://mongonaut.org/security/authentication)
- [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 available as a Docker image, making it easy to run alongside your MongoDB instance.

## Quick Start

```bash
docker run -it --rm \
  -p 8081:8081 \
  -e MONGO_CONNECTION_URL="mongodb://mongo:27017/" \
  ghcr.io/withzu/mongonaut
```

<Alert type="warning">

**Security Warning:** The example above exposes Mongonaut publicly on port 8081 without authentication. It is your responsibility to properly secure access to Mongonaut in production environments. Consider one of:

- Mongonaut's built in [Authentication](/security/authentication) layer (static password or OIDC)
- [Cloudflare Zero Trust Tunnel](/security/zero-trust-tunnel)
- A reverse proxy with authentication
- Network level security controls

Never expose an unsecured Mongonaut instance directly to the internet, as this could allow unauthorized access to your MongoDB databases.

</Alert>

## Full Docker Compose example

```yaml name="docker-compose.yml"
services:
  mongonaut:
    image: ghcr.io/withzu/mongonaut
    ports:
      - 8081:8081
    environment:
      MONGO_CONNECTION_URL: mongodb://mongo:27017/
    networks:
      - mongo-network
  mongo:
    image: mongo:latest
    ports:
      - 27017:27017
    networks:
      - mongo-network
networks:
  mongo-network:
    driver: bridge
```

## Environment Variables

### Core

| Variable               | Description                                                              | Default                          |
| ---------------------- | ------------------------------------------------------------------------ | -------------------------------- |
| `MONGO_CONNECTION_URL` | Connection string of the target MongoDB                                  | `mongodb://localhost:27017`      |
| `MONGONAUT_READONLY`   | If `true`, all write operations are disabled                             | `false`                          |
| `MONGONAUT_TIMEOUT`    | MongoDB connection and server selection timeout in milliseconds          | `5000`                           |

### Authentication

These variables configure the built in [Authentication](/security/authentication) layer. See that page for setup details.

| Variable                    | Description                                                                                                | Default      |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------ |
| `MONGONAUT_AUTH_MODE`       | Authentication mode. One of `NONE`, `STATIC_PASSWORD`, `OIDC`                                              | `NONE`       |
| `MONGONAUT_AUTH_SECRET`     | Secret used to sign session cookies. Required for any mode other than `NONE`                               | unset        |
| `MONGONAUT_SESSION_TTL`     | Session lifetime in seconds                                                                                | `86400`      |
| `MONGONAUT_AUTH_PASSWORD`   | Shared password used when `MONGONAUT_AUTH_MODE=STATIC_PASSWORD`                                            | unset        |

### OIDC

Only relevant when `MONGONAUT_AUTH_MODE=OIDC`.

| Variable                          | Description                                                                                            | Default                  |
| --------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------ |
| `MONGONAUT_OIDC_ISSUER`           | OIDC issuer URL (used for `.well-known/openid-configuration` discovery)                                | unset                    |
| `MONGONAUT_OIDC_CLIENT_ID`        | OIDC client ID                                                                                         | unset                    |
| `MONGONAUT_OIDC_CLIENT_SECRET`    | OIDC client secret                                                                                     | unset                    |
| `MONGONAUT_OIDC_SCOPES`           | Requested OIDC scopes, space separated                                                                 | `openid profile email`   |
| `MONGONAUT_OIDC_ALLOWED_EMAILS`   | Comma separated list of email addresses allowed to sign in. If empty, every verified user is allowed   | unset                    |
| `MONGONAUT_OIDC_REDIRECT_URL`     | Full callback URL. If unset, Mongonaut derives it from the incoming request                            | derived                  |