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/Choose how to run Mica

Start here

Choose how to run Mica

Pick the local editor or the self-hosted editor in one minute, and see how they work together on one repository.

3 min read

Mica has two ways to run. They edit the same files in the same Git repository. Pick the one that fits you. You can use both.

Mica is experimental and not ready for production. The API and the content format can still change before 1.0. Read the changelog before you upgrade.

Which one do you need?

Answer one question: who will edit the content?

  • I am a developer and I edit on my own machine. Use the local editor.
  • People who are not developers must edit, and they need a web address. Use the self-hosted editor.
  • Both. Start with the local editor. Add the self-hosted editor when editors join.

The local editor

Run npx @micacms/editor start in your Astro project.

  • It is for the developer.
  • It edits the files in your checkout. Save writes the files, and the Astro dev server reloads them.
  • With astro dev running, an entry shows Preview: the page with the saved changes, before Publish.
  • Publish makes a Git commit and pushes it with your own Git credentials.
  • There is no sign-in, no user, and no database.
  • It listens on your machine only, and it refuses an address on another machine.
  • It uses the Git, and the Git LFS, of your machine.

The self-hosted editor

Run the Docker image ghcr.io/micacms/mica on a server. It runs on amd64 and arm64.

  • It is for editors who are not developers.
  • Editors sign in through an OpenID Connect provider, for example Google. Mica keeps no passwords and no user list.
  • A save is a draft. Drafts are files in a Git clone on the server, and all editors see them.
  • Publish commits the drafts that the editor chooses as one commit and pushes it over HTTPS. The editor is the author, and Mica is the committer.
  • Mica fetches the branch on its own and never merges. If the website changes an entry that has a draft, the editor keeps their version or uses the website's version.
  • Whoever your rules admit is an editor. There are no roles.
  • It shows a live preview of drafts, from a preview container of your website. Each entry can also link to its page on the website.

Side by side

  • Who: local, the developer. Self-hosted, editors.
  • Where it runs: local, your machine. Self-hosted, a server with a web address and HTTPS.
  • Sign-in: local, none. Self-hosted, OpenID Connect.
  • Saves go to: local, files in your checkout. Self-hosted, draft files in a Git clone on the server.
  • Publish does: local, git commit and push. Self-hosted, one commit and a push over HTTPS.
  • Preview: local, yes, while astro dev runs. Self-hosted, yes, with a preview container of the website.
  • Needs a token: local, no. Self-hosted, yes: a token for your Git host.

How they work together

  1. The developer builds the website and the content model with the local editor.
  2. The Astro build writes content/.mica/schema.json. The developer commits it.
  3. The self-hosted editor reads the model from that file in the repository.
  4. Editors save drafts and press Publish. Each Publish is one commit on the branch.
  5. A push starts your normal site build.

The developer pulls the new commits and continues. The website never calls Mica, and Mica does not know where the website is hosted. They meet in the repository.

The content can be in the website repository, or in a repository of its own: see Content in its own repository. Large media can be in Git LFS: see Large files with Git LFS.

Next

Start with the local editor: Getting started. Go to Self-hosting when editors need access.