Skip to content

docs: create .env before docker compose up in the self-hosted quickstart - #505

Merged
loveRhythm1990 merged 1 commit into
matrixorigin:mainfrom
loveRhythm1990:docs/docker-compose-env-setup
Nov 18, 2026
Merged

loveRhythm1990 merged 1 commit into
matrixorigin:mainfrom
loveRhythm1990:docs/docker-compose-env-setup

Conversation

@loveRhythm1990

Copy link
Copy Markdown
Collaborator

Fixes #18

Problem

The self-hosted quickstart in the README goes straight from git clone to docker compose up -d. The compose file requires MEMORIA_MASTER_KEY, so a first-time user gets:

error while interpolating services.api.environment.[]: required variable MEMORIA_MASTER_KEY is missing a value: Set MEMORIA_MASTER_KEY in .env (min 16 chars)

The repo has a .env.example, but nothing in the quickstart or in the error points to it. skills/deployment/SKILL.md already documents the cp .env.example .env step. The README does not.

Change

  • README.md: add cp .env.example .env and a note to set MEMORIA_MASTER_KEY (min 16 chars, for example openssl rand -hex 32) and the embedding settings before docker compose up -d.
  • docker-compose.yml: extend the required-variable message with start from cp .env.example .env. The text avoids : because it sits inside a YAML list item, where a colon followed by a space is parsed as a mapping.

Verification

  • Without a .env file, docker compose config fails and the message now includes the hint.
  • After cp .env.example .env, docker compose config succeeds and renders MASTER_KEY.
  • No containers were started. Only the config interpolation was checked.

Notes

  • .env.example ships MEMORIA_MASTER_KEY=your-master-key-here. That placeholder is 20 characters, so it passes the length check silently. The README now tells users to replace it. Rejecting the placeholder in the compose file would be a separate change.

docker compose up -d fails with 'required variable MEMORIA_MASTER_KEY is
missing a value' because the quickstart never mentions .env. Add the
cp .env.example .env step with the master key hint, and point the compose
error message at .env.example too.
@mergify

mergify Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

This pull request is merged.

@loveRhythm1990
loveRhythm1990 merged commit 3bd6bb8 into matrixorigin:main Nov 18, 2026
9 of 10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: docker compose up -d error

2 participants