Run & configure with Docker

With the published image, MintJams CMS starts with a single Docker command. The server runtime, all default bundles, and the pre-built Webtop assets are all included in the image.

Prerequisites

  • Docker Desktop or Docker Engine running
  • The URL you will reach it on (for local testing, http://localhost:8080)

Start it the quick way

The command below runs it in the foreground.

docker run --rm \
  -p 8080:8080 \
  -e CMS_PUBLIC_BASE_URL=http://localhost:8080 \
  -v cms-repository:/data/repository \
  -v cms-secrets:/data/secrets \
  --tmpfs /opt/felix/tmp:size=512m,mode=0700 \
  mintjams/cms:0.1.13-beta

Then open http://localhost:8080/ in a browser.

To keep it running in the background, replace --rm with -d --name mintjams.

docker run -d --name mintjams \
  -p 8080:8080 \
  -e CMS_PUBLIC_BASE_URL=http://localhost:8080 \
  -v cms-repository:/data/repository \
  -v cms-secrets:/data/secrets \
  --tmpfs /opt/felix/tmp:size=512m,mode=0700 \
  mintjams/cms:0.1.13-beta

Environment variables

Variable Purpose
CMS_PUBLIC_BASE_URL Required. External base URL (e.g. https://cms.example.org). The SAML SP / IdP redirect URLs are derived from it.
MINTJAMS_CMS_SECRET_KEY_PATH Location of the AES master key. Image default: /data/secrets/secret-key.yml.
CMS_INITIAL_ADMIN_PASSWORD Optional. Initial password for the admin user. If unset, a random password is generated on first boot and written to /data/repository/INITIAL_PASSWORD.txt (mode 0600).
CMS_SP_KEYSTORE_PASSWORD Optional. Password for the SP keystore. If unset, generated randomly and stored encrypted.
CMS_IDP_KEYSTORE_PASSWORD Optional. Password for the IdP keystore. Same as above.

For a fixed deployment behind a reverse proxy, set CMS_PUBLIC_BASE_URL to the externally visible URL (e.g. https://cms.example.org) so the SAML SP / IdP generate correct redirect URLs.

Persistent volumes

To avoid losing data, always persist these two.

Mount Why it must be persistent
/data/repository JCR content, generated SP/IdP keystores (*.p12), and the auto-generated saml2.yml / idp.yml. Losing it means starting from a blank repository.
/data/secrets The AES key that encrypts the keystore passwords in *.yml. Losing it makes the encrypted values unrecoverable — back it up on its own schedule.

Start with docker compose

services:
  cms:
    image: mintjams/cms:0.1.13-beta
    restart: unless-stopped
    environment:
      CMS_PUBLIC_BASE_URL: "http://localhost:8080"
    ports:
      - "8080:8080"
    volumes:
      - cms-repository:/data/repository
      - cms-secrets:/data/secrets
    tmpfs:
      - /opt/felix/tmp:size=512m,mode=0700

volumes:
  cms-repository:
  cms-secrets:

Run docker compose up -d and open http://localhost:8080/.

Zero-configuration SAML

On first boot, the SAML configuration (saml2.yml / idp.yml), the SP/IdP keystores, and certificates are generated automatically. The IdP comes up in "starter mode" trusting the co-located SP, so you can sign in without any manual SAML setup.

Troubleshooting

  • Won't start / CMS_PUBLIC_BASE_URL error — make sure the variable is set (it is required).
  • Port already in use — change the host port, e.g. -p 18080:8080.
  • Data gone after a restart — confirm the named volumes (cms-repository / cms-secrets) are mounted.

Next steps

Once it's up, go to First sign-in & the desktop to sign in as admin and start using the desktop.