Modmail Viewer

A Java based frontend for your Modmail bot instance. Serves as an alternative to logviewer.

Built using Javalin, JTE, and Bootstrap 5.

Modmail-Viewer is currently in beta. There may be breaking or otherwise significant changes between versions and the application may be unstable in some circumstances.

Features

Discord OAuth2 authentication based on your modmail roles.
Browsable paginated logs sorted by most recent message and filtered by status.
Mobile friendly design.
Full message Discord Markdown formatting (Including spoilers, custom emojis, and timestamps).

Roadmap

Stats dashboard
Basic API
Dark theme (waiting on bootstrap 5.3)
Search
Snippet editor (requires a bot plugin)
Configurable log sorting

Self-hosting

You should place your modmail-viewer instance behind Cloudflare or some other reverse proxy (such as Caddy) to provide automatic https OR provide the required keys/certs to the application yourself if you plan on using authentication.

Docker

Running the application with Docker is the fastest and best supported way to run modmail-viewer. Additionally, you easily can run it using any 3rd party service that supports running docker containers.

Docker Run

To quickly test modmail-viewer, you can use this docker run command. Make sure to substitute the environment variables for what is applicable to you.

docker run --name modmail-viewer -p 80:80 \
  --env "MODMAIL_VIEWER_MONGODB_URI=mongodb://mongo:27017" \
  --env "MODMAIL_VIEWER_URL=http://127.0.0.1" \
  --env "MODMAIL_VIEWER_DISCORD_OAUTH_CLIENT_ID=1234" \
  --env "MODMAIL_VIEWER_DISCORD_OAUTH_CLIENT_SECRET=abcd" \
  -d ghcr.io/khakers/modmail-viewer:latest

Docker Compose

For long term ease of use, it's highly recommended that you use docker compose. An example docker compose for running only modmail-logviewer.

Note See docker-compose.yml for a compose file that can run modmail, modmail-viewer, and mongodb.

version: "3.7"
services:
  viewer:
    image: ghcr.io/khakers/modmail-viewer:latest
    env_file:
      - .env
    ports:
      - "80:80"
      # uncomment if using SSL
      #- "443:443"
    environment:
      - "MODMAIL_VIEWER_MONGODB_URI=mongodb://mongo:27017"
      - "MODMAIL_VIEWER_URL=http://127.0.0.1"

.env example

Should be located next to your docker-compose.yml, contains secrets.

Note You'll need to create a Discord application (or use the one you created for modmail) and retrieve your OAuth2 client ID and Client secret from the OAuth2 section of the developer dashboard

MODMAIL_VIEWER_DISCORD_OAUTH_CLIENT_ID=123456789
MODMAIL_VIEWER_DISCORD_OAUTH_CLIENT_SECRET=67234rtg3b2otgfhbn3298t7h
MODMAIL_VIEWER_SECRETKEY=secret

Other

Before getting started, you'll need:

A JDK/JRE 17 installation

Download the latest release from GitHub and unzip/tar the modmail-viewer archive

Run the webserver via the included scripts bin/modmail-viewer on linux, and bin/modmail-viewer.bat on windows.

It's recommended to either set up a reverse proxy (such as Cloudflare or Caddy) in front of your modmail-logviewer instance, or enable SSL and provide your own certificate and private key. You can generate one for your domain automatically with Certbot.

To run the webserver in the background, it's recommended you use a service manager such as Systemd.

Environment Variables

Environment Variable	Description
MODMAIL_VIEWER_URL	The URL your modmail viewer instance is reachable at (i.e http://127.0.0.1)
MODMAIL_VIEWER_MONGODB_URI	URI for the MongoDB instance
MODMAIL_VIEWER_DISCORD_OAUTH_CLIENT_ID	Your Discord Application ID. Can be skipped if authentication is disabled.
MODMAIL_VIEWER_DISCORD_OAUTH_CLIENT_SECRET	Your Discord OAuth2 client secret
MODMAIL_VIEWER_SECRETKEY	A randomly generated secret key used for signing auth tokens. ANYONE WITH THIS KEY CAN FORGE AUTHENTICATION TOKENS and impersonate any user. Should be at least 32 characters. If you don't provide one, sessions will not persist across restarts.
MODMAIL_VIEWER_DEV	Enables development features. Do not enable in production. Requires a JDK.
MODMAIL_VIEWER_AUTH_ENABLED	Set to `false` to completely disable authentication. May break some features.
MODMAIL_VIEWER_SSL	Enables SSL and HTTP/2 when connected via https.
MODMAIL_VIEWER_HTTPS_ONLY	Disables the http port and redirects all connections to https. Enabled by default if SSL is enabled. Does not function on localhost.
MODMAIL_VIEWER_SSL_CERT	Path to the SSL certificate pem file. Does not hot reload.
MODMAIL_VIEWER_SSL_KEY	Path to the SSL certificate private key pem file. Does not hot reload.
MODMAIL_VIEWER_HTTP_PORT	Port HTTP traffic will be served at. Defaults to 80
MODMAIL_VIEWER_HTTPS_PORT	Port HTTPS traffic will be served at. Defaults to 443
MODMAIL_VIEWER_SNI	Set SNI to be enabled/disabled. Requires SSL to be enabled
MODMAIL_VIEWER_BRANDING	Text to display in the navbar title. Will display "Modmail-Viewer" by default

lorenzo132 / modmail-viewer