Modmail Logviewer

A simple webserver to view your self-hosted Modmail logs.

This is a simple viewer for Modmail logs. It is designed to be self-hosted alongside your Modmail bot instance, allowing you to view your logs in a web interface.

The method of hosting the logviewer depends on your server configurations.

Below are some general instructions to help you get started on a Linux machine.

• A Python 3.12 installation with pip included (Python 3.10-3.12 are supported)
• git for your system

e.g. on Debian with pyenv in bash:

# Install git and pyenv dependencies
sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev curl git \
  libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev libzstd-dev
curl https://pyenv.run | bash

# Auto-loads pyenv every time you start a terminal session
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init - bash)"' >> ~/.bashrc
touch .profile
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.profile
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.profile
echo 'eval "$(pyenv init - bash)"' >> ~/.profile

exec "$SHELL"

# Install Python 3.12
pyenv install 3.12
pyenv global 3.12
python -m pip install -U pip

Run the following shell commands:

# Clone the repository
git clone https://github.com/modmail-dev/logviewer
cd logviewer

# Create and activate virtual environment (optional, but strongly recommended)
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
cp .env.example .env

Edit the .env file (e.g. nano .env) and fill in your MongoDB connection URI.

You can also customize the bind IP and port in the .env file.

Then to start the app, run:

python app.py

You can verify the logviewer is working by navigating to http://<IP_OF_SERVER>:8000 (if you didn't change the bind IP / port) and should be greeted with the Logviewer main page.

To run the program in the background, you can use screen. Or you can use a service manager, such as systemd, which can also auto-restart the logviewer on failure and after system reboot. Remember to set the working directory and the correct Python interpreter path in your service file when using a virtual environment.

To update the logviewer, simply cd into the logviewer directory and run:

git pull
pip install -r requirements.txt

We recommend setting up a reverse proxy (e.g. Nginx) to port forward external port 80 to your internal logviewer port and cache static web contents (tutorial).

To accept requests from a domain instead of your server IP, simply set an A/AAAA record from your DNS provider to forward your domain to your server IP.

Discord's CDN URLs for attachments expire after ~24 hours, which means images in your logs will break. There are two ways to fix this:

Downloads attachments and stores them directly in your MongoDB using GridFS. No third parties involved.

Add to your .env file:

SAVE_ATTACHMENTS=yes

A background task scans your logs collection periodically and downloads any Discord CDN attachment/avatar URLs it finds. Images are compressed to JPEG (configurable) and stored in MongoDB GridFS. When a log page is viewed, archived images are served from /attachments/ instead of the expired Discord URLs.

Routes image requests through a third-party proxy service instead of storing them yourself. Simpler setup but relies on an external service.

You can enable both options together - archived images take priority, and the proxy is used as a fallback for images not yet archived.

Protecting your logs with a login (Discord Oauth2 support) is a premium feature, only available to Premium members.

You can automatically update the logviewer in your Heroku account whenever changes are made to this repo.

To enable auto-updates, fork this repo and install the Pull app in your fork. Then go to the Deploy tab in your Heroku account, select GitHub and connect your fork. Turn on auto-deploy for the master branch.

If you can make improvements in the design and presentation of logs, please make a pull request with the changes.