# Mongonaut: Self-Hosted MongoDB Web GUI

## Migrate from mongo-express

> Category: Guides

---

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

---

# Migrate from mongo-express

This guide shows how to add Mongonaut next to an existing mongo-express setup, test it with the same MongoDB connection and remove mongo-express only after the new workflow is verified.

No MongoDB data migration is required. Mongonaut connects to your existing MongoDB instance through `MONGO_CONNECTION_URL`.

## Prerequisites

- An existing MongoDB deployment.
- Access to the Docker Compose file or container configuration currently running mongo-express.
- The MongoDB hostname, port and credentials used by mongo-express.
- Docker or Docker Compose.
- A generated `MONGONAUT_AUTH_SECRET`.

## 1. Identify the existing mongo-express configuration

Find the MongoDB target used by mongo-express. In many Docker Compose setups, it is represented by environment variables such as host, port, username and password.

Example existing service:

```yaml name="docker-compose.yml"
services:
  mongo-express:
    image: mongo-express
    ports:
      - 8081:8081
    environment:
      ME_CONFIG_MONGODB_SERVER: mongo
      ME_CONFIG_MONGODB_PORT: 27017
      ME_CONFIG_MONGODB_ADMINUSERNAME: root
      ME_CONFIG_MONGODB_ADMINPASSWORD: example
    networks:
      - mongo-network
```

Your actual variable names may differ. The important parts are the MongoDB hostname, port, username, password and auth database.

## 2. Convert the settings to `MONGO_CONNECTION_URL`

Mongonaut uses one MongoDB URI.

From the example above:

```env
MONGO_CONNECTION_URL=mongodb://root:example@mongo:27017/?authSource=admin
```

If your MongoDB does not require authentication:

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

For Atlas:

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

## 3. Add Mongonaut on a separate port

Run both tools side by side during evaluation. If mongo-express already uses port `8081`, map Mongonaut to another host port such as `8082`.

```yaml name="docker-compose.yml"
services:
  mongonaut:
    image: ghcr.io/withzu/mongonaut
    restart: unless-stopped
    ports:
      - 8082:8081
    environment:
      MONGO_CONNECTION_URL: mongodb://root:example@mongo:27017/?authSource=admin
      MONGONAUT_AUTH_SECRET: ${MONGONAUT_AUTH_SECRET}
    networks:
      - mongo-network
```

Create or update `.env`:

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

Start Mongonaut:

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

Open:

```text
http://localhost:8082/setup
```

## 4. Test access

Create the first Mongonaut administrator and verify:

- The expected databases appear.
- Collections can be opened.
- Documents render correctly.
- Search works for representative key/value queries.
- Create, edit and delete operations work only if your team needs write access.
- `MONGONAUT_READONLY=true` disables write operations if you need inspection-only access.

## 5. Configure read-only access if needed

Add read-only mode:

```yaml
services:
  mongonaut:
    environment:
      MONGONAUT_READONLY: "true"
```

For stronger isolation, create a MongoDB user with read-only permissions and use that user's credentials in `MONGO_CONNECTION_URL`.

See [Read-only configuration](/guides/read-only-configuration).

## 6. Review security before sharing

Before giving other users the URL:

- Keep Mongonaut authentication enabled or put it behind an external access layer.
- Use HTTPS through your proxy or tunnel.
- Avoid publishing the port directly to the internet.
- Limit MongoDB user permissions to the minimum needed.

See [Authentication](/security/authentication) and [Cloudflare Zero Trust Tunnel](/security/zero-trust-tunnel).

## 7. Remove mongo-express when ready

After testing, remove or stop the mongo-express service.

```bash
docker compose stop mongo-express
```

If the migration is successful, remove the mongo-express service from the Compose file and run:

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

Keep a rollback path until users confirm that their required workflows work in Mongonaut.

## Common errors

### Mongonaut cannot resolve `mongo`

Mongonaut must be on the same Docker network as MongoDB. Add the same `networks` entry used by mongo-express.

### Port conflict on `8081`

If mongo-express already uses `8081`, publish Mongonaut on a different host port:

```yaml
ports:
  - 8082:8081
```

### Login setup does not appear

If an account already exists, open `/login` instead of `/setup`.

### Writes are disabled

Check `MONGONAUT_READONLY` and the account grant in Mongonaut. Also check whether the MongoDB user itself has write permissions.

## Related links

- [Modern mongo-express Alternative](/mongo-express-alternative)
- [Mongonaut vs mongo-express](/compare/mongonaut-vs-mongo-express)
- [MongoDB GUI with Docker](/mongodb-gui-docker)
- [Authentication](/security/authentication)