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 before proceeding:

# AES-256 encryption key (64-char hex) – protects OAuth tokens
openssl rand -hex 32

# JWT secret – signs access tokens
openssl rand -base64 48

# Session secret – frontend session cookies
openssl rand -base64 48

Critical: The ENCRYPTION_KEY encrypts stored Mastodon OAuth tokens. It cannot be changed after initial setup without losing access to all connected Mastodon accounts. Store it securely. The same key must be used by both the backend and CLI services.

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 references variables from an .env file. Create it next.

Environment File

Create a .env file in the same directory as your docker-compose.yml:

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

Replace the placeholder values with the secrets you generated. 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

Variable	Description	Required
`JWT_SECRET`	Secret for signing access tokens	Yes
`JWT_EXPIRES_IN`	Access token lifetime (default: 1h)	No
`JWT_REFRESH_TOKEN_EXPIRES_IN`	Refresh token lifetime (default: 7d)	No
`DB_CLIENT_URL`	MongoDB connection string	Yes
`MASTODON_APP_NAME`	Name shown during OAuth (default: Analytodon)	No
`FRONTEND_URL`	Public URL of the frontend	Yes
`MARKETING_URL`	URL of the marketing website	No
`ENCRYPTION_KEY`	64-char hex key for OAuth token encryption	Yes
`EMAIL_HOST`	SMTP server hostname	No
`EMAIL_PORT`	SMTP server port	No
`EMAIL_USER`	SMTP username	No
`EMAIL_PASS`	SMTP password	No
`EMAIL_SECURE`	Use TLS for SMTP (true/false)	No
`EMAIL_FROM_NAME`	Sender name for emails	No
`EMAIL_FROM_ADDRESS`	Sender address for emails	No
`EMAIL_API_KEY`	API key for email service	No
`DISABLE_NEW_REGISTRATIONS`	Block new sign-ups (default: false)	No

Frontend

Variable	Description	Required
`API_URL`	Internal backend URL (e.g. http://backend:3000)	Yes
`SESSION_SECRET`	Secret for session cookies	Yes
`MARKETING_URL`	URL of the marketing website	No
`SUPPORT_EMAIL`	Contact email for support	No
`DISABLE_NEW_REGISTRATIONS`	Block new sign-ups (default: false)	No

CLI

Variable	Description	Required
`MONGODB_URI`	MongoDB connection string	Yes
`MONGODB_DATABASE`	Database name	Yes
`ENCRYPTION_KEY`	Must match the backend's key	Yes
`APP_URL`	Public URL of the application	Yes
`EMAIL_API_KEY`	API key for email service	No
`LOG_LEVEL`	Logging verbosity (default: info)	No

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

View on GitHub