Introduction

The MongoDB Docker image can run initialization scripts from /docker-entrypoint-initdb.d, but how those scripts receive configuration depends on the script type. Shell scripts can read container environment variables directly, while JavaScript init files need a wrapper if you want to inject values such as usernames, database names, or seed data options.

How docker-entrypoint-initdb.d Works

The official image executes files from /docker-entrypoint-initdb.d during first-time initialization, when the data directory is empty. That means these scripts are for bootstrap logic, not for code that should run every container start.

A typical Compose setup looks like this:

1services:
2  mongo:
3    image: mongo:7
4    environment:
5      MONGO_INITDB_ROOT_USERNAME: admin
6      MONGO_INITDB_ROOT_PASSWORD: secret
7      APP_DB_NAME: appdb
8      APP_DB_USER: appuser
9      APP_DB_PASSWORD: apppass
10    volumes:
11      - ./init:/docker-entrypoint-initdb.d

Those environment variables exist in the container process, so shell scripts can use them directly.

Use a Shell Script When You Need Environment Variables

A .sh file is the simplest way to consume custom variables.

1#!/usr/bin/env bash
2set -e
3
4mongosh --username "$MONGO_INITDB_ROOT_USERNAME" \
5  --password "$MONGO_INITDB_ROOT_PASSWORD" \
6  --authenticationDatabase admin <<EOF_JS
7use $APP_DB_NAME
8
9db.createUser({
10  user: "$APP_DB_USER",
11  pwd: "$APP_DB_PASSWORD",
12  roles: [{ role: "readWrite", db: "$APP_DB_NAME" }]
13})
14EOF_JS

Because the shell expands variables before launching mongosh, the values arrive in the executed commands naturally.

Why Plain .js Files Are Different

A .js file in /docker-entrypoint-initdb.d runs as JavaScript, not as a shell script. JavaScript does not automatically interpolate container environment variables like $APP_DB_NAME. If you write this inside a plain init file:

use $APP_DB_NAME

it will not work the way a shell script would. The JavaScript engine has no special awareness of shell environment variables.

That is why developers often think the variables are “missing” when the real problem is the script type.

A Reliable Pattern: Shell Wrapper Plus mongosh

If you prefer JavaScript logic, keep it inside a shell wrapper and pass values explicitly.

1#!/usr/bin/env bash
2set -e
3
4cat <<EOF_JS >/tmp/init.js
5const dbName = "$APP_DB_NAME";
6const user = "$APP_DB_USER";
7const password = "$APP_DB_PASSWORD";
8
9db = db.getSiblingDB(dbName);
10db.createUser({
11  user: user,
12  pwd: password,
13  roles: [{ role: "readWrite", db: dbName }]
14});
15EOF_JS
16
17mongosh --username "$MONGO_INITDB_ROOT_USERNAME" \
18  --password "$MONGO_INITDB_ROOT_PASSWORD" \
19  --authenticationDatabase admin /tmp/init.js

This keeps the environment-variable handling in the shell, where it belongs, while still letting you write database logic in JavaScript.

File Ordering and Idempotence

Scripts are processed in filename order. If one script creates a database and the next inserts seed data, name them accordingly, such as 01-users.sh and 02-seed.sh.

Also remember that these scripts run only on first initialization. If you change the script later but reuse the same persisted volume, Docker will not rerun it automatically. For local testing, you may need to remove the volume and start fresh.

docker compose down -v
docker compose up

Use that carefully, because -v removes persisted database data.

Keep Secrets Out of the Image

Do not bake credentials into your init scripts. Pass them through environment variables or secret-management tooling and keep the scripts generic. That makes the same initialization logic reusable across local development, CI, and staging.

Common Pitfalls

The biggest mistake is expecting plain .js init files to expand shell variables automatically. Another is forgetting that init scripts only run when the database directory is empty, which makes later changes appear ineffective. Developers also often confuse Mongo root credentials with application-user credentials and authenticate against the wrong database. Finally, when values contain special characters, careless shell quoting can break the generated commands.

Summary

• Shell init scripts can read container environment variables directly.
• Plain JavaScript init files do not automatically expand shell variables.
• Use a .sh wrapper when you need env-driven database setup.
• Init scripts run only on first container initialization.
• Preserve quoting carefully so usernames, passwords, and database names are passed correctly.