Running Database Containers with MiniBox: db run Guide

MiniBox ships a dedicated db run subcommand that wraps the standard container runtime with a set of production-friendly defaults tuned for database engines. It mounts a larger shared memory segment, ensures a full POSIX device environment, raises the I/O scheduling priority, and protects the process from the OOM killer — all while persisting data to a named volume that survives container restarts.

Database containers in MiniBox are experimental. Some kernels and runtime configurations may require a more complete /dev setup than MiniBox currently provides. Test thoroughly in a VM before relying on db run for any persistent workload. See Limitations at the bottom of this page.

What `db run` does differently from `run`

minibox db run passes db_mode=true in the ContainerOptions struct, which unlocks a different code path in the container child process. The table below summarises every behavioural difference:

Feature	`minibox run`	`minibox db run`
Capability drop	✅ Dropped before exec	❌ Skipped (`db_mode=true`) — DB entrypoints need `chown` on first boot
`/dev/shm` size	256 MB (default)	Configurable via `--shm-size` (default 256 MB)
`/dev/pts` (devpts)	Mounted	Mounted — required by `initdb` and DB shell tools
`/tmp` tmpfs	Mounted as `tmpfs` with mode `1777`	Mounted as `tmpfs` with mode `1777`
Device nodes	`null`, `zero`, `random`, `urandom`, `full`, `tty`, `console`, `ptmx`	`null`, `zero`, `random`, `urandom`, `full`, `tty`, `console`, `ptmx`
`io.weight` cgroup	100 (default)	800 — high disk scheduling priority
`oom_score_adj`	0 (default)	-900 — last process to be OOM-killed
Named volume	None	Persistent volume at `DataRoot/volumes/<name>-data`
Detached mode	Optional (`-d`)	Always detached

Why capabilities are kept in `db_mode`

On first boot, database engines such as PostgreSQL’s initdb and MongoDB’s mongod need to chown their data directories and create socket files in locations that require privilege. Dropping all capabilities before exec (as the standard run path does) breaks this initialisation sequence. db_mode=true skips dropContainerCapabilities() so the entrypoint runs with a full capability set. Future versions of MiniBox aim to replace this broad exception with a narrower set of kept capabilities.

`/dev/shm` and shared memory

/dev/shm is mounted as a tmpfs inside every container. In db run, the size is controlled by --shm-size:

PostgreSQL uses shared_buffers backed by /dev/shm; a minimum of 128 MB is recommended.
MongoDB WiredTiger benefits from 256 MB or more.
Redis has minimal shared memory requirements; 64 MB is sufficient.

The mount options are mode=1777,size=<N>m with MS_NOSUID | MS_NODEV | MS_STRICTATIME flags.

Named volumes

db run requires a named volume so database files persist when the container is stopped and restarted. Volumes are stored on the host at:

DataRoot/volumes/<name>-data/

The default DataRoot is /var/lib/minibox. Override it with MINIBOX_DATA_ROOT. The volume is bind-mounted into the container at the path specified by --data. MiniBox creates both the host directory and the container mount target (os.MkdirAll) before the container starts.

Flags reference

--name

string

Named volume identifier. The volume is stored at DataRoot/volumes/<name>-data/ on the host. If omitted, a name is derived from the image name.

--data

string

default:"/var/lib/minibox-data"

Container-side path where the named volume is mounted. Set this to the path your database engine writes its data files (e.g. /var/lib/postgresql/data for Postgres).

--shm-size

integer

default:"256"

Size of /dev/shm in megabytes. Increase for databases that use large shared memory buffers.

-p

string

Port mapping in host:container format. Repeat for multiple ports. See Networking for details.

-e

string

Environment variable in KEY=VALUE format. Repeat for multiple variables. Used to pass credentials and configuration to the database entrypoint.

--cmd

string

Shell command string passed to /bin/sh -c <cmd> when no positional arguments are provided. Useful for wrapping entrypoints that require shell expansion.

-d

flag

Always detached. Accepted for symmetry with minibox run -d but has no additional effect — db run is always detached.

Examples

PostgreSQL
MongoDB
Redis

# Build the image
minibox build -t minibox-postgres ./db-test/postgres

# Start Postgres 15
minibox db run \
  --name pg-data \
  --data /var/lib/postgresql/data \
  --shm-size 256 \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_USER=app \
  -e POSTGRES_DB=mydb \
  minibox-postgres

# Verify it is running
minibox ps

# Connect with psql
psql -h 127.0.0.1 -p 5432 -U app -d mydb

A helper script is available at db-test/postgres/run.sh in the MiniBox repository.

# Build the image
minibox build -t minibox-mongo ./db-test/mongo

# Start MongoDB 7
minibox db run \
  --name mongo-data \
  --data /data/db \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=root \
  -e MONGO_INITDB_ROOT_PASSWORD=secret \
  minibox-mongo

# Verify it is running
minibox ps

# Connect with mongosh
mongosh mongodb://root:secret@127.0.0.1:27017

A helper script is available at db-test/mongo/run.sh.

# Build the image
minibox build -t minibox-redis ./db-test/redis

# Start Redis 7 (small shm is sufficient)
minibox db run \
  --name redis-data \
  --data /data \
  --shm-size 64 \
  -p 6379:6379 \
  minibox-redis

# Verify it is running
minibox ps

# Test the connection
redis-cli -h 127.0.0.1 -p 6379 ping
# PONG

A helper script is available at db-test/redis/run.sh.

Inspecting and managing database containers

Because db run is always detached, use the standard lifecycle commands to manage it:

# View logs
minibox logs <containerID>

# Live resource stats (memory, CPU, I/O)
minibox stats <containerID>

# Open a shell inside the running database container
minibox exec -it <containerID> /bin/sh

# Stop the database (sends SIGTERM)
minibox stop <containerID>

# Remove the container record (volume data is preserved on the host)
minibox rm <containerID>

Removing a container with minibox rm only deletes the container record and its overlayfs layers. The named volume directory at DataRoot/volumes/<name>-data/ is not deleted and can be reused by a new db run invocation with the same --name.

Limitations

The following limitations apply to database containers in the current MiniBox beta:

Experimental status — The db run path is explicitly marked experimental. Not all database engine versions or distributions have been tested.
Capabilities exception is broad — db_mode=true skips all capability drops. A future release will keep only the minimum required capabilities (CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_SETUID, CAP_SETGID).
Some kernels need a fuller /dev — PostgreSQL initdb on some kernel versions requires real device nodes (/dev/null, etc.) to be character devices rather than bind mounts. On kernels that deny mknod inside the container, MiniBox falls back to bind-mounting from the host /dev, which may not always succeed.
No cgroup memory reservation — db run does not currently set memory.low (a soft memory guarantee). Databases competing for memory on a busy host may be subject to aggressive reclaim.
Single-host only — MiniBox has no cluster networking. Database containers are always single-instance and accessible only from the same host.

Get Started

Building Images

Running Containers

Compose Orchestration

Operations

Running Database Containers with MiniBox: db run Guide

What `db run` does differently from `run`

Why capabilities are kept in `db_mode`

`/dev/shm` and shared memory

Named volumes

Flags reference

Examples

Inspecting and managing database containers

Limitations

Build docs developers (and LLMs) love

Get Started

Building Images

Running Containers

Compose Orchestration

Operations

Documentation Index

​What db run does differently from run

​Why capabilities are kept in db_mode

​/dev/shm and shared memory

​Named volumes

​Flags reference

​Examples

​Inspecting and managing database containers

​Limitations

Build docs developers (and LLMs) love

What `db run` does differently from `run`

Why capabilities are kept in `db_mode`

`/dev/shm` and shared memory

Named volumes

Flags reference

Examples

Inspecting and managing database containers

Limitations