Self-hosting

MastoMetrics is open source, you can run it for yourself or your community. All you need is a server with Docker and a domain. Users sign in with their Mastodon account, MastoMetrics registers itself on each instance automatically, so there is nothing to configure on the Mastodon side.

This page covers the recommended setup. The README has all configuration options, other ways to deploy and a guide for contributors.

1 Get the code

git clone https://github.com/mastometrics/web.git mastometrics
cd mastometrics
cp .env.dist .env

2 Configure

Fill in the required values in .env. The database connection is set up by Docker Compose.

SESSION_SECRET="$(openssl rand -base64 32)"      # signs session cookies
POSTGRES_PASSWORD="$(openssl rand -base64 24)"   # database password
SITE_URL="https://metrics.example.com"           # the public URL of your deployment

3 Start

Builds the image, starts PostgreSQL, applies the database migrations and starts the app and worker on port 4321.
```
docker compose up -d
```
4 Add HTTPS

Point a reverse proxy at the app, for example Caddy, which takes care of certificates:
```
metrics.example.com {
  reverse_proxy localhost:4321
}
```

5 Sign in and become admin

Open your SITE_URL, sign in with your Mastodon account, then give yourself access to the admin page:

docker compose exec db psql -U mastometrics -c \
  "UPDATE users SET roles = '{admin}' FROM accounts
   WHERE users.\"accountId\" = accounts.id AND accounts.username = '[email protected]';"

Updating

Pull the latest version and rebuild, database migrations are applied automatically on start.

git pull
docker compose up -d --build

Without Docker

Requires Node.js 22.22 or newer and PostgreSQL 14 or newer. Keep npm start running with a process manager such as systemd or pm2. The app and the worker can also run as separate processes, see the README .

cp .env.dist .env               # fill in DATABASE_URL, SESSION_SECRET and SITE_URL
npm ci
npm run build
npm run db:migrate              # apply database migrations
npm start -- --host 0.0.0.0     # starts the app and the worker, loads .env automatically

Using your own database

Instead of the bundled PostgreSQL you can use a managed database by setting DATABASE_URL. Keep these in mind:

SSL certificates: sslmode=require verifies the server certificate. For managed databases with their own CA (DigitalOcean, AWS RDS, ...) add the CA with sslrootcert=..., or add uselibpqcompat=true to encrypt without verifying.
Connection limits: Every process (app, worker, each extra app replica) uses up to 10 connections. Small managed plans allow only 20-25, lower it with connection_limit.
Same region: Imports write each post with its own query. Keep the app, worker and database close together, or imports take minutes instead of seconds.
Storage and backups: Plan for roughly 10 MB per tracked account, growing over time. The database is the only state, back it up regularly.
Privileges: Migrations create the citext extension and tables. To run the app with a restricted user, set RUN_MIGRATIONS=false and migrate with a privileged user.

For example:

DATABASE_URL="postgresql://user:password@host:25060/mastometrics?sslmode=require&uselibpqcompat=true&connection_limit=5"

Before you open it up

The privacy policy and FAQ describe the hosted version at mastometrics.com, review them for your instance. Set CONTACT_HANDLE to your own Mastodon account, it's used for support and contact links. Questions or problems? Open an issue on GitHub .