Skip to content
MikroPlan Docs

Deployment

MikroPlan can run as a static local-only app or as a Node API that serves the app and stores a shared workspace.

Static Local-Only Deployment

Section titled “Static Local-Only Deployment”

Download the static app archive:

Terminal window
curl -sSL -o mikroplan_app.zip https://releases.mikrosuite.com/mikroplan_app_latest.zip
unzip mikroplan_app.zip -d mikroplan_app

Serve the extracted app files from any static host.

In this mode, every browser stores its own workspace in IndexedDB. There is no shared database, collaboration, or auth.

API Deployment

Section titled “API Deployment”

Download the app and API archives:

Terminal window
mkdir -p /opt/mikroplan/app /opt/mikroplan/api


curl -sSL -o /opt/mikroplan/mikroplan_app.zip https://releases.mikrosuite.com/mikroplan_app_latest.zip
curl -sSL -o /opt/mikroplan/mikroplan_api.zip https://releases.mikrosuite.com/mikroplan_api_latest.zip


unzip -q /opt/mikroplan/mikroplan_app.zip -d /opt/mikroplan/app
unzip -q /opt/mikroplan/mikroplan_api.zip -d /opt/mikroplan/api


APP_DIR="$(find /opt/mikroplan/app -mindepth 1 -maxdepth 1 -type d | head -n 1)"
API_DIR="$(find /opt/mikroplan/api -mindepth 1 -maxdepth 1 -type d | head -n 1)"

Start the API:

Terminal window
cd "$API_DIR"
cp mikroplan.config.json.example mikroplan.config.json
node server.mjs --static-root "$APP_DIR"

The API serves:

  • the static app from the configured app directory
  • /config.json for browser runtime settings
  • /api/* for workspace, auth, and event endpoints

The browser app reads /config.json at startup. That public runtime config includes the API base URL, auth mode, and public auth route paths; secrets stay only in mikroplan.config.json, environment variables, or SQLite.

Runtime Config

Section titled “Runtime Config”

MikroPlan uses MikroConf for server configuration. mikroplan.config.json controls host, port, public app URL, auth, and email.

For local testing:

Terminal window
cp mikroplan.config.json.example mikroplan.config.json

For deployment, prefer environment variables for secrets and host-specific settings. CLI flags can also override file settings, for example --port 4500 or --authAllowedDomains example.com.

  • MIKROPLAN_CONFIG_PATH
  • MIKROPLAN_APP_URL
  • MIKROPLAN_HOST
  • MIKROPLAN_PORT
  • MIKROPLAN_STATIC_ROOT
  • MIKROPLAN_DB_PATH
  • MIKROPLAN_AUTH_JWT_SECRET
  • MIKROPLAN_EMAIL_PASSWORD

Collaboration

Section titled “Collaboration”

API mode uses Server-Sent Events to notify connected browser sessions when another session saves the workspace.

Saves include workspace revision headers. If a browser tries to save over a newer workspace, the API responds with a conflict and the browser reloads the latest board instead of overwriting it.

When auth is enabled, serve the app and API from the same site whenever possible. MikroPlan sets an HttpOnly auth cookie after magic-link verification and uses that cookie for the Server-Sent Events stream.

Backups

Section titled “Backups”

Back up both:

  • the SQLite database file, usually data/mikroplan.sqlite
  • exported ZIP archives for complete restore, or JSON data exports when assets are not needed

SQLite files may have -wal and -shm companions while the server is running. Stop the service or use a SQLite-aware backup method for consistent filesystem backups.