Skip to main content


We provide three Docker images for various deployments: "all-in-one" for quick testing and experiments, a development image for debugging problems, and a production image for all other cases.

All-in-one image is documented in the file in the repository. The rest are covered below.

Production image

Our production image is recommended for most deployments. It does not include PostgreSQL or other backends, so you must run them separately. You can do that with Docker Compose, Kubernetes, or other means.

Setup with Docker Compose

The following steps describe a quick local setup:

  1. Store the following in the docker-compose.yml file:

    image: postgres
    - POSTGRES_USER=username
    - POSTGRES_PASSWORD=password
    - POSTGRES_DB=ferretdb
    - ./data:/var/lib/postgresql/data

    restart: on-failure
    - 27017:27017
    - FERRETDB_POSTGRESQL_URL=postgres://postgres:5432/ferretdb

    name: ferretdb

    postgres container runs PostgreSQL that would store data in the ./data directory on the host. ferretdb runs FerretDB.

  2. Start services with docker compose up -d.

  3. If you have mongosh installed, just run it to connect to FerretDB. It will use credentials passed in mongosh flags or MongoDB URI to authenticate to the PostgreSQL database. You'll also need to set authMechanism to PLAIN. The example URI would look like:


    See Authentication and Securing connection with TLS for more details.

    If you don't have mongosh, run the following command to run it inside the temporary MongoDB container, attaching to the same Docker network:

    docker run --rm -it --network=ferretdb --entrypoint=mongosh mongo \

You can improve that setup by:

Find out more about:

Development image

The development image contains the debug build of FerretDB with test coverage instrumentation, race detector, and other changes that make it more suitable for debugging problems. It can be used exactly the same way as the production image, as described above.