marimo server (Docker Compose)

This repository provides a minimal Dockerized setup to run a marimo server using Docker Compose. It mounts your local ./marimo directory structure into the container so you can create, edit, and persist notebooks on your host.

Learn more about marimo on the official site: https://marimo.io/.

What this includes

• Dockerized marimo: Built from python:3.13-slim with uv for dependency management.
• Volume mounts: Multiple local directories are mounted into the container:
  • ./marimo/config → /app/.config (marimo configuration)
  • ./marimo/cache → /app/.cache (marimo and uv cache)
  • ./marimo/notebooks → /app/notebooks (your notebooks)
• Config via .env: Uses .env to configure port, base URL (if behind a proxy), optional auth token, debug mode, and watch mode.
• Non-root user mapping: Container runs with your host UID:GID to avoid root-owned files.

Prerequisites

• Docker Engine and Docker Compose installed
• Optional: create or add notebooks in ./marimo/notebooks

Directory structure

• compose.yml: Docker Compose service definition
• Dockerfile: Image definition (installs uv, syncs deps, sets up marimo)
• marimo.sh: Entrypoint script that starts the marimo server
• example.env: Example environment configuration

Configuration (.env)

Create a .env file at the project root to configure the service. Start by copying the example:

cp example.env .env

Edit .env as needed:

• MARIMO_PORT: Port to expose locally (default 2718).

• MARIMO_BASE_URL (optional): Set when serving marimo behind a reverse proxy on a subpath (e.g., /marimo). This is passed to marimo so links, static assets, and routes resolve correctly.

• MARIMO_TOKEN (optional): If set, marimo will require this auth token to access the UI.

• MARIMO_DEBUG_MODE (optional): Enable debug mode for marimo (default false).

• MARIMO_WATCH_MODE (optional): Enable filesystem watch mode for automatic reloading (default false).

  Note: MARIMO_BASE_URL must not end with a trailing slash (use /marimo, not /marimo/).

Example .env:

MARIMO_PORT=2718
# MARIMO_BASE_URL="/marimo"
# MARIMO_TOKEN="my_secret_token"
# MARIMO_DEBUG_MODE="true"
# MARIMO_WATCH_MODE="true"

The Compose file maps ${MARIMO_PORT} on your host to the same port in the container and injects the environment variables into the service.

Install and start

1. Copy and adjust environment file (if not already done):

cp example.env .env

Optionally set your host user and group IDs so files created in ./marimo/notebooks are not owned by the deffault of 1000:1000.

echo "PUID=$(id -u)" >> .env
echo "PGID=$(id -g)" >> .env

2. Build and start the service in the background:

docker compose up -d --build

3. Open marimo in your browser:

http://localhost:2718

If you changed MARIMO_PORT in .env, use that port instead. If you set a MARIMO_TOKEN, your browser must include the token in the query string or you will be prompted accordingly.

Working with notebooks

• Place your .py marimo notebooks (and any data) under .marimo/notebooks.
• Files are persisted on your host and available in the marimo file browser.

Notes

• The container runs as your host user via UID:GID to avoid permission issues on the mounted volume.
• MARIMO_BASE_URL should be set if you serve marimo behind a proxy under a subpath (e.g., Nginx at /marimo).
• This image installs dependencies with uv during build as defined in pyproject.toml/uv.lock.