From e6c2f17e4984845a9f60a31696ea61c5b0d1a25e Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Sat, 30 May 2026 12:30:29 -0400
Subject: [PATCH 01/15] may 2026 update to the unrecommended host list
---
choose-host/unrecommended-hosts.md | 20 +++++++++++++++++---
1 file changed, 17 insertions(+), 3 deletions(-)
diff --git a/choose-host/unrecommended-hosts.md b/choose-host/unrecommended-hosts.md
index fa01194..2060fb8 100644
--- a/choose-host/unrecommended-hosts.md
+++ b/choose-host/unrecommended-hosts.md
@@ -12,14 +12,12 @@ description: These hosts are hosts we, and members of our community have had lit
- Repl.it is a provider aimed at hosting websites. Meaning, it does not have the proper tools and features to properly host the Modmail bot.
- This host is particularly problematic, and there have been many documented unexplainable issues that occur when hosting your bot with this method. Because of this it is **strongly discouraged** for use.
-
### Bot-hosting.net
- [Website](https://bot-hosting.net/)
- bot-hosting.net is a free or low cost hosting provider that bases their hosting platform on the common free and open-source panel [Pterodactyl](https://pterodactyl.io/).
- Hosting on any Pterodactyl panel based host is already challenging, however, bot-hosting.net shares IP addressess among users, which has resulted in high numbers of our users reporting rate limits being applied to their bot. In other words: your bot will randomly stop working with nothing you can do to fix it.
-
### Wispbyte
- [Website](https://wispbyte.com/)
@@ -37,7 +35,6 @@ description: These hosts are hosts we, and members of our community have had lit
### Kairo Hositing
- Discord Only
- Kairo Hosting is a discord server based hosting provider that provides free hosting for Modmail bots. However, the Modmail team was provided evidence that the host expressed what is in our opinion, poor security hygiene, by failing to isolate the filesystems of bots. This allows any user hosting with Kairo hosting to access all files, including token and database connection details of all other bots hosted by this provider. This is a major security risk, with this, we have no choice but to not recommend this host.
-
1x Screenshot
@@ -46,6 +43,23 @@ description: These hosts are hosts we, and members of our community have had lit
+
+
+Stephen from the Modmail Team's Update on May 30th, 2026
+
+> The Modmail team always attempts to work in good faith with a host when we find a security vulnerability. We have been working with this host and it appears they are making a good faith attempt to address the security vulnerabilities we have found. Even after these fixes, we still advise caution when using this host.
+
+
+
+### baud.host
+- [Website](https://baud.host)
+- baud.host is a low cost hosting provider that is primarily operated by Kybo Group, a Roblox products group.
+- baud.host does not allow users to provide their MongoDB Connection URI, this is not recommended as it locks users into a single host, and limits a user's ownership of their data. We were not able to conduct a test on the security of their locally hosted database, but if managed improperly, it could also be a security concern.
+- baud.host uses Stripe for payment verification, however, appears to use their own processing flow, instead of the one provided by Stripe. We were unable to conduct a test on security, but this could be a security concern.
+- Kybo Group claims compliance with HIPAA, GDPR, DPDPA, with an ISO27001, PCI DSS, SOC 1 Type 2, and SOC 2 Type 2 certifications, however, attempts to verify this have failed. You can conduct your own certification search with the [IAF](https://www.iafcertsearch.org/search/certified-entities?search=Kybo%20Group).
+- Some users have reported feagures in latest updates not working with this host.
+
+
{% hint style="danger" %}
### Why These Are Not Recommended
These hosts generally:
From b0bbfd62ae78de54f39195159267cb813673d42d Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Sat, 30 May 2026 12:49:27 -0400
Subject: [PATCH 02/15] Append the Heroku update instructions from old doc to
bottom of the heroku.md instructions
---
installation/heroku.md | 36 ++++++++++++++++++++++++++++++++++--
updating (1).md | 38 --------------------------------------
2 files changed, 34 insertions(+), 40 deletions(-)
delete mode 100644 updating (1).md
diff --git a/installation/heroku.md b/installation/heroku.md
index 7b6e299..7bc4891 100644
--- a/installation/heroku.md
+++ b/installation/heroku.md
@@ -49,10 +49,42 @@ Next, to keep your Modmail and Logviewer up to date, you will need to install th
Your GitHub should now be all set. Next step, [create a Heroku account](heroku.md#create-a-heroku-account) to deploy your bot.
-## Create a Heroku account
+## Updating
+You can update Modmail on your Heroku account whenever changes are made to the repository. If you want to update while hosting locally (not Heroku), simply type `git pull` in your terminal and install the requirements again with `pipenv install`.
-## Updating
+## Forking the repo
+
+Before you get started, you must [fork](https://github.com/modmail-dev/modmail/fork) the repo first if you are using Heroku and want to update the bot.
+
+### Syncing a fork branch from the web UI
+
+1. On GitHub, navigate to the main page of the forked repository that you want to sync with the upstream repository.
+2. Select the Sync fork dropdown.
+
+ 
+3. Then click Update branch.
+
+ 
+
+If the changes from the upstream repository cause conflicts, GitHub will prompt you to create a pull request to resolve the conflicts.
+
+### I want to enable automatic updates
+
+1. Create a GitHub account
+2. [Fork](https://github.com/modmail-dev/modmail/fork) the repository
+3. Add GITHUB\_TOKEN into your configuration variables from https://github.com/settings/tokens with the repo scope ([Guide](https://github.com/modmail-dev/modmail/wiki/Installation-\(cont.\)#4-how-to-obtain-your-github\_token---required-for-the-update-command-)).
+4. Link your GitHub account to heroku 
+5. Turn on automatic deploys 
+6. Restart the bot
+
+### I want to update the bot once
+
+[Click here to create a new pull request to your fork](https://github.com/modmail-dev/modmail/pull/new/master). Select `compare across forks`, make the base repository `yourusername/modmail` and ensure the branch is set to master. Put any title you want and create the pull request. On the page that comes after this, merge the pull request.
+
+You then want to go to your modmail application in Heroku, connect your modmail fork via the `Deploy` tab and deploy the `master` branch.
+
+You can turn on auto-deploy for the master branch if you don't want to go through the process of logging into Heroku and deploying the branch every time changes to the repo are made in the future. However, you will have to make a pull request to update your fork every time.
\ No newline at end of file
diff --git a/updating (1).md b/updating (1).md
deleted file mode 100644
index e2485ce..0000000
--- a/updating (1).md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Updating
-
-## Updating Modmail
-
-You can update Modmail on your Heroku account whenever changes are made to the repository. If you want to update while hosting locally (not Heroku), simply type `git pull` in your terminal and install the requirements again with `pipenv install`.
-
-## Forking the repo
-
-Before you get started, you must [fork](https://github.com/modmail-dev/modmail/fork) the repo first if you are using Heroku and want to update the bot.
-
-### Syncing a fork branch from the web UI
-
-1. On GitHub, navigate to the main page of the forked repository that you want to sync with the upstream repository.
-2. Select the Sync fork dropdown.
-
- 
-3. Then click Update branch.
-
- 
-
-If the changes from the upstream repository cause conflicts, GitHub will prompt you to create a pull request to resolve the conflicts.
-
-### I want to enable automatic updates
-
-1. Create a GitHub account
-2. [Fork](https://github.com/modmail-dev/modmail/fork) the repository
-3. Add GITHUB\_TOKEN into your configuration variables from https://github.com/settings/tokens with the repo scope ([Guide](https://github.com/modmail-dev/modmail/wiki/Installation-\(cont.\)#4-how-to-obtain-your-github\_token---required-for-the-update-command-)).
-4. Link your GitHub account to heroku 
-5. Turn on automatic deploys 
-6. Restart the bot
-
-### I want to update the bot once
-
-[Click here to create a new pull request to your fork](https://github.com/modmail-dev/modmail/pull/new/master). Select `compare across forks`, make the base repository `yourusername/modmail` and ensure the branch is set to master. Put any title you want and create the pull request. On the page that comes after this, merge the pull request.
-
-You then want to go to your modmail application in Heroku, connect your modmail fork via the `Deploy` tab and deploy the `master` branch.
-
-You can turn on auto-deploy for the master branch if you don't want to go through the process of logging into Heroku and deploying the branch every time changes to the repo are made in the future. However, you will have to make a pull request to update your fork every time.
From f326f4ec7277301f72514910808aef4cdfe3eb56 Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Sat, 30 May 2026 12:54:05 -0400
Subject: [PATCH 03/15] Update choosing a host, mostly formatting
---
choose-host/README.md | 17 ++++++++++-------
1 file changed, 10 insertions(+), 7 deletions(-)
diff --git a/choose-host/README.md b/choose-host/README.md
index 05eabf8..2fc6784 100644
--- a/choose-host/README.md
+++ b/choose-host/README.md
@@ -63,25 +63,26 @@ Modmail is a very lightweight bot, very minimal resources are required.
> Do you have more than 1000 members in your server?
-If not: you likely do not need more than 512mb of memory and 1 CPU core.
+**If not:** you likely do not need more than 512mb of memory and 1 CPU core.
-If yes: you can potentially get away with the minimum spec, but you should consider upgrading.
+**If yes:** you can potentially get away with the minimum spec, but you should consider upgrading.
> Do you require your Modmail bot to be online with 0 downtime?
-If yes: you want to steer away from free hosts, and in most cases, local hosting as well.
+**If yes:** you want to steer away from free hosts, and in most cases, local hosting as well.
+*Clarification: for our team, "local hosting" is hosting on a computer that you have in your house, not a VPS in a datacenter*
> Do you plan to have significant usage of your bot?
-If yes (ie plugins, hundreds of active threads at once - being replied to not sitting dormant, etc): you can potineitally get away with the minimum spec, but you should consider upgrading.
+**If yes (ie many plugins, hundreds of active threads at once - being replied to not sitting dormant, etc):** you can potineitally get away with the minimum spec, but you should consider upgrading.
-If you aren't sure: Talk with our [community and team](https://discord.gg/nfErcs7mDM).
+**If you aren't sure:** Talk with our [community and team](https://discord.gg/nfErcs7mDM).
-If no: use the minimum spec above.
+**If no:** use the minimum spec above.
> How technical are you?
-If you struggle with technology, you may want to consider a PaaS (Platform as a Service) host, which handles the backend of a server for you. If you have strong technical proficiencies, a VPS or local hosting is likely a better fit for you.
+If you struggle with technology, you may want to consider a PaaS (Platform as a Service) host, which handles the backend of a server for you. If you have strong technical proficiencies (or a willingness to research and learn), a VPS or local hosting is likely a better fit for you.
{% endstep %}
@@ -115,6 +116,8 @@ For nearly all cases, we recommend a cheap Virtual Private Server from one of ou
For users who do not wish to pay, we recommend locally hosting the bot from hardware you already own, like a Raspberry Pi, or old computer you can keep running 24/7 in your house.
In situations where you significantly struggle with technology, a PaaS option *may* be better with you. Feel free to consult with our [team](https://discord.gg/nfErcs7mDM) if you don't know if this is the best option for you.
+
+If you want the simplest possible method of getting your bot online, we would recommend one of our two native Modmail hosts, [buymeacoffee.com/modmaildev](https://buymeacoffee.com/modmaildev) or [modmail.lvl.lol](https://modmail.lvh.lol). Both run a panel that is purpose built and custom developed solely for the purpose of running Modmail.
{% endhint %}
{% hint style="danger" %}
From 13e5307a2c8f57750f802fa36434ecc76ff35756 Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 11:12:03 -0400
Subject: [PATCH 04/15] Update updating instructions, and old-docs typo/rename
---
SUMMARY.md | 2 +-
old-docs/README.md | 2 +-
updating.md | 6 ++++++
3 files changed, 8 insertions(+), 2 deletions(-)
diff --git a/SUMMARY.md b/SUMMARY.md
index 26e844a..db636c4 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -31,7 +31,7 @@
* [Config References]()
* [Configuration Variables](config-references/config-vars.md)
* [Color Names](config-references/color-names.md)
-* [OLD DOCS](old-docs/README.md)
+* [Archives Documentation](old-docs/README.md)
* [Installation](installation-1.md)
* [Installation (continued)](installation-continued.md)
* [Configure Modmail and Logviewer](configure-modmail-and-logviewer.md)
diff --git a/old-docs/README.md b/old-docs/README.md
index eb737dd..312773e 100644
--- a/old-docs/README.md
+++ b/old-docs/README.md
@@ -2,4 +2,4 @@
Anything in this header exists as a place-holder to our origninal docs using the GitHub Wiki function.
-They will eventually be adapted, updated, and moved elsewhere on this site. Do not expect links you copy today to remain valud into the future.
\ No newline at end of file
+They will eventually be adapted, updated, and moved elsewhere on this site. Do not expect links you copy today to remain valid into the future.
\ No newline at end of file
diff --git a/updating.md b/updating.md
index f3c8c45..215083b 100644
--- a/updating.md
+++ b/updating.md
@@ -34,3 +34,9 @@ Else, it means that your repository is a fork and must update (aka sync) it inde
Run the `git pull` command above locally after syncing your fork.
And then, be sure to restart your bot to apply the update.
+
+## Breaking Changes and Update Compatibility
+
+For the most part, it is not necessary to worry about updating from one version to the other. However, before updating, take a look at the most recent changelog entry to see if there is a **"Breaking"** note. If you are updating from a very old version, start at the version you are currently on, and scroll up to the current version, and check to see if there are any **Breaking** notes. If there are none, you can update without issue. (Remember to backup your files.)
+
+If there is a **Breaking** entry in the changelog, read to see what steps are required to maintain functionality. If you need assistance, contact the Modmail Team in our official [support server *preferred*](https://discord.gg/cnUpwrnpYb) or on [GitHub](https://github.com/modmail-dev)
From 56935044fc95b8539b89ce151e5b195a3984df24 Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 11:25:25 -0400
Subject: [PATCH 05/15] Assorted Installation Updates
---
installation/README.md | 42 ++++++++++++++++++++++++------------------
1 file changed, 24 insertions(+), 18 deletions(-)
diff --git a/installation/README.md b/installation/README.md
index 3b7d333..d719c92 100644
--- a/installation/README.md
+++ b/installation/README.md
@@ -6,9 +6,7 @@ description: Modmail hosting and installation guide.
Modmail is a self-hosted bot. This unfortunately means that there's **no** public bot invite. Furthermore, due to the inner workings of the bot and its highly customisable interfaces, you will need to host your own dedicated Modmail bot.
-This section provides setup instructions for Modmail on many hosting methods, both **free\* and paid**.
-
-\*Some free options require a credit card for verification.
+This section provides setup instructions for Modmail on many hosting methods, both **free[^1] and paid**.
Here are the basic requirements for hosting your Modmail bot. You will find instructions on obtaining and using them in later sections.
@@ -27,6 +25,7 @@ Here are the basic requirements for hosting your Modmail bot. You will find inst
{% hint style="warning" %}
**Note:** There are two components for Modmail: the bot component and the Logviewer component. You will need **both** to take full advantage of Modmail.
+
{% endhint %}
## Create a Discord bot
@@ -120,7 +119,7 @@ Discord should prompt you to choose a server to invite your bot, followed by a l
{% hint style="info" %}
-You **must leave on** all permissions excepted for _Administrator_ (optional). However, we recommend allowing _Administrator_ for ease of setup and to avoid complications with Discord permissions.
+You **must leave on** all permissions excepted for _Administrator_ (optional). However, we recommend allowing _Administrator_ during the setup process for ease of setup and to avoid complications with Discord permissions. Once you have fully setup and began to use the bot, you should restrict permissions to only those necessary.
{% endhint %}
@@ -265,7 +264,7 @@ You finished the MongoDB steps! At this point, your bot should still be **offlin
Once you have finished the previous steps, gather and save the variables listed below as they will be needed to run your bot in later steps:
* `TOKEN` - The token to run your Modmail application under your Discord bot account
-* `LOG_URL` **- \[Optional]** Logviewer URL that will be used to view threads in your web browser
+* `LOG_URL` - Logviewer URL that will be used to view threads in your web browser. *Please view the below **Danger** block if you do not intend on using a Logviewer.
* `GUILD_ID` - The ID of the main Discord server that your bot will operate in.
* `MODMAIL_GUILD_ID` - **\[Optional]** The ID of the Discord server that your bot will create ticket channels in. This is only needed if you want your ticket channels to be created in a separate server, for an example, Staff Server.
* `OWNERS` - The user ID of the Discord accounts you want to set as owner for the bot. Can consist of multiple users, separated by comma.
@@ -283,9 +282,20 @@ CONNECTION_URI=mongodb+srv://username:password@cluster0-abcde.mongodb.net/
```
{% endcode %}
+{% hint style="danger" %}
+**DANGER!!** - `LOG_URL` Enviornment Variable without a Logviewer
+
+*This is only relevant if you choose not to use a logviewer with your Modmail Instance, if you intend on having a fully featured instance, you can safely ignore this block.*
+
+If you do not intend on using a Logviewer for your Modmail Instance, you must still ensure `LOG_URL` is set to a valid FQDN (Fully Qualified Domain Name). You can leave it as `example.com` or change it to anything else, but, do **not** delete the row, or set a value that is not an FQDN. `none`, `local`, `12032`, etc are **not** FQDNs.
+
+If you set the `LOG_URL` to an invalid FQDN, Discord will not handle it well and you will experience issues with thread creation.
+{% endhint %}
+
+
## Hosting Modmail
-Your next step is to choose one of our supported hosting method that's available and preferable to you.
+Your next step is to choose one of our supported hosting method that's available and preferable to you.
Click on one of the links below to view further instructions for your preferred hosting method. Each method has their pros and cons, be sure to take them into consideration when choosing your hosting platform to run Modmail.
@@ -297,11 +307,15 @@ A platform as a service (PaaS) that offers relatively low cost plans, which allo
If you have an old PC, a Raspberry Pi, or a Linux box that you're able to keep online 24/7, you can also host Modmail with your own machine at home. Since Modmail doesn't require intensive resources to run, you can get by with a system having as low as 1GB of RAM. Setting it up can be quite advanced but you have complete control over your bot instance. Refer to our local hosting guide supporting a few popular OSes by clicking [here](./#local-hosting-free).
-### [Modmail Patreon](https://www.patreon.com/kyber) (paid)
+### [Modmail Team Hosting](https://buymeacoffee.com/modmaildev) (paid)
We offer paid hosting solution for your Modmail bot. Hosting Modmail with us costs $4-5 USD per month.
-We will also fully manage your bot hosting for you, so you don't need to worry about upgrading or setting up your own host server. Refer to our [Patreon Hosting here](https://www.patreon.com/kyber).
+We will also fully manage your bot hosting for you, so you don't need to worry about upgrading or setting up your own host server. Refer to our [Patreon Hosting here](https://buymeacoffee.com/modmaildev).
+
+### [modmail.lvh.lol](https://modmail.lvh.lol) (paid)
+
+Run by a member of our community, this hosting provider has a purpose built software stack for hosting Modmail, logviewer not included.
### [Heroku](heroku.md) (paid)
@@ -315,16 +329,6 @@ Apart from [Patreon hosting](./#modmail-patreon-paid), hosting on a cloud server
This method is a lot more "involved" than other solutions. If you're not comfortable with configuring remote Linux environments, we recommend you to choose a different option. For this method, you will need to refer to our Local hosting installation guide [here](local-hosting-vps/) and choose your desired OS.
-### [Replit](https://replit.com/\~) (free/paid)
-
-{% hint style="warning" %}
-The Modmail team does not recommend this hosting method due to their highly unstable and heavily abused environment. That said, we still decided to list this option here as a method for users with no access to valid payment cards since most hosting platforms require them for verification.\
-\
-Please note that our Support Team will not be offering any official help or support if you choose this method to host Modmail.
-{% endhint %}
-
-An online code execution environment that costs $7 USD per month. However, hosting on Replit is often unstable, and thus not recommended. However, a community guide is still available by clicking [here](broken-reference).
-
## Community Guides
{% hint style="warning" %}
@@ -336,3 +340,5 @@ If you're not satisfied with the options listed above, some of our community mem
{% content-ref url="community-guides.md" %}
[community-guides.md](community-guides.md)
{% endcontent-ref %}
+
+[^1]: Some free options require a credit card for verification.
\ No newline at end of file
From bcb2baedda558d842e761fbb40754d449448f759 Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 11:31:15 -0400
Subject: [PATCH 06/15] Raspberry Pi Steps add to Debian
---
installation/local-hosting-vps/README.md | 1 +
installation/local-hosting-vps/debian.md | 9 ++++++++-
2 files changed, 9 insertions(+), 1 deletion(-)
diff --git a/installation/local-hosting-vps/README.md b/installation/local-hosting-vps/README.md
index 0ae116b..42d97ce 100644
--- a/installation/local-hosting-vps/README.md
+++ b/installation/local-hosting-vps/README.md
@@ -23,6 +23,7 @@ More OS-specific requirements will be listed on their specific installation page
* [Alma Linux](almalinux.md)
* [CentOS](almalinux.md)
* [Raspberry Pi OS](debian.md)
+ * See the **Raspberry Pi OS Steps** section to ensure a proper installation.
## Logviewer
diff --git a/installation/local-hosting-vps/debian.md b/installation/local-hosting-vps/debian.md
index 9046ff8..41a0099 100644
--- a/installation/local-hosting-vps/debian.md
+++ b/installation/local-hosting-vps/debian.md
@@ -33,6 +33,13 @@ All code blocks should be executed in bash and line by line unless specified oth
To install these dependencies, we will be using **`apt`**.
+### Raspberry Pi OS Steps
+
+{% hint style="info" %}
+By default, [Raspberry Pi OS](https://www.raspberrypi.com/software/operating-systems/) is missing some libraries to use modmail. Please run the following command to be able to use modmail.
+```sudo apt update && sudo apt upgrade -y && sudo apt install libjpeg8-dev```
+{% endhint %}
+
### **Debian 11 Bullseye /** Raspberry Pi OS 11 Bullseye
```bash
@@ -88,7 +95,7 @@ python3.9 -m pipenv install --python 3.9
```
{% hint style="info" %}
-Replace `3.9` with `3.10` on the command above if you followed[ Debian 10 Buster](debian.md#debian-10-buster-raspberry-pi-os-10-buster) method previously.
+Replace `3.9` with `3.10` on the command above if you followed [Debian 10 Buster](debian.md#debian-10-buster-raspberry-pi-os-10-buster) method previously.
{% endhint %}
Create a file named `.env` with `nano` and paste all the environmental variables (secrets) needed to run the bot via right-clicking in the nano editor. Refer to the steps in the [parent Installation page](../#preparing-your-environmental-variables) to find where to obtain these.
From a3f8f0186fe93fcfe88d46958509d0324c24e7d7 Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 11:38:42 -0400
Subject: [PATCH 07/15] Merge incomplete modern Heroku guide with old Heroku
guide to have a single, complete, Heroku guide
---
installation-1.md | 59 -------------------
installation-continued.md | 121 --------------------------------------
installation/heroku.md | 61 +++++++++++++++++--
3 files changed, 55 insertions(+), 186 deletions(-)
delete mode 100644 installation-1.md
delete mode 100644 installation-continued.md
diff --git a/installation-1.md b/installation-1.md
deleted file mode 100644
index f9ab8c2..0000000
--- a/installation-1.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# Installation
-
-**If you need help beyond this tutorial please join our support server and the support team will be happy to help you** [https://discord.gg/cnUpwrnpYb](https://discord.gg/cnUpwrnpYb)
-
-> **Self Hosting Tutorial**: https://taaku18.github.io/modmail/local-hosting/
-
-## What you'll need:
-
-* An internet connection and browser.
-* An email account.
-* A digital or physical notepad (Notepad, Notes, ... literally anything).
-
-## 1. Heroku Account
-
-In this guide, we will be using Heroku to deploy our Modmail bot. Make an account on their [website](https://www.heroku.com/) to get started.
-
-## 2. Discord Bot Account
-
-## 2.1. Create a bot
-
-You will need to create a bot application to interact with the Discord API. Head over to the [applications page](https://discordapp.com/developers/applications/). Log in - if you're not already - and click on `New Application`. Give it a name and click `Confirm` to register your bot.
-
-
-
-A new screen should pop up. Navigate to the `Bot` section and click on `Add Bot`. Click on `Yes, do it!` to confirm.
-
-
-
-## 2.2. Obtain a token
-
-After this, a dashboard for your bot will open. Give your bot a nice profile picture if you want to. It's recommended you switch off the `Public Bot` option. That way, no one except yourself will be able to add this bot to their server. Lastly, copy the token and paste this in your notepad.
-
-**Make sure to keep this token private, since anyone who has it can control (or "hack") your bot and potentially cause malicious damage. If you feel that your token has been leaked, click on `Regenerate` to invalidate the old one and create a new bot token.**
-
-
-
-## 2.3. Enable Privileged Intents
-
-Enable the "Presence Intent", "Server Members" and "Message content" intent within the dashboard.
-
-
-
-## 2.4. Get an invite link
-
-The last thing you need to do in Discord's developer portal is to obtain an invite link for the bot. To do this, head over to the `OAuth2` tab. Scroll down a bit and select the `Bot` section. Scroll a bit further down and you will see a few permissions. Make sure to select `View Audit Log`, `Manage Channels` and `Manage Messages`.
-
-
-
-Before you press "copy", scroll down and select the following permissions:
-
-
-
-## 2.5. Invite the bot
-
-`Copy` the link and paste it in your address bar. A new screen will open: choose your server and select all options. Click on `Authorize` and your bot should be offline in your server.
-
-## 
-
-[**To continue the setup, head over to the second page of this guide.**](https://github.com/modmail-dev/modmail/wiki/Installation-\(cont.\))
diff --git a/installation-continued.md b/installation-continued.md
deleted file mode 100644
index 576999f..0000000
--- a/installation-continued.md
+++ /dev/null
@@ -1,121 +0,0 @@
-# Installation (continued)
-
-## 3. Create a Database
-
-To be able to store data such as logs, you will need to use your own database. A database is required, as the database also stores configuration data for your bot.
-
-Modmail supports MongoDB and you are required to provide a MongoDB connection string to the bot. You can get a free 500MB cluster from [MongoDB Atlas](https://www.mongodb.com/cloud/atlas), which is enough to store around 3 million message logs.
-
-Upon creating an account, you will be greeted with this page. Make sure you select Starter Cluster.
-
-
-
-After this, you will be taken to the below screen:
-
-
-
-Select one of the servers marked with `FREE TIER AVAILABLE` and click on `Create Cluster`. It will only take a couple of minutes to configure everything for you.
-
-Follow the "Getting Started" tutorial on the bottom left.
-
-## 3.1. Create a database user
-
-Go to the `Database Access` section in the `security` tab. Click on `+ Add New User` to create a new user, whereupon a new screen will pop up. Select `Read and write to any database`, so the bot can properly store the data. Choose a username and password, but make sure they both **don't contain any special character** like `!`, `-`, `?`. Copy the password into your notepad.
-
-Finally, click `Add User` to finish the creation.
-
-
-
-## 3.2. Whitelist all IP's
-
-Go to the `Network Access` section in the `security` tab. Click on `+ Add IP Address` to add an IP address, whereupon a new screen will pop up. Click the `Allow Access From Everywhere` button and `0.0.0.0/0` should appear in the `Whitelist Entry`. Otherwise, make sure to put input that manually. Finally, click `Confirm` to confirm your changes.
-
-
-
-## 3.3. Obtain a connection string
-
-The last part is to generate a Mongo URI. Go to the `Clusters` section in the `Atlas` tab. Click on `Connect` on the left side of your Cluster dashboard. This will open up a new screen where you have three options. For our purposes, select the middle option `Connect Your Application`.
-
-
-
-You need to copy the connection string, which can be easily done by clicking the `Copy` button. Remove everything past `` but keeping the `/`. Then replace `` with the password for your user and `` with your database-username, which you set earlier. Paste the URI in your notepad.
-
-The final URI looks similar to this: `mongodb+srv://Username:MyPassword@modmail-kjvn21.mongodb.net/`.
-
-
-
-## 4. How to obtain your `github_token` ( Required for the update command )
-
-Note: This is not required when you are hosting using a vps.
-
-Start off by going to your [Github personal access tokens](https://github.com/settings/tokens) 
-
-Generate a new token
-
-Click on the Generate new token button in the top right of the view. 
-
-Give the token a name, such as: `modmail github_token`. Then check the `repo` scope. 
-
-Click `Generate token` and GitHub will take you back to the list of tokens from before. Copy the code into your clipboard. 
-
-If those steps are done correctly you can use the `?update` command to update your bot to the latest version!
-
-## 5. Deploying the Log Viewer
-
-### **Click the button below to deploy the logviewer to heroku!**
-
-[](https://heroku.com/deploy?template=https://github.com/modmail-dev/logviewer)
-
-**This is not the bot!**
-
-You will need to deploy a separate log viewer application from [this repository](https://github.com/modmail-dev/logviewer). This Heroku application is separate from the bot; it's a simple website that will be used to display your thread logs.
-
-Choose a name for your app and paste your Mongo URI (from your notepad). After you click the `Deploy App` button, it will start creating the website.
-
-After that's done configuring, click the `View` button. It will redirect you to the logviewer home screen. Copy the link in the address bar and paste it in Notepad.
-
-
-
-## 6. Modmail
-
-### **Click the button below to deploy the bot to heroku.**
-
-**This is the second application you will be deploying**
-
-[](https://heroku.com/deploy?template=https://github.com/modmail-dev/modmail)
-
-**6.1.** Choose any name for your app. Note: this name doesn't matter at all.
-
-**6.2.** Put your [bot's token](https://github.com/kyb3rr/modmail/wiki/Installation#creating-a-bot-account) in the `TOKEN` field.
-
-**6.3.** In the `DATABASE_TYPE` You may fillout: `mongodb`
-
-**6.4.** Put the [ID of your Server](https://support.discordapp.com/hc/en-us/articles/206346498-Where-can-I-find-my-User-Server-Message-ID-) into the `GUILD_ID` field.
-
-**6.5.** Put your own ID in the `OWNERS` field. If there are multiple owners, separate them by a comma: `180314310298304512, 355790471219511297, 325012556940836864`.
-
-**6.6.** Put your Mongo connection URI from the previous section in the `CONNECTION_URI` field.
-
-**6.7.** Put the `github token` you just created in the `GITHUB_TOKEN` field.
-
-**6.8.** Put the URL of your log viewer Heroku app (`https://yourlogviewerappname.herokuapp.com`) in the `LOG_URL` field.
-
-**6.9.** Click the `deploy app` button and wait for it to finish.
-
-**6.10.** Click `Manage App` and go into the `Resources` tab, where you need to turn on the worker by clicking the pencil icon next to it.
-
-**6.11.** If you want, you can go over and check the application logs to see if everything is running smoothly. If any unexpected errors pop up, join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. The support members will help you figure out the issue and show you how to fix it.
-
-**6.12.** Once the bot is online in your server, make sure to give it `Manage Channels`, `Manage Messages` and `View Audit Logs` permissions. If your bot is not online, recheck the previous steps above.
-
-**6.13.** Do the `?setup` command and you are good to go!
-
-***
-
-Congratulations! Your bot is ready! Head over to Discord and try it out! If you have any issues or questions, join the [Discord server](https://discord.gg/cnUpwrnpYb).
-
-Make sure to setup permissions using this [handy guide](https://github.com/modmail-dev/modmail/wiki/Permissions)!
-
-[Taki's Blog](https://taaku18.github.io/modmail/customization/) contains many cool customizations for the bot, so you might want to check it out!
-
-If you like the bot, consider giving this repository a star 😉. If you want to support the developers financially, subscribe to the [Patreon](https://www.patreon.com/kyber).
diff --git a/installation/heroku.md b/installation/heroku.md
index 7bc4891..785af5b 100644
--- a/installation/heroku.md
+++ b/installation/heroku.md
@@ -4,24 +4,24 @@ description: Deploy Modmail on Heroku PaaS.
# Heroku
-## What is Heroku?
+### What is Heroku?
Heroku is a container-based cloud Platform as a Service (PaaS). Developers use Heroku to deploy, manage, and scale modern apps.
-## Requirements
+### Requirements
* A credit card (for payment and verification).
* An email account.
* A [GitHub](https://github.com/signup) account.
* You have completed the initial steps: [invited your bot](./#create-a-discord-bot) and [created a MongoDB database](./#create-a-mongodb-database).
-## Costs
+### Costs
Unfortunately, Heroku is no longer free-of-charge. You will need at least their Eco plan, which currently costs $5 USD per month. See their [pricing page](https://www.heroku.com/pricing) for more info and up-to-date prices.
If you are a higher-education student, you *may* be eligible for their [student offer](https://www.heroku.com/github-students), which grants you $13 USD of credits per month for 24 months—enough to host Modmail free for two years.
-## Fork our GitHub repositories
+### Fork our GitHub repositories
You will need to fork our repositories to deploy onto Heroku.
@@ -47,16 +47,65 @@ Next, to keep your Modmail and Logviewer up to date, you will need to install th
-Your GitHub should now be all set. Next step, [create a Heroku account](heroku.md#create-a-heroku-account) to deploy your bot.
+Your GitHub should now be all set. Next step, [create a Heroku account](https://heroku.com) on their website to deploy your bot.
+## Deploying the Log Viewer
+### **Click the button below to deploy the logviewer to Heroku!**
+[](https://heroku.com/deploy?template=https://github.com/modmail-dev/logviewer)
+
+**This is not the bot!**
+
+You will need to deploy a separate log viewer application from [this repository](https://github.com/modmail-dev/logviewer). This Heroku application is separate from the bot; it's a simple website that will be used to display your thread logs.
+
+Choose a name for your app and paste your Mongo URI (from your notepad). After you click the `Deploy App` button, it will start creating the website.
+
+After that's done configuring, click the `View` button. It will redirect you to the logviewer home screen. Copy the link in the address bar and paste it in Notepad.
+
+
+
+## 6. Modmail
+
+### **Click the button below to deploy the bot to heroku.**
+
+**This is the second application you will be deploying - this is the actual bot.**
+
+[](https://heroku.com/deploy?template=https://github.com/modmail-dev/modmail)
+
+**6.1.** Choose any name for your app. Note: this name doesn't matter at all.
+
+**6.2.** Put your bot's token in the `TOKEN` field.
+
+**6.3.** In the `DATABASE_TYPE` You may fillout: `mongodb`
+
+**6.4.** Put the ID of your Server into the `GUILD_ID` field.
+
+**6.5.** Put your own ID in the `OWNERS` field. If there are multiple owners, separate them by a comma.
+
+**6.6.** Put your Mongo connection URI from the previous section in the `CONNECTION_URI` field.
+
+**6.7.** Put the URL of your log viewer Heroku app (`https://yourlogviewerappname.herokuapp.com`) in the `LOG_URL` field.
+
+**6.8** Click the `Deploy App` button and wait for it to finish.
+
+**6.9.** Click `Manage App` and go into the `Resources` tab, where you need to turn on the worker by clicking the pencil icon next to it.
+
+**6.11.** If you want, you can go over and check the application logs to see if everything is running smoothly. If any unexpected errors pop up, join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. Our support team will gladly assist with any issues.
+
+**6.12.** Once the bot is online in your server, make sure to give it the required positions from [Installation](https://docs.modmail.dev/installation).
+
+**6.13.** Run the `?setup` command and you are good to go!
+
+***
+
+Congratulations! Your bot is ready! Head over to Discord and try it out! If you have any issues or questions, join our [Discord Server](https://discord.gg/cnUpwrnpYb).
## Updating
You can update Modmail on your Heroku account whenever changes are made to the repository. If you want to update while hosting locally (not Heroku), simply type `git pull` in your terminal and install the requirements again with `pipenv install`.
-## Forking the repo
+### Forking the repo
Before you get started, you must [fork](https://github.com/modmail-dev/modmail/fork) the repo first if you are using Heroku and want to update the bot.
From f326bdb5d841650bd4479ac0d4f97820405f7be3 Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 11:41:01 -0400
Subject: [PATCH 08/15] Update typo and windows requirements in Windows Guide
---
installation/local-hosting-vps/windows.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/installation/local-hosting-vps/windows.md b/installation/local-hosting-vps/windows.md
index 4965f87..c2383b3 100644
--- a/installation/local-hosting-vps/windows.md
+++ b/installation/local-hosting-vps/windows.md
@@ -6,12 +6,12 @@ description: Deploy Modmail on a Windows machine.
## Prerequisites
-1. Minimum 2GB of RAM\*
+1. Minimum 4GB of RAM\*
2. At least 2GB available disk space.
3. Supported Windows version: Windows 11
{% hint style="info" %}
-Note that while it is possible to run Modmail with even less memory, Windows 10 itself recommend at least 2GB (4GB for Windows 11). This guide assumes the lowest threshold to comfortably run Modmail without possibly running into any resource bottleneck.
+Note that while it is possible to run Modmail with even less memory, Windows 10 itself recommends at least 4GB. This guide assumes the lowest threshold to comfortably run Modmail without possibly running into any resource bottleneck.
{% endhint %}
{% hint style="warning" %}
From e423535f76ff50fe32455f4543524e1523167d02 Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 11:45:43 -0400
Subject: [PATCH 09/15] Organizational Changes and Archived Docs Removal
---
SUMMARY.md | 11 +++-------
getting-started.md | 6 ------
modmail-usage.md | 21 -------------------
.../configure-modmail-and-logviewer.md | 0
.../frequently-asked-questions-old.md | 0
5 files changed, 3 insertions(+), 35 deletions(-)
delete mode 100644 getting-started.md
delete mode 100644 modmail-usage.md
rename configure-modmail-and-logviewer.md => old-docs/configure-modmail-and-logviewer.md (100%)
rename frequently-asked-questions (1).md => old-docs/frequently-asked-questions-old.md (100%)
diff --git a/SUMMARY.md b/SUMMARY.md
index db636c4..e2ebf5d 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -21,7 +21,6 @@
* [Heroku](installation/heroku.md)
* [Community Guides](installation/community-guides.md)
* [Updating](updating.md)
-* [Getting Started](getting-started.md)
* [Usage](usage-guide/README.md)
* [Plugins](usage-guide/plugins.md)
* [Configuration](usage-guide/configuration.md)
@@ -31,10 +30,6 @@
* [Config References]()
* [Configuration Variables](config-references/config-vars.md)
* [Color Names](config-references/color-names.md)
-* [Archives Documentation](old-docs/README.md)
- * [Installation](installation-1.md)
- * [Installation (continued)](installation-continued.md)
- * [Configure Modmail and Logviewer](configure-modmail-and-logviewer.md)
- * [Frequently Asked Questions]()
- * [Modmail Usage](modmail-usage.md)
- * [Updating]()
+* [Archived Documentation](old-docs/README.md)
+ * [Configure Modmail and Logviewer](old-docs/configure-modmail-and-logviewer.md)
+ * [Frequently Asked Questions](old-docs/frequently-asked-questions-old.md)
diff --git a/getting-started.md b/getting-started.md
deleted file mode 100644
index 1f0f48f..0000000
--- a/getting-started.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-description: TODO
----
-
-# Getting Started
-
diff --git a/modmail-usage.md b/modmail-usage.md
deleted file mode 100644
index 072075b..0000000
--- a/modmail-usage.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Modmail Usage
-
-### Basic Usage
-
-Once someone DMs the bot a channel will be created for their thread. You can reply to their thread using the `[p]reply` command. Once you are done communicating you can use the `[p]close` command
-
-### Ease of Use
-
-You can configure aliases and snippets, which is highly recommended. For example, you can shorten the `reply` command to `r` (In case you want to do this you can use the command `[p]alias add r reply`)
-
-You can use snippets to shorten text like "Thanks for Contacting Modmail Support! How can I help you today?" to a simple command such as `[p]hi` (In case you want to do this you can use the command `[p]snippets add hi Thanks for Contacting Modmail Support! How can I help you today?`)
-
-### Advanced Usage
-
-You can use times with the close command for example `[p]close 20m Bye` to close in 20 minutes with the reason "Bye" if you don't want to close on a timer but still add a reason you can use `[p]close Bye` which will close the thread with the reason "Bye"
-
-### Anonymous Snippets
-
-\[p]alias add \[snippetname] anonreply \[snippet text]
-
-_Note: In this page, the meaning of `[p]` is `bot prefix` this defaults to `?` but can be changed with the `[p]prefix` command_
diff --git a/configure-modmail-and-logviewer.md b/old-docs/configure-modmail-and-logviewer.md
similarity index 100%
rename from configure-modmail-and-logviewer.md
rename to old-docs/configure-modmail-and-logviewer.md
diff --git a/frequently-asked-questions (1).md b/old-docs/frequently-asked-questions-old.md
similarity index 100%
rename from frequently-asked-questions (1).md
rename to old-docs/frequently-asked-questions-old.md
From ca83421f894a84fead1335418a5b84719dc35e95 Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 14:49:35 -0400
Subject: [PATCH 10/15] Fix typo
---
choose-host/unrecommended-hosts.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/choose-host/unrecommended-hosts.md b/choose-host/unrecommended-hosts.md
index 2060fb8..96c01f3 100644
--- a/choose-host/unrecommended-hosts.md
+++ b/choose-host/unrecommended-hosts.md
@@ -57,7 +57,7 @@ description: These hosts are hosts we, and members of our community have had lit
- baud.host does not allow users to provide their MongoDB Connection URI, this is not recommended as it locks users into a single host, and limits a user's ownership of their data. We were not able to conduct a test on the security of their locally hosted database, but if managed improperly, it could also be a security concern.
- baud.host uses Stripe for payment verification, however, appears to use their own processing flow, instead of the one provided by Stripe. We were unable to conduct a test on security, but this could be a security concern.
- Kybo Group claims compliance with HIPAA, GDPR, DPDPA, with an ISO27001, PCI DSS, SOC 1 Type 2, and SOC 2 Type 2 certifications, however, attempts to verify this have failed. You can conduct your own certification search with the [IAF](https://www.iafcertsearch.org/search/certified-entities?search=Kybo%20Group).
-- Some users have reported feagures in latest updates not working with this host.
+- Some users have reported features in latest updates not working with this host.
{% hint style="danger" %}
From 719364b0c33fe597f2da3bff31ab2aa04df2252f Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 16:59:12 -0400
Subject: [PATCH 11/15] begin heroku fix
---
installation/heroku.md | 75 +++++++++++++++++++++++++++---------------
1 file changed, 48 insertions(+), 27 deletions(-)
diff --git a/installation/heroku.md b/installation/heroku.md
index 785af5b..e20117c 100644
--- a/installation/heroku.md
+++ b/installation/heroku.md
@@ -21,33 +21,15 @@ Unfortunately, Heroku is no longer free-of-charge. You will need at least their
If you are a higher-education student, you *may* be eligible for their [student offer](https://www.heroku.com/github-students), which grants you $13 USD of credits per month for 24 months—enough to host Modmail free for two years.
-### Fork our GitHub repositories
+{% hint style="info" %}
+The Basic Setup option below uses templates from our repository, while this is a simpler way to setup the bot, it is no longer recommended due to added complexities in the updating process.
-You will need to fork our repositories to deploy onto Heroku.
-
-Make sure you're logged in to [GitHub](https://github.com/). You will need to fork **two** repositories.
-
-First we fork the Modmail repository. Head over to [https://github.com/kyb3rr/modmail/fork](https://github.com/modmail-dev/modmail/fork), leave all the settings as default, and click **Create fork**.
-
-
Create a GitHub fork for the Modmail Repository.
+It is recommended you use the
+{% endhint %}
-Next do the same for the Logviewer repository by heading over to [https://github.com/kyb3r/logviewer/fork](https://github.com/modmail-dev/logviewer/fork), leave all the settings as default, and click **Create fork**.
+{% tabs %}
-
Create a GitHub fork for the Logviewer Repository.
-
-Next, to keep your Modmail and Logviewer up to date, you will need to install the [Pull app](https://github.com/apps/pull). Simply head over to [https://github.com/apps/pull](https://github.com/apps/pull), click **Install**, choose **Only select repositories**, then select **both** the Modmail and Logviewer repositories that you forked in the previous step.
-
-
Select both the Modmail and Logviewer forks, then click Install.
-
-
-
-Your GitHub should now be all set. Next step, [create a Heroku account](https://heroku.com) on their website to deploy your bot.
+{% tab title="Basic Setup (not recommended)" icon="taxi" %}
## Deploying the Log Viewer
@@ -65,7 +47,7 @@ After that's done configuring, click the `View` button. It will redirect you to
-## 6. Modmail
+## Deploying Modmail
### **Click the button below to deploy the bot to heroku.**
@@ -99,11 +81,45 @@ After that's done configuring, click the `View` button. It will redirect you to
***
+ {% endtab %}
+
+{% tab title="Complex Setup (recommended)" icon="shuttle-space" %}
+
+## Fork our GitHub repositories
+
+You will need to fork our repositories to deploy onto Heroku.
+
+Make sure you're logged in to [GitHub](https://github.com/). You will need to fork **two** repositories.
+
+First we fork the Modmail repository. Head over to [https://github.com/kyb3rr/modmail/fork](https://github.com/modmail-dev/modmail/fork), leave all the settings as default, and click **Create fork**.
+
+
Create a GitHub fork for the Modmail Repository.
+
+Next do the same for the Logviewer repository by heading over to [https://github.com/kyb3r/logviewer/fork](https://github.com/modmail-dev/logviewer/fork), leave all the settings as default, and click **Create fork**.
+
+
Create a GitHub fork for the Logviewer Repository.
+
+Next, to keep your Modmail and Logviewer up to date, you will need to install the [Pull app](https://github.com/apps/pull). Simply head over to [https://github.com/apps/pull](https://github.com/apps/pull), click **Install**, choose **Only select repositories**, then select **both** the Modmail and Logviewer repositories that you forked in the previous step.
+
+
Select both the Modmail and Logviewer forks, then click Install.
+
+
+
+Your GitHub should now be all set. Next step, [create a Heroku account](https://heroku.com) on their website to deploy your bot.
+
+
+
Congratulations! Your bot is ready! Head over to Discord and try it out! If you have any issues or questions, join our [Discord Server](https://discord.gg/cnUpwrnpYb).
## Updating
-You can update Modmail on your Heroku account whenever changes are made to the repository. If you want to update while hosting locally (not Heroku), simply type `git pull` in your terminal and install the requirements again with `pipenv install`.
+You can update Modmail on your Heroku account whenever changes are made to the repository.
### Forking the repo
@@ -136,4 +152,9 @@ If the changes from the upstream repository cause conflicts, GitHub will prompt
You then want to go to your modmail application in Heroku, connect your modmail fork via the `Deploy` tab and deploy the `master` branch.
-You can turn on auto-deploy for the master branch if you don't want to go through the process of logging into Heroku and deploying the branch every time changes to the repo are made in the future. However, you will have to make a pull request to update your fork every time.
\ No newline at end of file
+You can turn on auto-deploy for the master branch if you don't want to go through the process of logging into Heroku and deploying the branch every time changes to the repo are made in the future. However, you will have to make a pull request to update your fork every time.
+
+{% endtab %}
+
+{% endtabs %}
+
From ac9b3ef345ceb52ca200ec33dce94c8d5b3a1113 Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 17:09:38 -0400
Subject: [PATCH 12/15] heroku 2 -- seeing formatting
---
installation/heroku.md | 70 +++++++++++++++++++++++++-----------------
1 file changed, 42 insertions(+), 28 deletions(-)
diff --git a/installation/heroku.md b/installation/heroku.md
index e20117c..6f2269d 100644
--- a/installation/heroku.md
+++ b/installation/heroku.md
@@ -91,15 +91,15 @@ You will need to fork our repositories to deploy onto Heroku.
Make sure you're logged in to [GitHub](https://github.com/). You will need to fork **two** repositories.
-First we fork the Modmail repository. Head over to [https://github.com/kyb3rr/modmail/fork](https://github.com/modmail-dev/modmail/fork), leave all the settings as default, and click **Create fork**.
+First we fork the Modmail repository. Head over to [https://github.com/modmail-dev/modmail/fork](https://github.com/modmail-dev/modmail/fork), leave all the settings as default, and click **Create fork**.
Create a GitHub fork for the Modmail Repository.
-Next do the same for the Logviewer repository by heading over to [https://github.com/kyb3r/logviewer/fork](https://github.com/modmail-dev/logviewer/fork), leave all the settings as default, and click **Create fork**.
+Next do the same for the Logviewer repository by heading over to [https://github.com/modmail-dev/logviewer/fork](https://github.com/modmail-dev/logviewer/fork), leave all the settings as default, and click **Create fork**.
Create a GitHub fork for the Logviewer Repository.
-Next, to keep your Modmail and Logviewer up to date, you will need to install the [Pull app](https://github.com/apps/pull). Simply head over to [https://github.com/apps/pull](https://github.com/apps/pull), click **Install**, choose **Only select repositories**, then select **both** the Modmail and Logviewer repositories that you forked in the previous step.
+Next, to keep your Modmail and Logviewer up to date, you will need to install the [Pull App](https://github.com/apps/pull). Simply head over to [https://github.com/apps/pull](https://github.com/apps/pull), click **Install**, choose **Only select repositories**, then select **both** the Modmail and Logviewer repositories that you forked in the previous step.
@@ -113,48 +113,62 @@ Next, to keep your Modmail and Logviewer up to date, you will need to install th
Your GitHub should now be all set. Next step, [create a Heroku account](https://heroku.com) on their website to deploy your bot.
+## Deploying the Log Viewer
+Go to this link: ``https://heroku.com/deploy?template=https://github.com/[YOUR GITHUB USERNAME HERE!!!]/logviewer``
+*Fill in your Github username `[YOUR GITHUB USERNAME HERE!!!]` before pressing enter!*
-Congratulations! Your bot is ready! Head over to Discord and try it out! If you have any issues or questions, join our [Discord Server](https://discord.gg/cnUpwrnpYb).
+**This is not the bot!**
-## Updating
+Choose a name for your app and paste your Mongo URI in the field (from your notepad). After you click the `Deploy App` button, it will start creating the website.
-You can update Modmail on your Heroku account whenever changes are made to the repository.
+After that's done configuring, click the `View` button. It will redirect you to the logviewer home screen. Copy the link in the address bar and paste it in Notepad.
-### Forking the repo
+
-Before you get started, you must [fork](https://github.com/modmail-dev/modmail/fork) the repo first if you are using Heroku and want to update the bot.
+## Deploying Modmail
+
+**This is the second application you will be deploying - this is the actual bot.**
-### Syncing a fork branch from the web UI
+Go to this link: ``https://heroku.com/deploy?template=https://github.com/[YOUR GITHUB USERNAME HERE!!!]/modmail``
+*Fill in your Github username `[YOUR GITHUB USERNAME HERE!!!]` before pressing enter!*
-1. On GitHub, navigate to the main page of the forked repository that you want to sync with the upstream repository.
-2. Select the Sync fork dropdown.
+**01.** Choose any name for your app. Note: this name doesn't matter at all.
- 
-3. Then click Update branch.
+**02.** Put your bot's token in the `TOKEN` field.
- 
+**03.** In the `DATABASE_TYPE` You may fillout: `mongodb`
-If the changes from the upstream repository cause conflicts, GitHub will prompt you to create a pull request to resolve the conflicts.
+**04.** Put the ID of your Server into the `GUILD_ID` field.
-### I want to enable automatic updates
+**05.** Put your own ID in the `OWNERS` field. If there are multiple owners, separate them by a comma.
-1. Create a GitHub account
-2. [Fork](https://github.com/modmail-dev/modmail/fork) the repository
-3. Add GITHUB\_TOKEN into your configuration variables from https://github.com/settings/tokens with the repo scope ([Guide](https://github.com/modmail-dev/modmail/wiki/Installation-\(cont.\)#4-how-to-obtain-your-github\_token---required-for-the-update-command-)).
-4. Link your GitHub account to heroku 
-5. Turn on automatic deploys 
-6. Restart the bot
+**06.** Put your Mongo connection URI from the previous section in the `CONNECTION_URI` field.
-### I want to update the bot once
+**07.** Put the URL of your log viewer Heroku app (`https://yourlogviewerappname.herokuapp.com`) in the `LOG_URL` field.
-[Click here to create a new pull request to your fork](https://github.com/modmail-dev/modmail/pull/new/master). Select `compare across forks`, make the base repository `yourusername/modmail` and ensure the branch is set to master. Put any title you want and create the pull request. On the page that comes after this, merge the pull request.
+**08** Click the `Deploy App` button and wait for it to finish.
-You then want to go to your modmail application in Heroku, connect your modmail fork via the `Deploy` tab and deploy the `master` branch.
+**09.** Click `Manage App` and go into the `Resources` tab, where you need to turn on the worker by clicking the pencil icon next to it.
-You can turn on auto-deploy for the master branch if you don't want to go through the process of logging into Heroku and deploying the branch every time changes to the repo are made in the future. However, you will have to make a pull request to update your fork every time.
+**10.** If you want, you can go over and check the application logs to see if everything is running smoothly. If any unexpected errors pop up, join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. Our support team will gladly assist with any issues.
-{% endtab %}
+**11.** Once the bot is online in your server, make sure to give it the required positions from [Installation](https://docs.modmail.dev/installation).
-{% endtabs %}
+**12.** Run the `?setup` command and you are good to go!
+
+## Updating
+
+You can update Modmail on your Heroku account whenever changes are made to the repository. Link your GitHub Account to Heroku:
+
+
+
+**One Time Update:** You then want to go to your modmail application in Heroku, connect your modmail fork via the `Deploy` tab and deploy the `master` branch.
+
+**Automatic Updates:** You can turn on auto-deploy for the master branch if you don't want to go through the process of logging into Heroku and deploying the branch every time changes to the repo are made in the future.
+
+
+
+{% endtab %}
+{% endtabs %}
\ No newline at end of file
From df990e3bec1f3834a1d78b8677949ee4d6ebfb3a Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 17:15:53 -0400
Subject: [PATCH 13/15] heroku3
---
installation/heroku.md | 15 ++++++++++++---
1 file changed, 12 insertions(+), 3 deletions(-)
diff --git a/installation/heroku.md b/installation/heroku.md
index 6f2269d..d0e4e8b 100644
--- a/installation/heroku.md
+++ b/installation/heroku.md
@@ -85,6 +85,8 @@ After that's done configuring, click the `View` button. It will redirect you to
{% tab title="Complex Setup (recommended)" icon="shuttle-space" %}
+{% stepper %}
+{% step %}
## Fork our GitHub repositories
You will need to fork our repositories to deploy onto Heroku.
@@ -112,10 +114,12 @@ Next, to keep your Modmail and Logviewer up to date, you will need to install th
Your GitHub should now be all set. Next step, [create a Heroku account](https://heroku.com) on their website to deploy your bot.
-
+{% endstep %}
+{% step %}
## Deploying the Log Viewer
Go to this link: ``https://heroku.com/deploy?template=https://github.com/[YOUR GITHUB USERNAME HERE!!!]/logviewer``
+
*Fill in your Github username `[YOUR GITHUB USERNAME HERE!!!]` before pressing enter!*
**This is not the bot!**
@@ -125,12 +129,14 @@ Choose a name for your app and paste your Mongo URI in the field (from your note
After that's done configuring, click the `View` button. It will redirect you to the logviewer home screen. Copy the link in the address bar and paste it in Notepad.
-
+{% endstep %}
+{% step %}
## Deploying Modmail
**This is the second application you will be deploying - this is the actual bot.**
Go to this link: ``https://heroku.com/deploy?template=https://github.com/[YOUR GITHUB USERNAME HERE!!!]/modmail``
+
*Fill in your Github username `[YOUR GITHUB USERNAME HERE!!!]` before pressing enter!*
**01.** Choose any name for your app. Note: this name doesn't matter at all.
@@ -156,7 +162,8 @@ Go to this link: ``https://heroku.com/deploy?template=https://github.com/[YOUR G
**11.** Once the bot is online in your server, make sure to give it the required positions from [Installation](https://docs.modmail.dev/installation).
**12.** Run the `?setup` command and you are good to go!
-
+{% endstep %}
+{% step %}
## Updating
You can update Modmail on your Heroku account whenever changes are made to the repository. Link your GitHub Account to Heroku:
@@ -169,6 +176,8 @@ You can update Modmail on your Heroku account whenever changes are made to the r
+{% endstep %}
+{% endstepper %}
{% endtab %}
{% endtabs %}
\ No newline at end of file
From 437a50401e56dd19efcc7bc52683bf853558aef7 Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 17:27:43 -0400
Subject: [PATCH 14/15] heroku formatting basic setup
---
installation/heroku.md | 31 ++++++++++++++++++-------------
1 file changed, 18 insertions(+), 13 deletions(-)
diff --git a/installation/heroku.md b/installation/heroku.md
index d0e4e8b..ba9f381 100644
--- a/installation/heroku.md
+++ b/installation/heroku.md
@@ -30,7 +30,8 @@ It is recommended you use the
{% tabs %}
{% tab title="Basic Setup (not recommended)" icon="taxi" %}
-
+{% stepper %}
+{% step %}
## Deploying the Log Viewer
### **Click the button below to deploy the logviewer to Heroku!**
@@ -47,6 +48,8 @@ After that's done configuring, click the `View` button. It will redirect you to
+{% endstep %}
+{% step %}
## Deploying Modmail
### **Click the button below to deploy the bot to heroku.**
@@ -55,31 +58,33 @@ After that's done configuring, click the `View` button. It will redirect you to
[](https://heroku.com/deploy?template=https://github.com/modmail-dev/modmail)
-**6.1.** Choose any name for your app. Note: this name doesn't matter at all.
+**1.** Choose any name for your app. Note: this name doesn't matter at all.
-**6.2.** Put your bot's token in the `TOKEN` field.
+**2.** Put your bot's token in the `TOKEN` field.
-**6.3.** In the `DATABASE_TYPE` You may fillout: `mongodb`
+**3.** In the `DATABASE_TYPE` You may fillout: `mongodb`
-**6.4.** Put the ID of your Server into the `GUILD_ID` field.
+**4.** Put the ID of your Server into the `GUILD_ID` field.
-**6.5.** Put your own ID in the `OWNERS` field. If there are multiple owners, separate them by a comma.
+**5.** Put your own ID in the `OWNERS` field. If there are multiple owners, separate them by a comma.
-**6.6.** Put your Mongo connection URI from the previous section in the `CONNECTION_URI` field.
+**6.** Put your Mongo connection URI from the previous section in the `CONNECTION_URI` field.
-**6.7.** Put the URL of your log viewer Heroku app (`https://yourlogviewerappname.herokuapp.com`) in the `LOG_URL` field.
+**7.** Put the URL of your log viewer Heroku app (`https://yourlogviewerappname.herokuapp.com`) in the `LOG_URL` field.
-**6.8** Click the `Deploy App` button and wait for it to finish.
+**8** Click the `Deploy App` button and wait for it to finish.
-**6.9.** Click `Manage App` and go into the `Resources` tab, where you need to turn on the worker by clicking the pencil icon next to it.
+**9.** Click `Manage App` and go into the `Resources` tab, where you need to turn on the worker by clicking the pencil icon next to it.
-**6.11.** If you want, you can go over and check the application logs to see if everything is running smoothly. If any unexpected errors pop up, join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. Our support team will gladly assist with any issues.
+**10.** If you want, you can go over and check the application logs to see if everything is running smoothly. If any unexpected errors pop up, join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. Our support team will gladly assist with any issues.
-**6.12.** Once the bot is online in your server, make sure to give it the required positions from [Installation](https://docs.modmail.dev/installation).
+**11.** Once the bot is online in your server, make sure to give it the required positions from [Installation](https://docs.modmail.dev/installation).
-**6.13.** Run the `?setup` command and you are good to go!
+**12.** Run the `?setup` command and you are good to go!
***
+{% endstep %}
+{% endstepper %}
{% endtab %}
From 144e80bb963667e7f6b845a7e7d445acf28f60eb Mon Sep 17 00:00:00 2001
From: Stephen <48072084+StephenDaDev@users.noreply.github.com>
Date: Mon, 1 Jun 2026 17:41:19 -0400
Subject: [PATCH 15/15] flip order and typo
---
installation/heroku.md | 120 ++++++++++++++++++++---------------------
1 file changed, 60 insertions(+), 60 deletions(-)
diff --git a/installation/heroku.md b/installation/heroku.md
index ba9f381..a29e44d 100644
--- a/installation/heroku.md
+++ b/installation/heroku.md
@@ -24,70 +24,11 @@ If you are a higher-education student, you *may* be eligible for their [student
{% hint style="info" %}
The Basic Setup option below uses templates from our repository, while this is a simpler way to setup the bot, it is no longer recommended due to added complexities in the updating process.
-It is recommended you use the
+It is recommended you use the complex setup, which allows for seamless autoupdate of your Modmail instance.
{% endhint %}
{% tabs %}
-{% tab title="Basic Setup (not recommended)" icon="taxi" %}
-{% stepper %}
-{% step %}
-## Deploying the Log Viewer
-
-### **Click the button below to deploy the logviewer to Heroku!**
-
-[](https://heroku.com/deploy?template=https://github.com/modmail-dev/logviewer)
-
-**This is not the bot!**
-
-You will need to deploy a separate log viewer application from [this repository](https://github.com/modmail-dev/logviewer). This Heroku application is separate from the bot; it's a simple website that will be used to display your thread logs.
-
-Choose a name for your app and paste your Mongo URI (from your notepad). After you click the `Deploy App` button, it will start creating the website.
-
-After that's done configuring, click the `View` button. It will redirect you to the logviewer home screen. Copy the link in the address bar and paste it in Notepad.
-
-
-
-{% endstep %}
-{% step %}
-## Deploying Modmail
-
-### **Click the button below to deploy the bot to heroku.**
-
-**This is the second application you will be deploying - this is the actual bot.**
-
-[](https://heroku.com/deploy?template=https://github.com/modmail-dev/modmail)
-
-**1.** Choose any name for your app. Note: this name doesn't matter at all.
-
-**2.** Put your bot's token in the `TOKEN` field.
-
-**3.** In the `DATABASE_TYPE` You may fillout: `mongodb`
-
-**4.** Put the ID of your Server into the `GUILD_ID` field.
-
-**5.** Put your own ID in the `OWNERS` field. If there are multiple owners, separate them by a comma.
-
-**6.** Put your Mongo connection URI from the previous section in the `CONNECTION_URI` field.
-
-**7.** Put the URL of your log viewer Heroku app (`https://yourlogviewerappname.herokuapp.com`) in the `LOG_URL` field.
-
-**8** Click the `Deploy App` button and wait for it to finish.
-
-**9.** Click `Manage App` and go into the `Resources` tab, where you need to turn on the worker by clicking the pencil icon next to it.
-
-**10.** If you want, you can go over and check the application logs to see if everything is running smoothly. If any unexpected errors pop up, join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. Our support team will gladly assist with any issues.
-
-**11.** Once the bot is online in your server, make sure to give it the required positions from [Installation](https://docs.modmail.dev/installation).
-
-**12.** Run the `?setup` command and you are good to go!
-
-***
-{% endstep %}
-{% endstepper %}
-
- {% endtab %}
-
{% tab title="Complex Setup (recommended)" icon="shuttle-space" %}
{% stepper %}
@@ -185,4 +126,63 @@ You can update Modmail on your Heroku account whenever changes are made to the r
{% endstepper %}
{% endtab %}
+{% tab title="Basic Setup (not recommended)" icon="taxi" %}
+{% stepper %}
+{% step %}
+## Deploying the Log Viewer
+
+### **Click the button below to deploy the logviewer to Heroku!**
+
+[](https://heroku.com/deploy?template=https://github.com/modmail-dev/logviewer)
+
+**This is not the bot!**
+
+You will need to deploy a separate log viewer application from [this repository](https://github.com/modmail-dev/logviewer). This Heroku application is separate from the bot; it's a simple website that will be used to display your thread logs.
+
+Choose a name for your app and paste your Mongo URI (from your notepad). After you click the `Deploy App` button, it will start creating the website.
+
+After that's done configuring, click the `View` button. It will redirect you to the logviewer home screen. Copy the link in the address bar and paste it in Notepad.
+
+
+
+{% endstep %}
+{% step %}
+## Deploying Modmail
+
+### **Click the button below to deploy the bot to heroku.**
+
+**This is the second application you will be deploying - this is the actual bot.**
+
+[](https://heroku.com/deploy?template=https://github.com/modmail-dev/modmail)
+
+**1.** Choose any name for your app. Note: this name doesn't matter at all.
+
+**2.** Put your bot's token in the `TOKEN` field.
+
+**3.** In the `DATABASE_TYPE` You may fillout: `mongodb`
+
+**4.** Put the ID of your Server into the `GUILD_ID` field.
+
+**5.** Put your own ID in the `OWNERS` field. If there are multiple owners, separate them by a comma.
+
+**6.** Put your Mongo connection URI from the previous section in the `CONNECTION_URI` field.
+
+**7.** Put the URL of your log viewer Heroku app (`https://yourlogviewerappname.herokuapp.com`) in the `LOG_URL` field.
+
+**8** Click the `Deploy App` button and wait for it to finish.
+
+**9.** Click `Manage App` and go into the `Resources` tab, where you need to turn on the worker by clicking the pencil icon next to it.
+
+**10.** If you want, you can go over and check the application logs to see if everything is running smoothly. If any unexpected errors pop up, join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. Our support team will gladly assist with any issues.
+
+**11.** Once the bot is online in your server, make sure to give it the required positions from [Installation](https://docs.modmail.dev/installation).
+
+**12.** Run the `?setup` command and you are good to go!
+
+***
+{% endstep %}
+{% endstepper %}
+
+ {% endtab %}
+
{% endtabs %}
\ No newline at end of file
