diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json index 164927dda4..f0b88fc82c 100644 --- a/docs/pages/_meta.json +++ b/docs/pages/_meta.json @@ -1,15 +1,19 @@ { "index": "Introduction", - "another": "Another Page", - "advanced": "Advanced (A Folder)", "about": { "title": "About", "type": "page" }, + "installation": "Installing Modmail", + "logviewer-installation": "Installing Logviewer", + "configuration": "Configuring Modmail", + "updating": "Updating Modmail", + "updating-logviewer": "Updating Logviewer", + "setting-up-auto-restart": "Set Up Auto-restart", "contact": { "title": "Contact ↗", "type": "page", - "href": "https://twitter.com/shuding_", + "href": "https://dsc.gg/transience", "newWindow": true } } diff --git a/docs/pages/advanced.mdx b/docs/pages/advanced.mdx deleted file mode 100644 index a1a5148edc..0000000000 --- a/docs/pages/advanced.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Advanced - -This is the index page for the Advanced folder! diff --git a/docs/pages/advanced/satori.mdx b/docs/pages/advanced/satori.mdx deleted file mode 100644 index 46eb19fd79..0000000000 --- a/docs/pages/advanced/satori.mdx +++ /dev/null @@ -1,3 +0,0 @@ -# Satori - -Satori (悟り) is a Japanese Buddhist term for awakening, "comprehension; understanding". diff --git a/docs/pages/another.mdx b/docs/pages/another.mdx deleted file mode 100644 index 7fb6a0231a..0000000000 --- a/docs/pages/another.mdx +++ /dev/null @@ -1,31 +0,0 @@ -# Another Page - -```js filename="demo.js" {3} copy -let a = 1; - -console.log(a); -``` - -## Component - -import { useState } from 'react' - -{/* Import CSS modules */} -import styles from '../components/counters.module.css' - -export const Counter = () => { - const [count, setCount] = useState(0); - return ( -
- -
- ); -}; - - - -## External Component - -import Counters from '../components/counters' - - diff --git a/docs/pages/assets/bot-id.png b/docs/pages/assets/bot-id.png new file mode 100644 index 0000000000..90b0497b7c Binary files /dev/null and b/docs/pages/assets/bot-id.png differ diff --git a/docs/pages/assets/create-bot.png b/docs/pages/assets/create-bot.png new file mode 100644 index 0000000000..a07279f741 Binary files /dev/null and b/docs/pages/assets/create-bot.png differ diff --git a/docs/pages/assets/docker-illust.png b/docs/pages/assets/docker-illust.png new file mode 100644 index 0000000000..53730352cf Binary files /dev/null and b/docs/pages/assets/docker-illust.png differ diff --git a/docs/pages/assets/docker-image-ls.png b/docs/pages/assets/docker-image-ls.png new file mode 100644 index 0000000000..7c81374005 Binary files /dev/null and b/docs/pages/assets/docker-image-ls.png differ diff --git a/docs/pages/assets/invite-bot.png b/docs/pages/assets/invite-bot.png new file mode 100644 index 0000000000..c08b8e9743 Binary files /dev/null and b/docs/pages/assets/invite-bot.png differ diff --git a/docs/pages/assets/mongo-connect.png b/docs/pages/assets/mongo-connect.png new file mode 100644 index 0000000000..080bc34077 Binary files /dev/null and b/docs/pages/assets/mongo-connect.png differ diff --git a/docs/pages/assets/mongo-ip.png b/docs/pages/assets/mongo-ip.png new file mode 100644 index 0000000000..fa88f56c4e Binary files /dev/null and b/docs/pages/assets/mongo-ip.png differ diff --git a/docs/pages/assets/mongo-password.png b/docs/pages/assets/mongo-password.png new file mode 100644 index 0000000000..41a1e493ac Binary files /dev/null and b/docs/pages/assets/mongo-password.png differ diff --git a/docs/pages/assets/mongo-shared.png b/docs/pages/assets/mongo-shared.png new file mode 100644 index 0000000000..c1482dcc24 Binary files /dev/null and b/docs/pages/assets/mongo-shared.png differ diff --git a/docs/pages/assets/reset-token.png b/docs/pages/assets/reset-token.png new file mode 100644 index 0000000000..8013be2f29 Binary files /dev/null and b/docs/pages/assets/reset-token.png differ diff --git a/docs/pages/assets/toggle-intents.png b/docs/pages/assets/toggle-intents.png new file mode 100644 index 0000000000..f13cf4ae62 Binary files /dev/null and b/docs/pages/assets/toggle-intents.png differ diff --git a/docs/pages/assets/vps-env.png b/docs/pages/assets/vps-env.png new file mode 100644 index 0000000000..cb0a966873 Binary files /dev/null and b/docs/pages/assets/vps-env.png differ diff --git a/docs/pages/community-guides.mdx b/docs/pages/community-guides.mdx new file mode 100644 index 0000000000..48bda321b4 --- /dev/null +++ b/docs/pages/community-guides.mdx @@ -0,0 +1,15 @@ +import { Callout } from 'nextra-theme-docs' + +# Community Guides + + + Community guides are not verified by the Modmail team, so use them at your own risks. + + +## [Replit Guide](https://gist.github.com/anondev-sudo/24978429b85b44348bcff5c0885afe82) by AnonDev + +An online code execution environment. You can host Modmail there for free using certain exploits. The legitimate method costs $7 USD per month. However, regardless if you pay or host for free, hosting on Replit are often unstable and thus not recommended. But for now, this is the only option for those without a payment method for hosting or verification. + +## [Northflank](https://blog.project-mei.xyz/2023/04/11/hosting-discord-modmail-on-northflank/) Guide by raidensakura + +Northflank is a Platform as a Service (PaaS) like Railway that offers abilities to run micro-services like bots, schedule jobs that run periodically and databases with a powerful UI, API and CLI. Their panel is a bit more advanced as compared to Railway but comes with the perk of more customization and features. You will need a valid payment method to verify your account, but will unlock a free tier project that's separated from paid resources. They will not charge your card if you go over resource usage as you have limited allocation per service. diff --git a/docs/pages/configuration.mdx b/docs/pages/configuration.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/pages/frequently-asked-questions.md b/docs/pages/frequently-asked-questions.md new file mode 100644 index 0000000000..a832ca8b11 --- /dev/null +++ b/docs/pages/frequently-asked-questions.md @@ -0,0 +1,27 @@ +--- +description: A list of commonly asked questions or problems related to Modmail. +--- + +# Frequently Asked Questions + +### I tried installing the dependencies with another Python version and it messed up my Pipfile! How can I get the original Pipfile back? + +First remove the broken `Pipfile` and `Pipfile.lock` with: + +```bash +rm Pipfile && rm Pipfile.lock +``` + +Fetch in the changes from the remote repository: + +```bash +git fetch origin +``` + +And then, fetch the original files with: + +```bash +git checkout FETCH_HEAD -- Pipfile && git checkout FETCH_HEAD -- Pipfile.lock +``` + +### diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index 016372b013..9d438d595a 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -1,3 +1,5 @@ +import Image from 'next/image' + # Introduction Modmail is a self-hosted Discord bot for your server. It works similar to [Reddit](https://reddit.zendesk.com/hc/en-us/articles/210896606-What-is-Modmail-)'s Modmail—both in functionality and purpose. It serves as a shared inbox for server staff to communicate with their users in a seamless way. @@ -8,7 +10,7 @@ This bot is free for everyone and always will be. If you like this project and w When a member sends a direct message to Modmail, the bot will create a channel (we call it a "thread") into a designated category. All further DM messages will automatically relay to that channel, then any available staff can respond within the channel. Compared to ticketing bots, Modmail allows easier and more organised discussions among staff. -![](https://i.imgur.com/fru5Q07.png) +Hello Our Logviewer will save the threads so your staff can view previous threads through their corresponding log link. Here is an [example](https://publicmodmail.logs.vodka/logs/example). diff --git a/docs/pages/installation.mdx b/docs/pages/installation.mdx new file mode 100644 index 0000000000..26678cd874 --- /dev/null +++ b/docs/pages/installation.mdx @@ -0,0 +1,285 @@ +--- +title: Installing Modmail +--- + +import { Callout } from 'nextra-theme-docs' +import Image from 'next/image' +import { Steps } from 'nextra-theme-docs' +import { Card, Cards } from 'nextra-theme-docs' +import Link from 'next/link' + +# Installation + +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 with free and paid options. +Keep in mind, some free options will still require a payment method for verification. + +## Basic requirements + +- **A Discord account** +You will need to create a Discord bot under your account. +- **A MongoDB database instance** +Modmail will store its internal data to this database. +- **A hosting server** +To keep Modmail running 24/7 in your server. +- **Note Editing Program (Notepad for desktop, VSCode, etc.)** +Anywhere you can copy and paste to temporary store some texts while we set up the bot. + + + There are two components for Modmail: the bot component and the Logviewer component. You will need both to take full advantage of Modmail. + + + + +### Create a Discord bot + +The first step in setting up Modmail is to create a Discord bot. +Head over to the Discord Developer Portal and create a new application. + +Once you've created a new application, head over to the Bot tab and create a new bot. +![](./assets/create-bot.png) +Navigate to the Bot tab on the sidebar. On this page, you can also edit the About Me section of your bot. + +Click Add bot to create the bot. After adding a bot, reset the token and copy and store the newly generated token in your Text editor for later use. +![](./assets/reset-token.png) + + Make sure to keep this token private! Anyone who has this token can control your bot and potentially cause malicious damage. + + +Next, we need to change some bot settings. Toggle off public bot, then toggle on both server members intent and message content intent. +Remember to click on Save Changes. +![](./assets/reset-token.png) +
+Why do I need to do this? +Disabling _public bot_ prevents other users from inviting your bot. Your bot may not behave appropriately if it's present in other servers. + +Enabling _server members intent_ allows Modmail to view your server's members list and efficiently populate the bot's internal cache. + +Enabling _message content intent_ allows bot commands to function since Modmail doesn't use slash commands. + +What about _presence intent_? It is not needed for Modmail, but it may be required for specialized plugins. +We recommend keeping this toggled off to save computational resources. +
+ +### Invite the bot + +Navigate back to the General Information tab and copy the application ID. +Click Copy to copy the application ID. This is also known as your "Bot ID". +![](./assets/bot-id.png) + +Using the following URL as template, replace `YOUR-ID-HERE` with the ID you just copied. Do not change anything else! Open a new browser tab and go to that URL. +``` +https://discord.com/oauth2/authorize?scope=bot&permissions=416075476184&client_id=YOUR-ID-HERE +``` + +Discord should prompt you to choose a server to invite your bot, followed by a list of permissions. Scroll to the bottom and click Authorize. +Choose your server to invite, then click Continue. +![](./assets/invite-bot.png) + +Scroll to the bottom and click Authorize. Don't un-check any permissions. Only Administrator is optional. + + 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. + + +
+Do you have a separate staff server? +If you manage a large server where you have a separate server for communication among your moderation team, +Modmail supports directing threads into the staff server instead of your main (public) server. + +You will need to invite your Modmail bot to **both** your main (public) server and your staff server using the same invite link above. +
+ +Your bot should now be **offline** in your server. Congratulations, that's as expected! You have successfully created a Discord bot. +The next step is to [create a MongoDB database](./#create-a-mongodb-database). + +### Create a MongoDB database + +Modmail uses MongoDB to store its internal configurations and log histories. You must create a MongoDB database in order to use Modmail. + +We will be using [MongoDB Atlas](https://www.mongodb.com/atlas), which provides us with a free 512MB storage share—more than enough for Modmail. + +Head over to [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) and register for a free account: + +Once you've registered and confirmed your email, you will be greeted by the MongoDB welcome introduction, +asking you to "tell us a few things about yourself and your project". You can answer these questions honestly or however you like. + +In the next step for "deploy a cloud database", choose the **Shared** option. Choose the region that's closest to where you're hosting your bot. +Make sure the **Cluster Tier** is set to **M0 Sandbox** and the price shows as **FREE**. + +![](./assets/mongo-shared.png) +Choose the free **Shared** option and click **Create**. + +On the following **Security Quickstart** page, do the following: + +1. Authentication method: _Username and Password_ + ```Username: `modmail` + Password: Click **Autogenerate Secure Password** - don't type your own password!``` + ![](./assets/mongo-password.png) +2. Copy and **save the password** into your text editor, you will need this for later. + From now on, we will be referring to these credentials as the _database username_ and _database password_. +3. Click **Create User**. +4. Scroll down, we will be connecting from: _My Local Environment_ +5. Set IP address as **`0.0.0.0/0`** and anything for the description. + ![](./assets/mongo-ip.png) + **You must** set the IP address exactly to this, unless you know what you're doing. + **Do not** set it to anything else or click add my current IP address. This allows Modmail to connect to your database. +6. Click **Add Entry**. + +Next, we will need to generate a MongoDB connection string. Simply click `Connect` on the main dashboard, +choose `Connect your application`, then copy the connection string (the default driver is fine) and paste it into your Notepad. + +![](./assets/mongo-connect.png) + +If you followed all the steps so far, your Notepad should contain three lines: +the bot token, the database password, and the MongoDB connection string. For example: + +```md filename="Notepad" +My bot token: MTA3Djv3IAxNjk1NDgdKD231.G1AoUjD.5z629aKP34JKHn4v1EsdNUwdDO3MvBR9ifVES4 +My database password: elAO7wF1r07pNG6u +My MongoDB connection string: mongodb+srv://modmail:@cluster0.example.mongodb.net/ +``` + +Finally, you will need to combine the database password with the MongoDB connection string by **replacing** +the `` (including the `<>`) with the database password. + +You also need to **remove** everything after `.mongodb.net` at the end of the MongoDB connection string. + +This is what your Notepad should look like at the end of this step: + +```md filename="Notepad" +My bot token: MTA3Djv3IAxNjk1NDgdKD231.G1AoUjD.5z629aKP34JKHn4v1EsdNUwdDO3MvBR9ifVES4 +My MongoDB connection string: mongodb+srv://modmail:elAO7wF1r07pNG6u@cluster0.example.mongodb.net +``` + +### Preparing your Environmental Variables + +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 +* `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. +* `CONNECTION_URI` - The URI the bot will use to connect to your MongoDB instance. + +Your finished variables should look something like this: + +```env filename=".env" +TOKEN=OTY3Nzy5MzU5NjAzMzU2NzE4.GtKp_5.JOTYRwGW-LB1He5widCu73vXtmi90KxsqkmoOg +LOG_URL=https://logs.mymodmailbot.com/ +GUILD_ID=1079074933008781362 +OWNERS=188363246695219201,231595246213922828 +MONGO_URI=mongodb+srv://username:password@cluster0-abcde.mongodb.net/ +``` + +### Hosting Modmail + +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. + +#### [Railway](railway.md) (free/paid) +A platform as a service (PaaS) that offers a generous free plan, which allows you to host Modmail for free without any downtime. A credit card is required for verification purposes. Their UI is very simple and easy for beginners to quickly deploy and run your Modmail bot on. You can learn more about their Free Tier plan and pricing by clicking [here](https://railway.app/pricing). + +#### [Northflank](https://northflank.com/) (free/paid) + +A PaaS like Railway but with more advanced UI and more features. Does require credit card for verification but has a dedicated free tier that has no hourly limit. Learn more about their free tier and pricing by clicking [here](https://northflank.com/pricing). + +#### [Local Hosting](local-hosting-vps/) (free) + +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) + +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). + +#### [Heroku](heroku.md) (paid) + +Another popular PaaS that's used to be free. However, their recent pricing adjustments, it now costs $5-7 USD per month to host Modmail. + +If you are currently a higher-education student, you may be eligible for the first year free with their [student offer](https://www.heroku.com/github-students). Refer to our Heroku installation guide by clicking [here](heroku.md). + +#### [Cloud Server / VPS](local-hosting-vps/) (paid) + +Apart from [Patreon hosting](./#modmail-patreon-paid), hosting on a cloud server / VPS is the most reliable hosting method. Rent a virtual server from any reputable hosting provider of your choice for roughly $4-10 USD per month (price varies), and you'll be able to install Modmail onto the 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. + +#### Community Guides +If you're not satisfied with the options listed above, some of our community members have created their +own installation guides for Modmail on various other hosting platforms. Keep in mind that Modmail support staff may +not be able to assist you much with community-made guides. Feel free to check them out by clicking the link below. + + + Community guides are not verified by the Modmail team, so use them at your own risk. + + + + + + + } + title="Syntax Highlighting" + href="/docs/guide/syntax-highlighting" + /> + + + + } + title="Syntax Highlighting" + href="/docs/guide/syntax-highlighting" + /> + + + + } + title="Syntax Highlighting" + href="/docs/guide/syntax-highlighting" + /> + + + \ No newline at end of file diff --git a/docs/pages/installation/_meta.json b/docs/pages/installation/_meta.json new file mode 100644 index 0000000000..36df5893bd --- /dev/null +++ b/docs/pages/installation/_meta.json @@ -0,0 +1,5 @@ +{ + "local-hosting": "Local Hosting", + "heroku": "Heroku", + "railway": "Railway" +} \ No newline at end of file diff --git a/docs/pages/installation/heroku.md b/docs/pages/installation/heroku.md new file mode 100644 index 0000000000..804e9e5d37 --- /dev/null +++ b/docs/pages/installation/heroku.md @@ -0,0 +1,58 @@ +--- +description: Deploy Modmail on Heroku PaaS. +--- + +# 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 + +* 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 + +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 12 months—enough to host Modmail free for one year. + +## 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**. + +
Screenshot of creating a Modmail 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**. + +
Screenshot of creating a Logviewer 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. + +
+ +
Screenshot of installing the pull app.

Click Install to install the Pull app.

+ + + +
Screenshot of selecting both repositories.

Select both the Modmail and Logviewer forks, then click Install.

+ +
+ +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 diff --git a/docs/pages/installation/local-hosting.mdx b/docs/pages/installation/local-hosting.mdx new file mode 100644 index 0000000000..793235bc10 --- /dev/null +++ b/docs/pages/installation/local-hosting.mdx @@ -0,0 +1,33 @@ +--- +title: Local Hosting Modmail +description: Hosting on the cloud or on your own computer. +--- + +# Local hosting / VPS + +## General Requirements + +* A supported hardware to comfortably run your chosen OS or a reliable VPS provider. +* Stable internet access and uptime for your machine or host. +* You have completed the initial steps in the [Installation](../) page. + +More OS-specific requirements will be listed on their specific installation page, you are free to choose a supported OS of your choice from the list below. + +## Choose your Operating System + +* [Windows](windows.md) +* [MacOS](macos.md) +* [Docker](docker.md) +* [Ubuntu](ubuntu.md) +* [Debian](debian.md) +* [Fedora](fedora.md) +* [Alma Linux](almalinux.md) +* [CentOS](almalinux.md) +* [Raspberry Pi OS](debian.md) + +## Logviewer + +You can also self-host logviewer by following the guides below. + +* [Logviewer](logviewer.md) +* [Patreon Logviewer](patreon\_logviewer.md) diff --git a/docs/pages/installation/local-hosting/README.md b/docs/pages/installation/local-hosting/README.md new file mode 100644 index 0000000000..0ae116b77c --- /dev/null +++ b/docs/pages/installation/local-hosting/README.md @@ -0,0 +1,32 @@ +--- +description: Hosting on the cloud or on your own computer. +--- + +# Local hosting / VPS + +## General Requirements + +* A supported hardware to comfortably run your chosen OS or a reliable VPS provider. +* Stable internet access and uptime for your machine or host. +* You have completed the initial steps in the [Installation](../) page. + +More OS-specific requirements will be listed on their specific installation page, you are free to choose a supported OS of your choice from the list below. + +## Choose your Operating System + +* [Windows](windows.md) +* [MacOS](macos.md) +* [Docker](docker.md) +* [Ubuntu](ubuntu.md) +* [Debian](debian.md) +* [Fedora](fedora.md) +* [Alma Linux](almalinux.md) +* [CentOS](almalinux.md) +* [Raspberry Pi OS](debian.md) + +## Logviewer + +You can also self-host logviewer by following the guides below. + +* [Logviewer](logviewer.md) +* [Patreon Logviewer](patreon\_logviewer.md) diff --git a/docs/pages/installation/local-hosting/almalinux.mdx b/docs/pages/installation/local-hosting/almalinux.mdx new file mode 100644 index 0000000000..e0799b3c82 --- /dev/null +++ b/docs/pages/installation/local-hosting/almalinux.mdx @@ -0,0 +1,101 @@ +--- +title: RHEL / Alma Linux / CentOS +--- + +import { Callout } from 'nextra-theme-docs' +import Image from 'next/image' +import { Steps } from 'nextra-theme-docs' +import { Card, Cards } from 'nextra-theme-docs' +import Link from 'next/link' + +# Alma Linux + + + For safety reasons, **DO NOT** install Modmail with a root user. A misbehaving or malicious plugin installed on your Modmail bot can easily access your entire system. If you are unsure how to create a new user on Linux, see [DigitalOcean’s tutorial: How To Create a New Sudo-enabled User](https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-20-04-quickstart). + + +Alma Linux 8, 9 and CentOS Stream 8, 9 are based on Red Hat Enterprise Linux (RHEL) 8 and 9 respectively so you can essentially follow this guide if you're running any of the OS mentioned above. + +## Prerequisites + +1. Root access (**`sudo`**). +2. Minimum 1GB of RAM +3. At least 2GB available disk space. +4. Supported releases: + * Alma Linux 9 + * Alma Linux 8 + * CentOS Stream 9 + * CentOS Stream 8 + * Red Hat Enterprise Linux (RHEL) 9 + * Red Hat Enterprise Linux (RHEL) 8 + +## Dependencies + +* Python 3.9 +* Tools: `git`, `nano` + + + All code blocks should be executed in bash and line by line unless specified otherwise. + + +### RHEL 9 / Alma Linux 9 / CentOS Stream 9 + +RHEL 9 and its derivatives have all required packages available in official repositories. Install them with `dnf`: + +```bash +sudo dnf -y install python39 git @development nano +``` + +### RHEL 8 / Alma Linux 8 / CentOS Stream 8.4-8.x + +RHEL 8 and its derivatives have all required packages available in official repositories. Install them with `dnf`: + +```bash +sudo dnf -y update +sudo dnf -y group install development +sudo dnf -y install python39 python39-pip python39-devel nano git +``` + +## Installing Bot + +Clone and change directory into the Modmail folder with: + +```bash +git clone https://github.com/modmail-dev/modmail +cd modmail +``` + +Inside the Modmail folder, ensure `pip` is installed correctly and is defaulting to Python 3.9 with: + +```bash +python3.9 -m ensurepip --upgrade +``` + +And then, install `pipenv` and the bot dependencies with: + +```bash +python3.9 -m pip install pipenv +python3.9 -m pipenv install --python 3.9 +``` + +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. + +```bash +nano .env +``` + +![](../../assets/vps-env.png) + +After that, press `Ctrl+O` and `Enter` to save your changes. Exit the `nano` editor with `Ctrl+X`. + + + If using the `nano` editor is a bit of a learning curve, you can always FTP into your server using software like [WinSCP](https://winscp.net/eng/index.php) to edit the `.env` file manually with your preferred GUI-based editor like Notepad. + + +After your `.env` file is ready, you can now go ahead and try running your bot with: + +```bash +python3.9 -m pipenv run bot +``` + +If no error shows up, it means your bot is now running correctly. You can stop the bot from running with `Ctrl+C` to continue using your terminal. diff --git a/docs/pages/installation/local-hosting/debian.mdx b/docs/pages/installation/local-hosting/debian.mdx new file mode 100644 index 0000000000..b422fbaed5 --- /dev/null +++ b/docs/pages/installation/local-hosting/debian.mdx @@ -0,0 +1,122 @@ +--- +Title: Debian / Raspberry Pi OS +--- + +import { Callout } from 'nextra-theme-docs' +import Image from 'next/image' +import { Steps } from 'nextra-theme-docs' +import { Card, Cards } from 'nextra-theme-docs' +import Link from 'next/link' + +# Debian + + +For safety reasons, **DO NOT** install Modmail with a root user. A misbehaving or malicious plugin installed on your Modmail bot can easily access your entire system. If you are unsure how to create a new user on Linux, see [DigitalOcean’s tutorial: How To Create a New Sudo-enabled User](https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-20-04-quickstart). + + +Raspberry Pi OS 11 Bullseye and Raspberry Pi OS 10 Buster are based on Debian 11 Bullseye and Debian 10 Buster respectively so you can essentially follow this guide if you're running any of the OS mentioned above. + +## Prerequisites + +1. Root access (**`sudo`**). +2. Minimum 1GB of RAM +3. At least 2GB available disk space. +4. Supported releases: + * Debian 11 Bullseye + * Debian 10 Buster + * Raspberry Pi OS 11 Bullseye + * Raspberry Pi OS 10 Buster + +## Dependencies + +* Python 3.9 / 3.10 +* Tools: `git`, `wget`, `nano` +* Additional Modmail requirements: `libcairo2-dev`, `libffi-dev`, `g++` + + +All code blocks should be executed in bash and line by line unless specified otherwise. + + +To install these dependencies, we will be using **`apt`**. + +### **Debian 11 Bullseye /** Raspberry Pi OS 11 Bullseye + +```bash +sudo apt update +sudo apt -y install python3 python3-dev python3-venv python3-pip libcairo2-dev libffi-dev g++ git wget nano +``` + +At the time of writing, this will install Python 3.9 from Debian's repository. + +### **Debian 10 Buster /** Raspberry Pi OS 10 Buster + +You will need to manually compile Python 3.10 from source. Compiling Python may take a while (est. 5-10 minutes). Make sure to run line 2-7 all at once. + +```bash +sudo apt update && sudo apt upgrade -y # Update and upgrade all packages +sudo apt install -y software-properties-common \ + libcairo2-dev libffi-dev g++ \ + git wget nano \ + build-essential zlib1g-dev libncurses5-dev \ + libgdbm-dev libnss3-dev libssl-dev \ + libreadline-dev libffi-dev libsqlite3-dev libbz2-dev +wget https://www.python.org/ftp/python/3.10.9/Python-3.10.9.tgz +tar xzf Python-3.10.9.tgz +cd Python-3.10.9 +./configure --enable-optimizations +sudo make altinstall +``` + +After that, ensure `pip` is installed and updated for Python 3.10 with: + +``` +python3.10 -m ensurepip --upgrade +``` + +Then **log out and log back in** to continue the installation steps. + +## Installing Bot + +Clone and change directory into the Modmail folder with: + +```bash +git clone https://github.com/modmail-dev/modmail +cd modmail +``` + +Inside the Modmail folder, Install `pipenv` and the bot dependencies with: + +```bash +python3.9 -m pip install pipenv +python3.9 -m pipenv install --python 3.9 +``` + + +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. + + +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. + +```bash +nano .env +``` + +![](../../assets/vps-env.png) + +After that, press `Ctrl+O` and `Enter` to save your changes. Exit the `nano` editor with `Ctrl+X`. + + +If using the `nano` editor is a bit of a learning curve, you can always FTP into your server using software like [WinSCP](https://winscp.net/eng/index.php) to edit the `.env` file manually with your preferred GUI-based editor like Notepad. + + +After your `.env` file is ready, you can now go ahead and try running your bot with: + +```bash +python3.9 -m pipenv run bot +``` + + +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. + + +If no error shows up, it means your bot is now running correctly. You can stop the bot from running with `Ctrl+C` to continue using your terminal. diff --git a/docs/pages/installation/local-hosting/docker.mdx b/docs/pages/installation/local-hosting/docker.mdx new file mode 100644 index 0000000000..20856b7a55 --- /dev/null +++ b/docs/pages/installation/local-hosting/docker.mdx @@ -0,0 +1,146 @@ +--- +description: Deploy Modmail on Docker. +--- + +import { Callout } from 'nextra-theme-docs' +import Image from 'next/image' +import { Steps } from 'nextra-theme-docs' +import { Card, Cards } from 'nextra-theme-docs' +import Link from 'next/link' + +# Docker + + +Docker is considered an advanced setup, it is recommended that you understand how Docker works before deciding to use this method. + + +![](../../assets/docker-illust.png) + +## Prerequisites + +* Supported OS for Docker +* Docker Engine +* Docker Compose + +## Installing Docker Engine + +Docker has their own installation page for popular Linux-based distros, read them by visiting the link below: + + + + + + } + title="Install Docker" + href="https://docs.docker.com/engine/install/" + /> + + +If you're on a desktop environment, refer to the "Desktop" section of their documentation as Docker Desktop also comes with nice GUI that you manage your deployments with. + +For VPS and servers, refer to the "Server" section as you will be needed to learn the CLI commands to run Modmail with Docker. + +After the installation process has finished, you can try running the commands below in your terminal to see if **Docker** and **Docker Compose** has been installed successfully: + +```docker +docker --version +docker compose version +``` + + +You may need to change your Docker Compose command to `docker-compose --version` depending on the version you have installed. + + +## Running the official image for Modmail + +You can pull the latest official image from Modmail repository by using the following command: + +```docker +docker pull ghcr.io/modmail-dev/modmail:master +``` + +This will take some time depending on the speed of your network. It will also update the already existing image if you have previously pulled the same image before. + +After that, you can run the bot as a container with the following command: + +```docker +docker run -d --name modmail \ +--env-file /path/to/.env \ +--restart always ghcr.io/modmail-dev/modmail:master +``` + +Make sure to change `/path/to/.env` to the location of the `.env` file containing all the variables that you want the bot to start with. Refer to the steps in the [parent Installation page](../#preparing-your-environmental-variables) to find where to obtain these. + +After deploying, you can view the logs of your currently running Modmail container with the following command: + +```docker +docker logs modmail +``` + +You can stop your running Modmail container with: + +``` +docker stop modmail +``` + +Stopping the container does not remove the container files, so you can start it back up with: + +``` +docker start modmail +``` + +If you want to stop and remove the container completely, you can do so with: + +``` +docker rm -f modmail +``` + +The `-f` will forcefully remove and delete the container even if it's currently running. You can omit the flag if the container is already stopped. + +## Building the image locally + +You can also build the image locally on your machine if the repository files are already in your machine. In your Modmail project folder, simply run the build command below: + +``` +docker build . -t myname/modmail:latest +``` + +The `.` in the command will use the `Dockerfile` in the Modmail repository as the build steps. The `-t` flag will specify the image tag so it's easier for us to differentiate between multiple images in our system. Verify if the image is successfully built with the following command: + +``` +docker images +``` + +You should be able to see the tag we just used in the list: + +![](../../assets/docker-image-ls.png) + +Now you can use the `docker run` command to run your bot using your locally-built image: + +```docker +docker run -d --name modmail \ +--env-file /path/to/.env \ +--restart always myname/modmail:latest +``` + +## Updating on Docker + +Auto-update is disabled when running Docker as Docker container state is not persistent across restarts. To update your bot, you will need to update the base image by running the `docker pull` command in the previous step: [Running the official image for Modmail](docker.md#running-the-official-image-for-modmail) if your image is based from the official repository. After that, you must recreate your container using the `docker rm` and `docker run` command again. + +If your image is created locally, simply replace the `docker pull` command with `git pull` and rebuilding your image again. + +To automate this process on Docker, you can look into running [Watchtower](https://containrrr.dev/watchtower/) which will auto-update your containers whenever a new image is pushed on the remote repository. Please refer to their documentation for guide and configuration. + diff --git a/docs/pages/installation/local-hosting/fedora.md b/docs/pages/installation/local-hosting/fedora.md new file mode 100644 index 0000000000..8295a70550 --- /dev/null +++ b/docs/pages/installation/local-hosting/fedora.md @@ -0,0 +1,80 @@ +--- +description: Deploy Modmail on a Fedora server. +--- + +# Fedora + + +For safety reasons, **DO NOT** install Modmail with a root user. A misbehaving or malicious plugin installed on your Modmail bot can easily access your entire system. If you are unsure how to create a new user on Linux, see [DigitalOcean’s tutorial: How To Create a New Sudo-enabled User](https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-20-04-quickstart). + + +## Prerequisites + +1. Root access (**`sudo`**). +2. Minimum 1GB of RAM +3. At least 2GB available disk space. +4. Supported releases: + * Fedora 38 + * Fedora 37 + * Fedora 36 + * Fedora 35 + +## Dependencies + +* Python 3.10 +* Tools: `git`, `wget`, `nano` +* Additional Modmail requirements: `g++` + + +All code blocks should be executed in bash and line by line unless specified otherwise. + + +Fedora Linux 35 and above has all required packages available in official repositories. Install them with `dnf`. + +```bash +sudo dnf -y install python310 git nano g++ gtk3 +``` + +And then, make sure `pip` is installed for Python 3.10 with: + +```bash +python3.10 -m ensurepip --upgrade +``` + +## Installing Bot + +Clone and change directory into the Modmail folder with: + +```bash +git clone https://github.com/modmail-dev/modmail +cd modmail +``` + +And then, install `pipenv` and the bot dependencies with: + +
python3.10 -m pip install pipenv
+python3.10 -m pipenv install --python 3.10
+
+ +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. + +```bash +nano .env +``` + +
+ +After that, press `Ctrl+O` and `Enter` to save your changes. Exit the `nano` editor with `Ctrl+X`. + + +If using the `nano` editor is a bit of a learning curve, you can always FTP into your server using software like [WinSCP](https://winscp.net/eng/index.php) to edit the `.env` file manually with your preferred GUI-based editor like Notepad. + + +After your `.env` file is ready, you can now go ahead and try running your bot with: + +```bash +python3.10 -m pipenv run bot +``` + +If no error shows up, it means your bot is now running correctly. You can stop the bot from running with `Ctrl+C` to continue using your terminal. + diff --git a/docs/pages/installation/local-hosting/macos.md b/docs/pages/installation/local-hosting/macos.md new file mode 100644 index 0000000000..c16aa34faa --- /dev/null +++ b/docs/pages/installation/local-hosting/macos.md @@ -0,0 +1,11 @@ +--- +description: Deploy Modmail on a MacOS machine. +--- + +# MacOS + +TODO + +## Prerequisites + +## Updating diff --git a/docs/pages/installation/local-hosting/ubuntu.md b/docs/pages/installation/local-hosting/ubuntu.md new file mode 100644 index 0000000000..307efafc30 --- /dev/null +++ b/docs/pages/installation/local-hosting/ubuntu.md @@ -0,0 +1,116 @@ +--- +description: Deploy Modmail on an Ubuntu server. +--- + +# Ubuntu + + +For safety reasons, **DO NOT** install Modmail with a root user. A misbehaving or malicious plugin installed on your Modmail bot can easily access your entire system. If you are unsure how to create a new user on Linux, see [DigitalOcean’s tutorial: How To Create a New Sudo-enabled User](https://www.digitalocean.com/community/tutorials/how-to-create-a-new-sudo-enabled-user-on-ubuntu-20-04-quickstart). + + +## Prerequisites + +1. Root access (**`sudo`**). +2. Minimum 1GB of RAM +3. At least 2GB available disk space. +4. Supported releases: + * Ubuntu 18.04 LTS (Bionic Beaver) + * Ubuntu 20.04 LTS (Focal Fossa) + * Ubuntu 22.04 LTS (Jammy Jellyfish) + +## Dependencies + +We will be using the following dependencies: + +* Python 3.10 +* Tools: `git`, `wget`, `nano`, `software-properties-common` +* Additional Modmail requirements: `libcairo2-dev`, `libffi-dev`, `g++` + + +All code blocks should be executed in bash and line by line unless specified otherwise. + + +To install these dependencies, we will be using **`apt`**. + +We recommend adding the `deadsnakes` ppa to install Python 3.10: + +```bash +sudo apt update +sudo apt -y install software-properties-common +sudo add-apt-repository -y ppa:deadsnakes/ppa +``` + +Now install the pre-requirements with `apt`, you can copy and run these 3 lines at once: + +```bash +sudo apt -y install python3.10 python3.10-dev python3.10-venv python3-pip \ + libcairo2-dev libffi-dev g++ \ + git nano +``` + +After that, install `pipenv` with: + +```bash +python3.10 -m pip install pipenv +``` + +
+ +Failed to install Python 3.10? + +You can manually compile Python instead of adding using the Deadsnakes PPA. Compiling Python may take a while (est. 5-10 minutes). Copy and run line 2-7 all at once. + +{% code lineNumbers="true" %} +```bash +sudo apt update && sudo apt upgrade -y # Update and upgrade all packages +sudo apt install -y software-properties-common \ + libcairo2-dev libffi-dev g++ \ + git wget nano \ + build-essential zlib1g-dev libncurses5-dev \ + libgdbm-dev libnss3-dev libssl-dev \ + libreadline-dev libffi-dev libsqlite3-dev libbz2-dev +wget https://www.python.org/ftp/python/3.10.9/Python-3.10.9.tgz +tar xzf Python-3.10.9.tgz +cd Python-3.10.9 +./configure --enable-optimizations +make altinstall +``` +{% endcode %} + +
+ +## Installing Bot + +Clone and change directory into the Modmail folder with: + +```bash +git clone https://github.com/modmail-dev/modmail +cd modmail +``` + +Inside the Modmail folder, Install `pipenv` and its Python packages with: + +
python3.10 -m pipenv install --python 3.10
+
+ +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. + +```bash +nano .env +``` + +
+ +After that, press `Ctrl+O` and `Enter` to save your changes. Exit the `nano` editor with `Ctrl+X`. + + +If using the `nano` editor is a bit of a learning curve, you can always FTP into your server using software like [WinSCP](https://winscp.net/eng/index.php) to edit the `.env` file manually with your preferred GUI-based editor like Notepad. + + +After your `.env` file is ready, you can now go ahead and try running your bot with: + +```bash +python3.10 -m pipenv run bot +``` + +If no error shows up, it means your bot is now running correctly. You can stop the bot from running with `Ctrl+C` to continue using your terminal. diff --git a/docs/pages/installation/local-hosting/windows.md b/docs/pages/installation/local-hosting/windows.md new file mode 100644 index 0000000000..0b91208789 --- /dev/null +++ b/docs/pages/installation/local-hosting/windows.md @@ -0,0 +1,82 @@ +--- +description: Deploy Modmail on a Windows machine. +--- + +# Windows + +## Prerequisites + +1. Minimum 2GB of RAM\* +2. At least 2GB available disk space. +3. Supported Windows version: + * Windows 10 + * Windows 11 + + +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. + + + +It is not recommended to run Modmail with previous versions of Windows such as Windows 7 or Windows 8.1 as they no longer receive important security updates, making your hosted applications significantly more prone to security vulnerabilities. + + +## Dependencies + +We will be using the following dependencies: + +* Chocolatey +* Python 3.10 +* Additional Modmail requirements: [GTK for Windows](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/) + +To install these dependencies, we will be using Powershell. + +Search “powershell” in the Windows start menu, right-click on it and then click “Run as administrator”. + +Then run each of the following commands: + +```powershell +Set-ExecutionPolicy Bypass -Scope Process -Force +[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072 +iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1')) +choco upgrade git --params "/GitOnlyOnPath /WindowsTerminal" -y +choco upgrade python310 -y +``` + +After that, ensure `pip` and `pipenv` are installed and updated for Python 3.10 with: + +```powershell +py -3.10 -m ensurepip --upgrade +py -3.10 -m pip install pipenv +``` + +After the above installation has finished, download and install the **GTK runtime for Windows** by [clicking here](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases/latest). + +## Installing Bot + +In any folder location of your choice, `Shift+Right Click` and click on `Open PowerShell window here`. + +In your PowerShell window, run these commands to clone the official Modmail repository locally and `cd` into the folder: + +```powershell +git clone https://github.com/modmail-dev/modmail +cd modmail +``` + +Install project dependencies inside Modmail's pipenv with: + +```powershell +py -3.10 -m pipenv install +``` + +Create a new file in the modmail folder named `.env` and paste in your environmental variables needed to run Modmail. Refer to the steps in the [parent Installation page](../#preparing-your-environmental-variables) to find where to obtain these. + +
+ +Lastly, in your PowerShell window simply enter the command below to run your Modmail bot: + +```powershell +py -3.10 -m pipenv run bot +``` + +If no error shows up, it means that your Modmail is now running correctly. + diff --git a/docs/pages/installation/railway.md b/docs/pages/installation/railway.md new file mode 100644 index 0000000000..8966fc4234 --- /dev/null +++ b/docs/pages/installation/railway.md @@ -0,0 +1,263 @@ +--- +description: Deploy Modmail on Railway PaaS. +--- + +# Railway + +## What is Railway? + +Railway is a deployment platform where you can provision infrastructure, develop with that infrastructure locally, and then deploy to the cloud. + +## Requirements + +* A credit card (for verification only). +* 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 + +Railway provides a **free** "Starter" plan. This plan allows you to try out their platform for free without requiring a credit card\*. Your bot will be online for 10 days after signing up. + +To keep your bot running 24/7, you'll need to sign up for their "Developer" plan. This plan is also **free**, but you will need to verify using your credit card, as it's to prevent abuse on their systems. + +\*Credit card may be required for some users. + +## Fork our GitHub repositories + +You will need to fork our repositories to deploy onto Railway. + +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/modmail-dev/modmail/fork](https://github.com/modmail-dev/modmail/fork), leave all the settings as default, and click **Create fork**. + +picture + +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**. + +picture + +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. + +picture + + + +picture + +Your GitHub should now be all set. Next step, [create a Railway account](railway.md#create-a-railway-account) to deploy your bot. + +## Create a Railway account + +Head over to [Railway's website](https://railway.app/new) and create an account. It will ask you to create a new project, choose **Deploy from GitHub repo**. Then, you will be asked to connect your GitHub account. + +picture + +
+ +Why does it says "Your Account is Unverified"? + +If your GitHub account is new or not reputable, you may be asked to verify your identify. + +This unfortunately means that you will have to provide a credit card for verification. Click **Verify Account**, read and accept Railway's **Terms of Service**, then enter your credit card details. You may be temporary charged $1 USD to confirm the legitimacy of the card. + +picture + +
+ +Next, you will be asked to **Configure a GitHub App**. You will be directed to the GitHub authentication page. Choose **Only select repositories**, then select **both** the Modmail and Logviewer repositories, as you have done before. Finally, click **Install & Authorize**. + +
+ +picture + + + +picture + +
+ +The next step is to deploy Modmail onto Railway. This is split into two parts. You will need to complete **both parts** to fully Modmail. + +## Part 1: Deploying the Logviewer + +From the [**New Project**](https://railway.app/new) page, create the project by selecting your **Logviewer** repository, then select **Add variables**. + +
+ +picture + + + +picture + +
+ +Click **New Variable**, set left to be **`CONNECTION_URI`**, then on the right, paste your revised MongoDB connection string from your Notepad (if this is new to you, [go back and read the initial steps](./)). + +Don't add any other variables, nor use the suggested variables section. You should see a new variable named **`CONNECTION_URI`** added under variables once you're done. + +
+ +picture + + +picture + + + +picture + +
+ +Next, go to the **Deployments** tab, look at the latest deployment, is it successful? You may need to wait up to 10 minutes. If you click the URL, you should be taken to your Logviewer homepage (see screenshot below). **Save this URL** into your Notepad as we will need it for the next step, we will be referring to this as your Logviewer URL. + +
+ +picture + + + +picture + +
+ +## Part 2: Deploying the Modmail bot + +From the [**New Project**](https://railway.app/new) page, create the project by selecting your **Modmail** repository, then select **Add variables**. + +
+ +picture + + + +picture + +
+ +Click **New Variable.** We will be adding 5 variables in total, so repeat this step until you've added all 5 variables. + +| Variable Name (left) | Variable Value (right) | Example | +| -------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | +| **`CONNECTION_URI`** | The MongoDB Connection string from your Notepad. | 
mongodb+srv://modmail:elAO7wF1r07pNG6u@cluster0.example.mongodb.net
+
| +| | | | +| **`TOKEN`** | The Discord bot token from your Notepad. | 
MTA3Djv3IAxNjk1NDgdKD231.G1AoUjD.5z629aKP34JKHn4v1EsdNUwdDO3MvBR9ifVES4
+
| +| | | | +| **`LOG_URL`** | The Logviewer URL from your Notepad. Remember to add `https://` in front! | 
https://web-production-1234.up.railway.app
+
| +| | | | +| **`OWNERS`** | Your Discord ID. If you have multiple owners, separate your IDs with a comma. | 
718827787302791100
+
| +| | | | +| **`GUILD_ID`** | The ID of the Discord server for your Modmail bot. | 
109483701365508619
+
| +| | | | + +
+ +Do you have a separate staff server? + +If you manage a large server where you have a separate server for communication among your moderation team, Modmail supports directing threads into the staff server instead of your main (public) server. + +Simply add an additional variable named **`MODMAIL_GUILD_ID`** and set the value to your staff server's ID. + +Note: the **`GUILD_ID`** should always be your main server's ID (not staff server's). + +If you haven't yet invited your Modmail bot to your staff server, see the [invite section](./#do-you-have-a-separate-staff-server). + +
+ +
+ +picture + + +picture + +
+ +## Complete the setup + +Within 10 minutes of saving the Modmail bot variables, your Modmail bot should come online in your server. The default prefix for Modmail is **`?`**. You need to run **`?setup`** within your server to complete the setup. If you configured Modmail to use a separate staff server, you must run this command **in your staff server**. This will create a category for your Modmail threads and a Logs channel for an archive of all past threads. + +
+ +Help! My bot hasn't started after 10 minutes. + +This probably means you've failed to follow one or more steps. \[more info TODO] + +
+ +## How to keep your bot running 24/7 + +You have 10 days to test Modmail without upgrading to the "Developer" plan. As mentioned in the [costs](railway.md#costs) section, Railway's Developer plan provides enough free monthly credits to run Modmail for **free** 24/7 everyday. However, you will need to provide your credit card details to upgrade your plan. More details can be found [here](https://docs.railway.app/reference/plans). + +#### Usage-based subscription + +Head over to the \*\*\*\* [**Billing Details**](https://railway.app/account/billing) page, click the **Unlock** button to unlock Developer plan. Then input your credit card details and hit **Subscribe to Developer Plan**. + +{% hint style="warning" %} +Subscribing to the Developer plan under _usage based subscription_ **may incur you unexpected charges**. This because Railway does not provide any safe-guards or monthly spending limits. Average Modmail and Logviewer usage should be well below the free threshold. However, if you run resource-intensive code via plugins or due to other means, you credit card may be billed. + +If you want to guarantee that your credit card won't get charged for whatever reason, check out the [credit-based subscription model](railway.md#credit-based-subscription-alternative-subscription-model) instead. Alternatively, you can use a virtual credit card, such as [privacy.com](https://privacy.com/virtual-card), to verify for the Developer plan. +{% endhint %} + +
+ +picture + + + +picture + +
+ +
+ +Why was I charged $1.00 USD? + +This should be a temporary charge to verify that your credit card works as expected. Railway explains this with: + +A temporary hold of $1.00 USD will be placed on the card and then refunded immediately. + +
+ +#### Credit-based subscription (alternative subscription model) + +If you rather pay a one-time $5.00 USD non-refundable credit purchase instead of permanently linking your credit card, you can choose to use the credit-based subscription model. As long as you have a non-zero credit balance (which should be forever since the monthly operating cost for Modmail is $0.00), you will be continuously subscribed to the Developer plan. + + +There you go! Your bot should now be able to run 24/7 without interruptions. Head over to the [**Usage**](https://railway.app/account/usage) page to make sure you won't be charged. Add up the estimated price for both your projects and verify that they're well below $5.00 USD. + + + +
+ +How do I cancel my Developer plan subscription? + +If you're subscribed under the [usage-based subscription](railway.md#usage-based-subscription) model, you can cancel your subscription by heading to the \*\*\*\* [**Billing Details**](https://railway.app/account/billing) page, click **Manage Subscription**, then click **Cancel plan**. + + + +
+ +## Updating + +Railway is configured to automatically update your Modmail bot and Logviewer whenever new updates become available. + +
+ +How do I disable auto-updates? + +You can disable auto-updates by heading to the settings page for **both** your Modmail and Logviewer projects. Under **Automatic Deployments**, click **Disable trigger**. + +
+ +## Next steps + +Now that you've successfully set up Modmail, visit the [Getting Started](../getting-started.md) page to find information on using Modmail. + +You can also join our [**Discord Server**](https://discord.gg/cnUpwrnpYb) to interact with our community or get support for Modmail. diff --git a/docs/pages/logviewer-installation.mdx b/docs/pages/logviewer-installation.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/pages/logviewer-installation/logviewer.md b/docs/pages/logviewer-installation/logviewer.md new file mode 100644 index 0000000000..292d6afdc0 --- /dev/null +++ b/docs/pages/logviewer-installation/logviewer.md @@ -0,0 +1,74 @@ +--- +description: Hosting the logviewer on the cloud or on your own computer. +--- + +# Logviewer + +## Prerequisites + +This logviewer hosting tutorial is written assuming you have already set up your bot and are running Ubuntu 20.04-22.04. + +## Downloading the files + +* You must have git installed on your system. If you do not, run `sudo apt install git` to install it. + +You can download the logviewer files by running the following command: + +```bash +git clone https://github.com/modmail-dev/logviewer logviewer +``` +
+Once done, you can use `cd logviewer` to enter the directory. + +## Installing the dependencies + +First, install pipenv by running the following command: + +* Pipenv must be installed. Since this is also used for the bot, you can skip this step if you have already installed it. + +```bash +python -m pip install pipenv +``` + +Installing the dependencies is done by running the following command: + +```bash +pipenv install +``` +
+ +## Configuring the .env + +To configure the `.env` file, you can use the following command: + +```bash +nano .env.example +``` +This will open the example `.env` file in nano. You can then edit the file with your info. +You will need to enter the same mongo URI as your bot uses. The rest of the configs can be left to the default values, unless you have a specific reason to change them. + +Then save the file and exit nano by pressing `ctrl + x`, then `y`, change the name from `.env.example` to `.env` and then `enter`. + +## Running the logviewer + +Now you can start the logviewer with the following command + +```bash +sudo pipenv run logviewer +``` + +## (Optional) Keep logviewer running in the background with pm2 + +Pm2 can keep your logviewer automatically online in the background even if you close your terminal. To install pm2, run the following command: + +```bash +sudo apt install npm -y && sudo npm i pm2 -g +``` + +Once installed, you can start the logviewer with pm2 by running the following command: + +```bash +sudo pm2 start logviewer.sh --name "logviewer" && sudo pm2 save +``` + +More info on how to use pm2 can be found [on pm2's website](https://pm2.keymetrics.io/docs/usage/quick-start/). diff --git a/docs/pages/logviewer-installation/patreon_logviewer.md b/docs/pages/logviewer-installation/patreon_logviewer.md new file mode 100644 index 0000000000..918c407daa --- /dev/null +++ b/docs/pages/logviewer-installation/patreon_logviewer.md @@ -0,0 +1,106 @@ +--- +description: Hosting the patreon logviewer on the cloud or on your own computer. +--- + +# Patreon logviewer + +This logviewer hosting tutorial is written assuming you have already set up your bot and are running Ubuntu 20.04-22.04. + +## Setting up OAuth2 + +To set up OAuth2, you need to set a few settings in your Discord Developer Portal. First, head to the [Discord Developer Portal](https://discord.com/developers/applications) and select your modmail bot application. Then go to "OAuth2" and "General" +
+ +First, copy the Client ID and Client Secret. You will need these later when filling in the `.env`. +Then, set a redirect URL to `https://yourlogviewer.com/callback`, with the url being changed to the url of your logviewer. +Finally, click save. +
+ +## Downloading the files + +* You must have git installed on your system. If you do not, run `sudo apt install git` to install it. + +Due to the logviewer premium repo being private, you will first need to set up a personal access token to clone the repo. To do this, follow the steps below. + +* Open github in your browser +* When logged in, click your name in the top right and go to 'settings' +* On the left, click 'Developer settings' +* On the left, click 'Personal access tokens' and then 'Tokens (classic)' +* Click 'Generate new token' +* Give the token a name and select the 'repo' scope +* Copy the token and save it somewhere safe + +
+
+
+
+
+ +You can download the logviewer files by running the following command: + +```bash +git clone https://github.com/modmail-dev/logviewer-premium logviewer +``` + +You will be prompted for your username and password. Enter your github username and the personal access token you just created. +
+Once done, you can use `cd logviewer` to enter the directory. + +## Installing the dependencies + +First, install pipenv by running the following command: + +* Pipenv must be installed. Since this is also used for the bot, you can skip this step if you have already installed it. + +```bash +python -m pip install pipenv +``` + +Installing the dependencies is done by running the following command: + +```bash +pipenv install +``` +
+ +## Configuring the .env + +To configure the `.env` file, you can use the following command: + +```bash +nano .env.example +``` +This will open the example `.env` file in nano. You can then edit the file with your info. Besides the normal logviewer config, you will also need to add your bot's token and the client ID and secret you copied earlier. + +You will need to enter the same mongo URI as your bot uses. The rest of the configs can be left to the default values, unless you have a specific reason to change them. + +Then save the file and exit nano by pressing `ctrl + x`, then `y`, change the name from `.env.example` to `.env` and then `enter`. + +## Running the logviewer + +Now you can start the logviewer with the following command + +```bash +sudo pipenv run logviewer +``` + +## Whitelisting users + +To allow people to view the logviewer, you will have to whitelist them. To do this, you can use the following command in discord where your modmail bot is: +`?oauth whitelist roleID` or `?oauth whitelist userID`. + +## (Optional) Keep logviewer running in the background with pm2 + +Pm2 can keep your logviewer automatically online in the background even if you close your terminal. To install pm2, run the following command: + +```bash +sudo apt install npm -y && sudo npm i pm2 -g +``` + +Once installed, you can start the logviewer with pm2 by running the following command: + +```bash +sudo pm2 start logviewer.sh --name "logviewer" && sudo pm2 save +``` + +More info on how to use pm2 can be found [on pm2's website](https://pm2.keymetrics.io/docs/usage/quick-start/). diff --git a/docs/pages/setting-up-auto-restart.md b/docs/pages/setting-up-auto-restart.md new file mode 100644 index 0000000000..287c1b757b --- /dev/null +++ b/docs/pages/setting-up-auto-restart.md @@ -0,0 +1,206 @@ +# Setting up auto-restart + +## Using PM2 on Linux + +PM2 is a process manager originally intended for Node.js but can also be used with Python applications, such as our Modmail bot and Logviewer. To use `pm2`, we will need to install Node Package Manager (`npm`). + +#### Installing `pm2` Using `apt` (Ubuntu, Debian, etc): + +```bash +sudo apt install npm -y && sudo npm i pm2 -g +``` + +#### Installing `pm2` using `dnf` (Fedora, Alma Linux, etc): + +```bash +sudo dnf -y install npm && sudo npm i pm2 -g +``` + +Then, in the Modmail folder, start the Modmail process in the background with: + +``` +pm2 start modmail.sh --name "modmail" +``` + +You can see the logs of your Modmail process with: + +``` +pm2 logs modmail +``` + +And then, to make sure that `pm2` stays active and persistent between machine restarts, run the following commands: + +```bash +pm2 save && pm2 startup +``` + +Here's some of the other PM2 commands for future reference: + +```bash +pm2 restart modmail +pm2 reload modmail +pm2 stop modmail +pm2 delete modmail +pm2 list +``` + +## Using systemd on Linux + +`systemd` is a built-in service manager for most Linux systems. It's primary used to manage background applications and services and to make applications auto-restart on crash and run on system startup. + +We will be using `systemd` for Modmail by making a service file for our bot. + +In order to create the service file, you will first need to know three things, your Linux `username`, your Modmail folder location as `modmail_path` and your Pipenv location as `pipenv_path`. + +First, your Linux `username` can be fetched with the following command: + +```bash +whoami +``` + +You can get your `pipenv_path` with: + +``` +whereis pipenv +``` + +Now, using `nano`, create a service file for systemd with: + +```bash +sudo nano /etc/systemd/system/modmail.service +``` + +and paste in the contents below, replacing `username`, `modmail_path` and `pipenv_path` with yours respectively. `Ctrl+O` and `Enter` to save. `Ctrl+X` to exit the nano editor. + +{% code title="modmail.service" %} +```bash +[Unit] +Description=Modmail bot +After=network.target + +[Service] +User=username # replace this +Group=username # replace this +Restart=always +RestartSec=10 +Type=simple +WorkingDirectory=modmail_path # replace this +ExecStart=pipenv_path run python bot.py # replace pipenv_path only + +[Install] +WantedBy=multi-user.target +``` +{% endcode %} + +Now, start your Modmail bot with: + +```bash +sudo systemctl start modmail +``` + +If everything goes correctly, you should see your bot online. You can also view the logs of your systemd process with: + +```bash +sudo journalctl -eu modmail +``` + +With that said, go ahead and enable your Modmail service to auto-restart after crash and reboot with: + +```bash +sudo systemctl enable modmail +``` + +If in the future you need to stop and disable your Modmail service, you can do so with: + +```bash +sudo systemctl stop modmail +sudo systemctl disable modmail +``` + +## Using PM2 on Windows + +Todo: [https://github.com/jessety/pm2-installer](https://github.com/jessety/pm2-installer) + +## Using NSSM on Windows + +To have the bot auto-restart on crash or system reboot, we will be using `nssm` by making a service for our bot application. + +First, find the Python path of your Modmail pipenv by running `pipenv shell` and `which python` in your Modmail folder. Copy the path that appears in your terminal and paste it in the first line of our next step. + +
+ +Second, create a file named `modmail.bat` in your modmail directory with the following contents, replacing `python_path` with the one you copied previously and `python.exe` with `activate.bat`: + +```batch +call python_path +call python bot.py +``` + +The finished file should look something like this: + +{% code title="modmail.bat" %} +```batch +call C:\Users\Raiden\.virtualenvs\modmail-oXWHQUly\Scripts\activate.bat +call python bot.py +``` +{% endcode %} + +Third, download `nssm` by [clicking here](http://nssm.cc/download) and downloading the file under "Latest Release". + +The download will be a `.zip` file so you'll need to extract it first using your file archiver program (such as WinRAR or 7-zip). After that, find `nssm.exe` in the folder corresponding to your OS bit version (these days it should be win64) and copy it's file path: + +
+ +As `nssm` itself is only a command-line program, we'll need to use our trusty Terminal to use the application to create our service. So, search up "Powershell" in your start menu, right-click it and click "Run as Administrator". + +Change directory (CD) into the folder path that you copied earlier, the command should look like something like this: + +```powershell +cd "C:\Users\Raiden\Downloads\nssm-2.24\win64" +``` + +{% hint style="info" %} +Wrapping "your folder\directory" on Windows in double quotes is necessary to make sure spaces in our file path is parsed correctly. +{% endhint %} + +And then, proceed to create a new service for Modmail using `nssm` with: + +```powershell +.\nssm install "Modmail" +``` + +A GUI will pop up where you can fill in the details needed for your Modmail service. Replace the `Path` with the path of your `modmail.bat` script and the `Startup directory` with the path of your Modmail folder as follow: + +
+ +You can fill in these extra details as you see fit as it's only for your own reference: + +
+ +You can also optionally specify a log file as output and error in the `I/O` tab, just be sure to create the file beforehand so you can select it in the GUI. + +
+ +And finally, click "Install Service" to install your Modmail bot as a service on your Windows system. + +
+ +By now you should have the service installed but not yet running. You can start it by using this command below in the open `nssm` Terminal from earlier: + +``` +.\nssm start modmail +``` + +
+ +You should be able to see your bot running if everything goes well. You can also verify the status of your Modmail service with: + +``` +.\nssm status modmail +``` + +And if you specified the log output file in your previous step, you should be able to see your current Modmail logs like so: + +
+ +And that's it! Your bot will now auto-start everytime you reboot your system. You can also additionally stop and restart your service with `.\nssm stop modmail` and `.\nssm restart modmail` respectively. Refer to [NSSM Documentation](http://nssm.cc/usage) for further customization as this guide is only meant to cover the basic needs adequate for standard Modmail usage. diff --git a/docs/pages/updating-logviewer.mdx b/docs/pages/updating-logviewer.mdx new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/pages/updating.md b/docs/pages/updating.md new file mode 100644 index 0000000000..bfb504f96d --- /dev/null +++ b/docs/pages/updating.md @@ -0,0 +1,36 @@ +--- +description: Guide on how to update the Modmail bot. +--- + +# Updating + +Your Modmail is set to auto-update itself by default, but you can also run the `?update` command on your bot manually, replacing `?` with your bot prefix. + +If for some reason your update command isn't working correctly, you can update your bot by going into your Modmail folder and pulling the latest changes from GitHub with the steps below. + +First, determine whether you have the official Modmail repository cloned or a fork by observing the output of the command below: + +``` +cat .git/config +``` + +If the output shows this exact URL as shown below, + +``` +[remote "origin"] + url = https://github.com/modmail-dev/modmail.git +``` + +you can go ahead and run the command below to pull in the latest changes: + +```bash +git pull +``` + +Else, it means that your repository is a fork and must update (aka sync) it independently. If your repository is hosted on GitHub, click on the button on your repo's GitHub URL as highlighted below: + +
+ +Run the `git pull` command above locally after syncing your fork. + +And then, be sure to restart your bot to apply the update. diff --git a/docs/public/header-pic.png b/docs/public/header-pic.png new file mode 100644 index 0000000000..50308f337b Binary files /dev/null and b/docs/public/header-pic.png differ diff --git a/docs/public/logo-ico.png b/docs/public/logo-ico.png new file mode 100644 index 0000000000..822b2196ca Binary files /dev/null and b/docs/public/logo-ico.png differ diff --git a/docs/public/logo-long.png b/docs/public/logo-long.png new file mode 100644 index 0000000000..b6791bf298 Binary files /dev/null and b/docs/public/logo-long.png differ diff --git a/docs/theme.config.tsx b/docs/theme.config.tsx index 88b8e2b18e..b1ba285c70 100644 --- a/docs/theme.config.tsx +++ b/docs/theme.config.tsx @@ -2,16 +2,37 @@ import React from 'react' import { DocsThemeConfig } from 'nextra-theme-docs' const config: DocsThemeConfig = { - logo: My Project, + logo: <> + zeabur + zeabur + , project: { - link: 'https://github.com/shuding/nextra-docs-template', + link: 'https://github.com/raidensakura/modmail', }, chat: { - link: 'https://discord.com', + link: 'https://dsc.gg/transience', }, - docsRepositoryBase: 'https://github.com/shuding/nextra-docs-template', + docsRepositoryBase: 'https://github.com/raidensakura/modmail/tree/develop/docs', footer: { - text: 'Nextra Docs Template', + text: ( + + {new Date().getFullYear()} ©{' '} + + A fork of Modmail + + . + + ), }, }