selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

GitHubWebsite
shm logo

Self-host shm

v1.2.7

Privacy-first telemetry collector for self-hosted apps

BetaOpen SourceAGPL-3.0
GitHubWebsite
Docker ComposeCompose file & guide
docker compose up -d
Updated12 hours ago
LanguageGo
Setup difficultyModerate
MobileResponsive
ThemeDark mode
Stars
165
CPU
0.1 vCPU
RAM
64 MB (app) + 256 MB (PostgreSQL)
Storage
~1 KB per snapshot
Port
8080 (HTTP server port for dashboard and API)
Requires
PostgreSQL, PostgreSQL migrations
Docker
ghcr.io/kolapsis/shm
SHM dashboard showing aggregated business metrics and system health in dark modeDashboard overview screenInstance details viewMetrics graph visualization

What is shm?

Self-Hosted Metrics (SHM) is a privacy-first telemetry platform for developers who distribute self-hosted software and need visibility into adoption, versions, and usage. The server is a single Go binary with an embedded AlpineJS/Tailwind dashboard, deployed via Docker Compose alongside PostgreSQL. Client SDKs for Go and Node.js send signed JSON payloads over HTTPS using Ed25519 keys generated on first run; the server stores raw JSONB and dynamically builds KPI cards, tables, and graphs from whatever keys appear. Features include multi-app tracking, automatic GitHub star fetching, public SVG badges for READMEs, rate limiting, and DO_NOT_TRACK opt-out. The dashboard has no built-in authentication — operators must add a reverse proxy with basic auth or ForwardAuth. The main server is AGPL-3.0; the SDKs are MIT-licensed for easier embedding. Minimum resources are ~0.1 vCPU, 64 MB for the app plus 256 MB for PostgreSQL.

Should you self-host shm?

shm scores 45/100 on selfhost.directory (how scoring works) and ranks #77 of 104 in Monitoring & observability. It has 165 GitHub stars.

It shipped 9 stable releases in the past year. The latest, v1.2.7, came out on 29 July 2026. New versions land roughly every 2 weeks.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is AGPL-3.0-licensed and written mostly in Go.

Its closest alternative on selfhost.directory is grafana (90/100, 77 569 stars). It scores higher overall, so compare the two before you pick. See shm vs grafana side by side.

Features

  • Automatic database migrations
  • Cryptographic instance identity
  • DO_NOT_TRACK opt-out
  • Dynamic dashboard
  • GitHub stars integration
  • Go SDK
  • Health check endpoint
  • Multi-application tracking
  • Node.js/TypeScript SDK
  • Ops vs business metrics separation
  • Public SVG badges
  • Rate Limiting

shm README

How to install shm

Install shm with Docker Compose

Docker and Docker Compose; domain name and reverse proxy recommended for production
Environment variables
SHM_DB_DSN, PORT, GITHUB_TOKEN, SHM_RATELIMIT_*, DO_NOT_TRACK, SHM_COLLECT_SYSTEM_METRICS
1. Create the configuration

Create a compose.yml file:

name: shm

services:
  db:
    image: postgres:15-alpine
    container_name: shm-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: shm
      POSTGRES_PASSWORD: ${DB_PASSWORD:-change-me-in-production}
      POSTGRES_DB: metrics
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./migrations:/docker-entrypoint-initdb.d
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shm -d metrics"]
      interval: 10s
      timeout: 5s
      retries: 5

  app:
    image: ghcr.io/kolapsis/shm:latest
    container_name: shm-app
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      SHM_DB_DSN: "postgres://shm:${DB_PASSWORD:-change-me-in-production}@db:5432/metrics?sslmode=disable"
      PORT: "8080"
    ports:
      - "8080:8080"

volumes:
  postgres_data:
2. Download migrations
mkdir -p migrations
curl -sL https://raw.githubusercontent.com/kolapsis/shm/main/migrations/001_init.sql -o migrations/001_init.sql
curl -sL https://raw.githubusercontent.com/kolapsis/shm/main/migrations/002_applications.sql -o migrations/002_applications.sql
3. Start the services
docker compose up -d

Access the dashboard at http://localhost:8080.

Requires reverse proxy (Traefik, Nginx, Caddy) with authentication for production exposure.

How to configure shm

  • DO_NOT_TRACKCompletely disables telemetry when set to true or 1

    Completely disables telemetry when set to true or 1

    values: true, 1

  • GITHUB_TOKENGitHub Personal Access Token for higher API rate limits

    GitHub Personal Access Token for higher API rate limits

  • PORT8080HTTP server port

    HTTP server port

  • SHM_COLLECT_SYSTEM_METRICStrueDisables automatic system metrics collection when set to false or 0

    Disables automatic system metrics collection when set to false or 0

    values: true, false, 1, 0

  • SHM_DB_DSNPostgreSQL connection string

    PostgreSQL connection string

  • SHM_RATELIMIT_ADMIN_BURST10Burst allowance for admin endpoints

    Burst allowance for admin endpoints

  • SHM_RATELIMIT_ADMIN_PERIOD1mTime window for admin endpoints

    Time window for admin endpoints

  • SHM_RATELIMIT_ADMIN_REQUESTS30Max requests per period for /api/v1/admin/*

    Max requests per period for /api/v1/admin/*

  • SHM_RATELIMIT_BRUTEFORCE_BAN15mDuration of IP ban after brute-force detection

    Duration of IP ban after brute-force detection

  • SHM_RATELIMIT_BRUTEFORCE_THRESHOLD5Failed auth attempts before IP ban

    Failed auth attempts before IP ban

  • SHM_RATELIMIT_CLEANUP_INTERVAL10mInterval for cleaning up expired limiters

    Interval for cleaning up expired limiters

  • SHM_RATELIMIT_ENABLEDtrueEnable/disable rate limiting

    Enable/disable rate limiting

    values: true, false

  • SHM_RATELIMIT_REGISTER_BURST2Burst allowance for register endpoints

    Burst allowance for register endpoints

  • SHM_RATELIMIT_REGISTER_PERIOD1mTime window for register endpoints

    Time window for register endpoints

  • SHM_RATELIMIT_REGISTER_REQUESTS5Max requests per period for /v1/register and /v1/activate

    Max requests per period for /v1/register and /v1/activate

  • SHM_RATELIMIT_SNAPSHOT_BURST2Burst allowance for snapshot endpoint

    Burst allowance for snapshot endpoint

  • SHM_RATELIMIT_SNAPSHOT_PERIOD1mTime window for snapshot endpoint

    Time window for snapshot endpoint

  • SHM_RATELIMIT_SNAPSHOT_REQUESTS1Max requests per period for /v1/snapshot (per instance)

    Max requests per period for /v1/snapshot (per instance)

shm releases & version history

Even more releases RSS

More in Analytics

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…