Skip to content

Under developmentMica is experimental and not ready for production. The API and the content format can still change, so read the release notes before you upgrade.Follow the releases.

Docs/Configuration

Operate

Configuration

Every environment variable of the self-hosted image and the local editor, with its default.

5 min read

Mica reads its settings from environment variables. Every name starts with MICA_, except PORT and HOST, which hosting platforms already use. A blank value counts as not set. NODE_ENV changes nothing in Mica.

Plain HTTP is allowed only for an address on this machine (localhost, 127.0.0.1 or [::1]), as in a trial or a test. Everything else needs https://. A duration has its unit in the name, in whole units: _HOURS, _MINUTES or _SECONDS. A secret can come from a file, such as a Docker or Kubernetes secret: set the variable with _FILE at the end of its name to the file's path.

The self-hosted image reads the environment and a .env file in its working directory. The compose file passes the .env beside it. The local editor reads the environment only: a site's .env holds the site's settings, not the editor's. Its flags win over the environment.

At the start, the image logs a warning for each MICA_ name that it does not know. That is usually a typo.

Self-hosted image: required

  • MICA_PUBLIC_URL: the address that the browser shows, an origin with https:// and no path, such as https://cms.example.com. For a trial on this machine: http://localhost:6422. It sets the cookie scope, the Origin check and the OIDC redirect.
  • MICA_SESSION_SECRET: at least 32 characters, for example from openssl rand -base64 48. It encrypts the session cookie, so a new value signs everybody out. Or MICA_SESSION_SECRET_FILE: a file that holds it.
  • MICA_REPOSITORY_URL: the HTTPS clone URL of the content repository, without credentials. When the content is in its own repository, this is the URL of that repository, not of the website. See Content in its own repository.
  • MICA_REPOSITORY_TOKEN: the token for Git over HTTPS. GitHub: a fine-grained token with Contents: read and write. GitLab: a project access token with read_repository and write_repository. Or MICA_REPOSITORY_TOKEN_FILE: a file that holds it. Mica reads the file for each Git call, so a short-lived token, such as a GitHub App token, can change without a restart.
  • MICA_OIDC_ISSUER and MICA_OIDC_CLIENT_ID: the OpenID Connect provider and the client that you registered there.
  • At least one of MICA_ADMIT_GROUPS, MICA_ADMIT_DOMAINS, MICA_ADMIT_EMAILS and MICA_ADMIT_SUBJECTS. Mica does not start without a rule that says who may edit.

Self-hosted image: the repository

  • MICA_REPOSITORY_BRANCH: the branch that Mica reads and publishes to. Default: main.
  • MICA_CONTENT_PATH: the content root in the repository, such as content or site/content. Mica writes only below it. Without it, Mica uses the one directory in the repository with a .mica/schema.json. Set it only when the repository has more than one. The top of the repository cannot be the content root.
  • MICA_REPOSITORY_USERNAME: the Git user name for the token. Default: x-access-token on GitHub, oauth2 on GitLab, mica on other hosts.
  • MICA_REPOSITORY_LFS_URL: the Git LFS address, only when the host does not serve it at the clone URL with /info/lfs. Mica also gives the token to this host. Default: the clone URL with /info/lfs. See Large files with Git LFS.
  • MICA_REPOSITORY_SYNC_SECONDS: how often Mica fetches the branch, from 5 to 86400. Default: 60.
  • MICA_DATA_DIR: where Mica keeps its clone, in the folder repository. Default: ./data. The image sets /data, the volume.

Self-hosted image: sign-in and sessions

  • MICA_OIDC_CLIENT_SECRET: the client secret. Leave it out for a public client with PKCE only. Or MICA_OIDC_CLIENT_SECRET_FILE: a file that holds it.
  • MICA_OIDC_SCOPE: the scopes that Mica asks for. Default: openid profile email.
  • MICA_OIDC_GROUPS_CLAIM: the claim that holds the person's groups. Default: groups.
  • MICA_ADMIT_GROUPS: groups whose members may edit, separated by commas.
  • MICA_ADMIT_DOMAINS: email domains whose verified addresses may edit, separated by commas. With Google, the account must also belong to a Workspace whose domain (hd) is in this list.
  • MICA_ADMIT_EMAILS: verified email addresses that may edit, separated by commas.
  • MICA_ADMIT_SUBJECTS: issuer|subject pairs that may edit, separated by commas.
  • MICA_SESSION_TTL_HOURS: the longest session, in hours. Default: 8.
  • MICA_SESSION_IDLE_HOURS: a session without a request ends after this many hours. Default: 4.
  • MICA_SIGNIN_MAX_ATTEMPTS: sign-in starts from one address in the window. Default: 10.
  • MICA_SIGNIN_WINDOW_MINUTES: the window for that limit, in minutes. Default: 15.

Self-hosted image: the server

  • HOST: the address to listen on. Default in the image: 0.0.0.0.
  • PORT: the port to listen on. Default: 6422.
  • MICA_TRUST_PROXY: read the client address from X-Forwarded-For. Set it to true only behind a proxy that you control. Default: false.
  • MICA_MAX_UPLOAD_BYTES: the largest upload, in bytes. Default: 26214400 (25 MB). Raise it for large files, such as a ZIP file or a GPX track.
  • MICA_LOG_LEVEL: debug, info, warn, error or silent. Default: info.
  • MICA_SITE_URL: the website's address, such as https://example.com. With a url in the model, an entry shows "Open on website". See Preview changes.

Self-hosted image: live preview

MICA_PREVIEW_UPSTREAM turns the live preview on. See Add the live preview in the self-hosting guide.

  • MICA_PREVIEW_UPSTREAM: the http:// address of the dev server in the container network, such as http://preview:4321.
  • MICA_PREVIEW_URL: the public origin of the preview. It is optional. Default: the address in MICA_PUBLIC_URL with preview. in front of the host name, such as https://preview.cms.example.com for https://cms.example.com. Set it only for another name on the same site. It must have another host name than MICA_PUBLIC_URL, and it has no path. A name set there needs https://, except a name under localhost for a trial on this machine. MICA_PREVIEW_URL without MICA_PREVIEW_UPSTREAM is an error.

Mica answers the requests for the preview's host name on its own port, PORT. With the preview on, MICA_PUBLIC_URL must have a host name, not localhost, an IP address or a name of one label, such as cms. Mica refuses these, because a name beside them is on another site. For a trial on this machine: MICA_PUBLIC_URL=http://cms.localhost:6422. The preview is then http://preview.cms.localhost:6422.

Preview image

The preview image ghcr.io/micacms/preview reads these variables. They are not variables of the Mica image.

  • MICA_PUBLIC_URL: the editor's address, the same value as for Mica. The page of the preview answers only that editor.
  • MICA_CONTENT_PATH: the content root, when the repository has more than one. The same as for Mica.
  • MICA_PREVIEW_SITE_PATH: the folder of the website in the repository, when no astro.config is above the content root.

The other variables of the container reach the dev server, for a website that reads its own. An image of your own sets MICA_PREVIEW_EDITOR to the editor's address instead of MICA_PUBLIC_URL. Mica does not read that variable.

Self-hosted image: agents

See Edit with an agent.

  • MICA_MCP: true lets agents connect at /mcp. Each person allows each agent on a consent page, after they sign in. Default: false.
  • MICA_MCP_PUBLISH: true lets a person also allow an agent to publish. Default: false: agents save drafts, and people publish them.

Local editor

npx @micacms/editor start [content directory] takes these flags:

  • --content, -c: the content root. Default: MICA_CONTENT_ROOT, else the directory with a .mica/schema.json (at most three levels down; not in node_modules or a hidden directory), else ./content. With more than one such directory, name the one to use.
  • --port, -p: the port. Default: PORT, else 6422.
  • --host: the address to listen on. Only a loopback address is allowed. Default: HOST, else 127.0.0.1.
  • --no-open: do not open the browser.

It also reads these variables:

  • MICA_CONTENT_ROOT: the content root, when no path is given.
  • MICA_PUBLIC_URL: the editor's own address. It must be on this computer. Default: http://localhost: and the port.
  • MICA_LOCAL_PUBLISH: false shows the pending changes, but Publish does not commit or push. Default: true. Only the local editor reads it.
  • MICA_MCP_PUBLISH: true gives agents the publish tool, at /mcp and in npx mica mcp. Default: false. npx mica mcp --allow-publish does the same.
  • MICA_SITE_URL, MICA_MAX_UPLOAD_BYTES and MICA_LOG_LEVEL, as for the image.

The local editor needs no setting for Preview, for Git LFS or for a Git submodule. It finds the dev server of astro dev itself, and it uses the Git and the Git LFS of your computer.

For work on Mica itself

The local editor only, not the image:

  • MICA_ADMIN_ORIGINS: more browser origins that may call the admin API, separated by commas. The Vite dev server of the editor UI needs it.
  • MICA_ADMIN_DIR: serve the editor UI from another directory.