Self-Hosting Analytodon

Analytodon is open source under GPL-3.0. You can run your own instance with full control over your data and infrastructure.

Architecture Overview

Analytodon consists of the following components:

• Backend (REST API) – NestJS application handling authentication, data processing, and the Mastodon OAuth flow
• Frontend (Web App) – Remix application providing the analytics dashboard
• CLI (Cron Jobs) – oclif-based tool that runs scheduled data synchronization from Mastodon
• MongoDB – Database for storing account data, post metrics, and analytics history
• SMTP (optional) – For sending email reports

A reverse proxy (Caddy, nginx, or Traefik) is required in production – only the frontend needs to be publicly accessible.

Prerequisites

• Docker and Docker Compose
• A domain name with DNS pointing to your server
• A reverse proxy (Caddy, nginx, or Traefik)
• (Optional) SMTP credentials for email reports

Generate Secrets

Analytodon requires three cryptographic secrets. Generate them directly into a .env file before proceeding – this keeps the values out of your clipboard and terminal history:

# AES-256 encryption key (64-char hex) – protects OAuth tokens
echo "ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env

# JWT secret – signs access tokens
echo "JWT_SECRET=$(openssl rand -base64 48)" >> .env

# Session secret – frontend session cookies
echo "SESSION_SECRET=$(openssl rand -base64 48)" >> .env

Docker Compose

Create a docker-compose.yml with the following configuration:

services:
  backend:
    image: ghcr.io/blazer82/analytodon-backend:latest
    environment:
      - JWT_SECRET=${JWT_SECRET}
      - JWT_EXPIRES_IN=1h
      - JWT_REFRESH_TOKEN_EXPIRES_IN=7d
      - DB_CLIENT_URL=mongodb://mongo:27017/analytodon
      - MASTODON_APP_NAME=Analytodon
      - FRONTEND_URL=https://your-domain.com
      - MARKETING_URL=https://your-domain.com
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
    depends_on:
      - mongo
    restart: unless-stopped

  frontend:
    image: ghcr.io/blazer82/analytodon-frontend:latest
    ports:
      - "127.0.0.1:3002:3002"
    environment:
      - API_URL=http://backend:3000
      - SESSION_SECRET=${SESSION_SECRET}
      - MARKETING_URL=https://your-domain.com
    depends_on:
      - backend
    restart: unless-stopped

  cli:
    image: ghcr.io/blazer82/analytodon-cli:latest
    environment:
      - MONGODB_URI=mongodb://mongo:27017
      - MONGODB_DATABASE=analytodon
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
      - APP_URL=https://your-domain.com
    depends_on:
      - mongo
    restart: unless-stopped

  mongo:
    image: mongo:8
    volumes:
      - mongo-data:/data/db
    restart: unless-stopped

volumes:
  mongo-data:

The compose file reads these secrets from the .env file you generated earlier (see the Environment File section below).

Environment File

The Generate Secrets step above already wrote your three secrets into a .env file. Keep it in the same directory as your docker-compose.yml – Docker Compose automatically reads variables from it and substitutes them into the ${...} placeholders in the compose file. The file looks like this:

# Generated secrets (see Generate Secrets above)
ENCRYPTION_KEY=your-64-char-hex-key
JWT_SECRET=your-jwt-secret
SESSION_SECRET=your-session-secret

For email reports and additional configuration options, refer to the environment variables reference below.

Reverse Proxy

Only the frontend (port 3002) needs public access. The backend and CLI communicate internally via Docker networking.

Example Caddy configuration:

your-domain.com {
    reverse_proxy localhost:3002
}

If you use nginx or Traefik, configure them to proxy all traffic to port 3002.

Start Analytodon

Launch all services:

docker compose up -d

Open https://your-domain.com in your browser. You should see the Analytodon login page. Register your first account and connect it to your Mastodon instance.

Environment Variables

The tables below list the most important configuration options for each service.

Backend

Frontend

CLI

Refer to the README in the GitHub repository for the complete and most up-to-date list of environment variables.

Resources

• GitHub Repository – Source code, README, and detailed setup instructions
• Issue Tracker – Report bugs or request features
• Mastodon – Follow for updates or reach out for help