Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chaitu426/minibox/llms.txt

Use this file to discover all available pages before exploring further.

minibox-compose.yaml is the single source of truth for a multi-container Minibox project. Every field maps directly to the Go struct in internal/models/compose.go. This page documents every supported key with types, defaults, and usage notes.

​
Top-Level Fields

​
name
string
The project name. Used as a prefix for container names (<name>-<service>) and for service discovery scoping. Defaults to the name of the current working directory when omitted.
​
services
map[string]Service
required
A map of named service definitions. Each key becomes the service name and is used for container naming, log prefixes, and hostname resolution inside the project network.

​
Service Fields

Each entry under services supports the following fields.
​
image
string
The container image to run. Required when build is not specified. Accepts any image reference resolvable from Docker Hub (e.g. redis:latest, postgres:16-alpine).
image: redis:latest
​
build
string
Path to a directory containing a MiniBox file. When set, Compose automatically builds the image before starting the service and tags it <project>-<service>. Can coexist with image — build takes precedence.
build: ./backend
​
command
string[]
Override the default command defined in the image. Specified as a list of strings (exec form).
command: ["node", "server.js"]
​
ports
string[]
List of port mappings in hostPort:containerPort format. Uses iptables DNAT rules on the host to forward traffic into the container.
ports:
  - "8080:80"
  - "5432:5432"
​
environment
string[]
List of environment variables injected into the container process, each in KEY=VALUE format.
environment:
  - NODE_ENV=production
  - DATABASE_URL=postgres://db:5432/app
​
volumes
string[]
List of host-to-container bind mounts in hostPath:containerPath format. The host path is mounted directly into the container rootfs at the specified container path.
volumes:
  - ./config:/app/config
  - /var/log/app:/logs
​
depends_on
string[]
List of service names that must be running before this service starts. Compose uses these edges to build the startup DAG and determine topological order.
depends_on:
  - db
  - cache
​
db_mode
boolean
default:"false"
Enables database-optimized runtime settings for the container:
  • /dev/shm is mounted at 256 MB (overridable with shm_size).
  • oom_score_adj is set to -900 to protect the process from OOM eviction.
  • When data is also set, a named persistent volume is provisioned automatically.
db_mode: true
db_mode relaxes the default capability-drop policy so that database engines can perform privileged internal operations (e.g. chown on data directories). Do not enable it for untrusted workloads.
​
data
string (path)
Only meaningful when db_mode: true. Specifies the container path where the named persistent volume is mounted. Minibox provisions a volume directory under DataRoot/volumes/<project>-<service>-data and bind-mounts it at this path, so data persists across down/up cycles.
db_mode: true
data: /var/lib/postgresql/data
​
shm_size
integer (MB)
default:"256"
Override the shared memory size (in megabytes) for the container’s /dev/shm. Only applied when db_mode: true. Useful for tuning PostgreSQL’s shared_buffers or MongoDB’s WiredTiger cache.
shm_size: 512
​
oom_score_adj
integer
default:"0"
Override the Linux OOM killer score adjustment for the container process. Lower values make the process less likely to be killed when the host is under memory pressure. db_mode: true sets this to -900 automatically; use this field to apply a custom value without enabling full db_mode.
oom_score_adj: -500
​
user
string
Run the container process as a specific user or UID. Accepts either a username string or a numeric UID.
user: "1001"

​
Complete Annotated Example

The following file demonstrates every field in a realistic three-service project. 
# Project name — all containers will be prefixed "shop-"
name: shop

services:

  # ── Persistent database ──────────────────────────────────────────────
  db:
    image: postgres:16-alpine
    db_mode: true                  # enables shm, OOM protection, named volume
    data: /var/lib/postgresql/data # persistent volume mounted here
    shm_size: 512                  # 512 MB shared memory for shared_buffers
    environment:
      - POSTGRES_USER=shop
      - POSTGRES_PASSWORD=secret
      - POSTGRES_DB=shopdb
    ports:
      - "5432:5432"

  # ── In-memory cache ──────────────────────────────────────────────────
  cache:
    image: redis:7-alpine
    db_mode: true
    data: /data
    ports:
      - "6379:6379"

  # ── Application server (built from local MiniBox file) ───────────────
  api:
    build: ./api                   # builds image tagged "shop-api"
    command: ["node", "dist/server.js"]
    ports:
      - "3000:3000"
    depends_on:
      - db                         # db starts before api
      - cache                      # cache starts before api
    environment:
      - NODE_ENV=production
      - DATABASE_URL=postgres://shop:secret@db:5432/shopdb
      - REDIS_URL=redis://cache:6379
    volumes:
      - ./uploads:/app/uploads     # bind-mount for user-uploaded files
    user: "1001"
Service names (db, cache, api) are automatically injected into every container’s /etc/hosts, so connection strings like postgres://db:5432/shopdb resolve without any additional DNS setup. See Service Discovery for the full details.

Build docs developers (and LLMs) love

Get started for freeTalk to us