Deployment

MikroChat consists of two parts that need to be deployed:

Frontend — static files (HTML, CSS, JavaScript) served by any web host
Backend — Node.js application that handles the API and real-time events

Using the MikroChat CLI (Recommended)

The easiest way to deploy. The mikrochat CLI handles downloading, configuring, and running the API.

# Install the CLI
curl -sSL https://releases.mikrochat.com/install.sh | bash

# Download MikroChat
mikrochat install

# Set up your deployment directory
mkdir /opt/mikrochat && cd /opt/mikrochat
mikrochat init
# Edit mikrochat.config.json with production settings

# Start the API
mikrochat start

The mikrochat init command creates mikrochat.config.json and copies the web app to ./app/. Point your web server at the app/ directory for the frontend.

To upgrade later:

mikrochat upgrade

Manual Deployment

Build from Source

Build both parts with a single command:

npm run build

This creates:

dist/ — optimized frontend files
lib/ — bundled backend (ESM format)

Or build them separately:

npm run build:web   # Frontend only
npm run build:api   # Backend only

Alternatively, download a pre-built release from releases.mikrochat.com which contains both api/mikrochat.mjs and the app/ directory ready to deploy.

Frontend Deployment

The frontend is a static site that can be deployed anywhere:

Netlify, Vercel, Cloudflare Pages
AWS S3 + CloudFront
Any web server (nginx, Apache, Caddy)

Build

npm run build:web

Configure the Frontend

Edit config.js in the dist/ output with your production settings. No rebuild is needed — changes take effect on page reload:

window.MIKROCHAT_CONFIG = {
  API_BASE_URL: 'https://api.chat.example.com',
  AUTH_MODE: 'magic-link',
  ENABLE_OAUTH: false,
  HAS_EMAIL: true,
  MAX_CONTENT_LENGTH: 1000,
  DEBUG_MODE: false
};

Deploy Static Files

Upload the contents of dist/ (or app/ from a release archive) to your hosting provider:

# Example: deploy to a server with rsync
rsync -avz dist/ user@server:/var/www/chat/

Backend Deployment

The backend runs as a Node.js application. Deploy mikrochat.mjs to any Node.js hosting:

VPS (DigitalOcean, Hetzner, Linode)
Docker
Railway, Render, Fly.io
AWS EC2, GCP Compute Engine

Configuration

Create mikrochat.config.json in the working directory, or use environment variables:

{
  "auth": {
    "jwtSecret": "your-production-secret-key",
    "authMode": "magic-link",
    "appUrl": "https://chat.example.com",
    "isInviteRequired": true
  },
  "chat": {
    "initialUser": {
      "userName": "admin",
      "email": "admin@example.com"
    }
  },
  "email": {
    "user": "noreply@example.com",
    "host": "smtp.example.com",
    "password": "smtp-password"
  },
  "server": {
    "port": 3000,
    "host": "0.0.0.0",
    "allowedDomains": ["https://chat.example.com"]
  }
}

Start the Server

Using the CLI:

mikrochat start

Or directly with Node.js:

node mikrochat.mjs

Or with environment variables:

PORT=3000 AUTH_JWT_SECRET=your-secret node mikrochat.mjs

VPS Deployment

Create a systemd service for automatic restarts:

[Unit]
Description=MikroChat Server
After=network.target

[Service]
Type=simple
User=mikrochat
WorkingDirectory=/opt/mikrochat
ExecStart=/usr/bin/node mikrochat.mjs
Restart=always
RestartSec=10
Environment="NODE_ENV=production"

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable mikrochat
sudo systemctl start mikrochat
sudo systemctl status mikrochat

Create a simple Dockerfile:

FROM node:24-slim
WORKDIR /app
COPY mikrochat.mjs .
COPY mikrochat.config.json .
EXPOSE 3000
CMD ["node", "mikrochat.mjs"]

Build and run:

docker build -t mikrochat .
docker run -d \
  --name mikrochat \
  --restart always \
  -p 3000:3000 \
  -v mikrochat-data:/app/mikrochat_db \
  mikrochat

Use PM2 for process management:

npm install -g pm2
pm2 start mikrochat.mjs --name mikrochat
pm2 save
pm2 startup

Reverse Proxy

Put MikroChat behind a reverse proxy for HTTPS and better security.

Caddy
nginx

Caddy provides automatic HTTPS:

# Frontend
chat.example.com {
  root * /var/www/chat
  file_server
  try_files {path} /index.html
}

# Backend API
api.chat.example.com {
  reverse_proxy localhost:3000
}

# Frontend
server {
  listen 443 ssl http2;
  server_name chat.example.com;

  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;

  root /var/www/chat;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
  }
}

# Backend API
server {
  listen 443 ssl http2;
  server_name api.chat.example.com;

  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;

  location / {
    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_buffering off;
    proxy_cache off;
  }
}

Data Persistence

MikroChat stores data in the mikrochat_db directory (configurable via storage.databaseDirectory). Ensure this directory:

Persists across restarts (use Docker volumes or persistent storage)
Is backed up regularly
Has appropriate permissions

CORS Configuration

Configure allowed domains to prevent unauthorized access:

{
  "server": {
    "allowedDomains": [
      "https://chat.example.com"
    ]
  }
}

Use ["*"] only for development.

Rate Limiting

Enable rate limiting to prevent abuse:

{
  "server": {
    "rateLimit": {
      "enabled": true,
      "requestsPerMinute": 100
    }
  }
}

Health Checks

The backend provides a health endpoint for monitoring:

curl http://localhost:3000/health
# Returns: OK

Production Checklist

Before going live:

Set a strong jwtSecret (use openssl rand -base64 32)
Set a STORAGE_KEY to enable encryption at rest
Configure SMTP for magic link emails
Set auth.authMode to "magic-link" or "password" (not "dev")
Configure allowedDomains (not ["*"])
Enable rate limiting
Set up HTTPS via reverse proxy or built-in SSL
Configure data backup for mikrochat_db
Back up your encryption key securely
Set up monitoring and health checks
Test the complete sign-in flow