diff --git a/.gitbook/assets/27-272811_containerization-docker-explained-edureka-docker-explanation-hd-png-1221238558.png b/.gitbook/assets/27-272811_containerization-docker-explained-edureka-docker-explanation-hd-png-1221238558.png new file mode 100644 index 0000000..5373035 Binary files /dev/null and b/.gitbook/assets/27-272811_containerization-docker-explained-edureka-docker-explanation-hd-png-1221238558.png differ diff --git a/.gitbook/assets/Screenshot 2023-04-13 224748.png b/.gitbook/assets/Screenshot 2023-04-13 224748.png new file mode 100644 index 0000000..33fea16 Binary files /dev/null and b/.gitbook/assets/Screenshot 2023-04-13 224748.png differ diff --git a/SUMMARY.md b/SUMMARY.md index 2a40184..f31376f 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -16,22 +16,24 @@ * [Heroku](installation/heroku.md) * [Community Guides](installation/community-guides.md) * [Setting up auto-restart](setting-up-auto-restart.md) +* [Updating](updating.md) * [Getting Started](getting-started.md) * [Usage](usage-guide/README.md) * [Plugins](usage-guide/plugins.md) * [Configuration](usage-guide/configuration.md) * [Permissions](usage-guide/permissions.md) +* [Frequently Asked Questions](frequently-asked-questions.md) * [OLD DOCS](old-docs/README.md) * [Installation](installation-1.md) * [Installation (continued)](installation-continued.md) * [Color Names](color-names.md) * [Configuration Variables (Config Vars)](configuration-variables-config-vars.md) * [Configure Modmail and Logviewer](configure-modmail-and-logviewer.md) - * [Frequently Asked Questions](frequently-asked-questions.md) + * [Frequently Asked Questions]() * [Modmail Usage](modmail-usage.md) * [Permissions](permissions.md) * [Plugins](plugins.md) * [Seperate Server Setup](seperate-server-setup.md) * [The Unofficial List of Plugins](the-unofficial-list-of-plugins.md) - * [Updating](updating.md) + * [Updating]() * [Video Tutorials](video-tutorials.md) diff --git a/frequently-asked-questions (1).md b/frequently-asked-questions (1).md new file mode 100644 index 0000000..e39b59f --- /dev/null +++ b/frequently-asked-questions (1).md @@ -0,0 +1,53 @@ +# Frequently Asked Questions + +> Last Updated: March 16, 2023 + +#### What is Modmail? + +Modmail is a Discord bot, similar to Reddit's Modmail feature. It serves as a shared inbox for server staff to communicate with their users - and vice versa - in a seamless way. + +#### Can I invite Modmail? + +Unfortunately, due to the nature of the bot, there is not a global invite link. Nonetheless, you can obtain a free copy of Modmail for your server. Follow the official tutorial at [https://github.com/modmail-dev/modmail/wiki/Installation](https://github.com/modmail-dev/modmail/wiki/Installation). However, if you don’t want the hassle of installing and maintaining Modmail, we offer installation, hosting, and other cool perks for [Patrons](https://patreon.com/kyber). + +#### How does Modmail work? + +Modmail uses the Discord API to interact with the platform. When someone sends a DM to the bot, it will create a new thread. Members of the moderation team can help the user and once the conversation ended, you will have access to a beautiful log of it online. + +#### Is Modmail safe? + +Your Modmail bot is safe as long as you don't share your bot's token. If you share your token, a "hacker" can take control over your bot. If you shared your bot token by mistake, regenerate a new token via the Discord Developer Portal. + +#### Where is my data stored? + +All your data including settings, blocked users, logs, installed plugins etc. are stored in your MongoDB database. The bot files only contain the stuff needed to run the bot. This means you can move your bot to a different host and still have your data intact, as long as you use the same MongoDB URI. + +#### Can I request new features? + +Modmail is an open-source project, which means you can easily add or request new features. You can make an issue or submit a pull request to the development branch on the repository. [Check out the contribution guidelines.](https://github.com/modmail-dev/modmail/blob/master/CONTRIBUTING.md) + +#### How do I become a support member? + +To join our support team, join our [Discord server](https://discord.gg/cnUpwrnpYb). One of the more experienced members will hold an interview to check if you fit the requirements. + +#### Can I add commands to the bot? + +You can add commands to the bot using plugins. All currently approved plugins can be found in the `?plugin registry` command. You can also see [this page](https://github.com/modmail-dev/modmail/wiki/Unofficial-List-of-Plugins) for an unofficial list of plugins. + +#### My bot is offline, what do I do? + +Join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. One of our support members will assist you and help you fix the issue. + +#### How can I donate the developers? + +You can support the developers on the [Patreon page](https://patreon.com/kyber). You will also receive various rewards for it. + +#### Does anyone get any info when I create my own modmail? + +There is not much information we get about your instance of modmail, The only thing what we recieve is the guild-info, For example: The guildname, The amount of members of the guild, the botname, and the bot-owner. Using this we keep track of how many modmail-instances get created on a monthly/yearly base. ( Only modmail-developers can see this ) + +*** + +#### Answer not found? + +Feel free to join our [Discord server](https://discord.gg/cnUpwrnpYb). People will gladly help you with any questions that you have! diff --git a/frequently-asked-questions.md b/frequently-asked-questions.md index e39b59f..a832ca8 100644 --- a/frequently-asked-questions.md +++ b/frequently-asked-questions.md @@ -1,53 +1,27 @@ -# Frequently Asked Questions - -> Last Updated: March 16, 2023 - -#### What is Modmail? - -Modmail is a Discord bot, similar to Reddit's Modmail feature. It serves as a shared inbox for server staff to communicate with their users - and vice versa - in a seamless way. - -#### Can I invite Modmail? - -Unfortunately, due to the nature of the bot, there is not a global invite link. Nonetheless, you can obtain a free copy of Modmail for your server. Follow the official tutorial at [https://github.com/modmail-dev/modmail/wiki/Installation](https://github.com/modmail-dev/modmail/wiki/Installation). However, if you don’t want the hassle of installing and maintaining Modmail, we offer installation, hosting, and other cool perks for [Patrons](https://patreon.com/kyber). - -#### How does Modmail work? - -Modmail uses the Discord API to interact with the platform. When someone sends a DM to the bot, it will create a new thread. Members of the moderation team can help the user and once the conversation ended, you will have access to a beautiful log of it online. - -#### Is Modmail safe? - -Your Modmail bot is safe as long as you don't share your bot's token. If you share your token, a "hacker" can take control over your bot. If you shared your bot token by mistake, regenerate a new token via the Discord Developer Portal. +--- +description: A list of commonly asked questions or problems related to Modmail. +--- -#### Where is my data stored? - -All your data including settings, blocked users, logs, installed plugins etc. are stored in your MongoDB database. The bot files only contain the stuff needed to run the bot. This means you can move your bot to a different host and still have your data intact, as long as you use the same MongoDB URI. - -#### Can I request new features? - -Modmail is an open-source project, which means you can easily add or request new features. You can make an issue or submit a pull request to the development branch on the repository. [Check out the contribution guidelines.](https://github.com/modmail-dev/modmail/blob/master/CONTRIBUTING.md) - -#### How do I become a support member? - -To join our support team, join our [Discord server](https://discord.gg/cnUpwrnpYb). One of the more experienced members will hold an interview to check if you fit the requirements. - -#### Can I add commands to the bot? - -You can add commands to the bot using plugins. All currently approved plugins can be found in the `?plugin registry` command. You can also see [this page](https://github.com/modmail-dev/modmail/wiki/Unofficial-List-of-Plugins) for an unofficial list of plugins. - -#### My bot is offline, what do I do? +# Frequently Asked Questions -Join our [Discord server](https://discord.gg/cnUpwrnpYb) and DM Modmail. One of our support members will assist you and help you fix the issue. +### I tried installing the dependencies with another Python version and it messed up my Pipfile! How can I get the original Pipfile back? -#### How can I donate the developers? +First remove the broken `Pipfile` and `Pipfile.lock` with: -You can support the developers on the [Patreon page](https://patreon.com/kyber). You will also receive various rewards for it. +```bash +rm Pipfile && rm Pipfile.lock +``` -#### Does anyone get any info when I create my own modmail? +Fetch in the changes from the remote repository: -There is not much information we get about your instance of modmail, The only thing what we recieve is the guild-info, For example: The guildname, The amount of members of the guild, the botname, and the bot-owner. Using this we keep track of how many modmail-instances get created on a monthly/yearly base. ( Only modmail-developers can see this ) +```bash +git fetch origin +``` -*** +And then, fetch the original files with: -#### Answer not found? +```bash +git checkout FETCH_HEAD -- Pipfile && git checkout FETCH_HEAD -- Pipfile.lock +``` -Feel free to join our [Discord server](https://discord.gg/cnUpwrnpYb). People will gladly help you with any questions that you have! +### diff --git a/installation/community-guides.md b/installation/community-guides.md index 12c48f9..64ce8f4 100644 --- a/installation/community-guides.md +++ b/installation/community-guides.md @@ -12,6 +12,6 @@ Community guides are not verified by the Modmail team, so use them at your own r 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/4/11/hosting-discord-modmail-with-northflank/) Guide by raidensakura +## [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/installation/local-hosting-vps/almalinux.md b/installation/local-hosting-vps/almalinux.md index dbc4298..34301e1 100644 --- a/installation/local-hosting-vps/almalinux.md +++ b/installation/local-hosting-vps/almalinux.md @@ -4,14 +4,24 @@ description: Deploy Modmail on RHEL / Alma Linux / CentOS server. # Alma Linux +{% hint style="warning" %} +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). +{% endhint %} + 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 -* Root access (**`sudo`**). -* Minimum 1GB of RAM -* At least 2GB available disk space. -* Supported releases: Alma Linux 9, Alma Linux 8, CentOS Stream 9, CentOS Stream 8, RHEL 9 and RHEL 8 +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 @@ -24,7 +34,7 @@ All code blocks should be executed in bash and line by line unless specified oth ### RHEL 9 / Alma Linux 9 / CentOS Stream 9 -Alma Linux 9 have all required packages available in official repositories. Install them with `dnf`: +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 @@ -32,6 +42,8 @@ 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 @@ -40,10 +52,9 @@ sudo dnf -y install python39 python39-pip python39-devel nano git ## Installing Bot -In your home directory, clone and cd into the official Modmail repository with: +Clone and change directory into the Modmail folder with: ```bash -cd ~ git clone https://github.com/modmail-dev/modmail cd modmail ``` @@ -51,14 +62,14 @@ cd modmail Inside the Modmail folder, ensure `pip` is installed correctly and is defaulting to Python 3.9 with: ```bash -python3.9 -m ensurepip --default-pip +python3.9 -m ensurepip --upgrade ``` And then, install `pipenv` and the bot dependencies with: ```bash -pip3.9 install pipenv -pipenv install --python 3.9 +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. @@ -78,19 +89,7 @@ If using the `nano` editor is a bit of a learning curve, you can always FTP into After your `.env` file is ready, you can now go ahead and try running your bot with: ```bash -pipenv run bot -``` - -If no error shows up, it means your bot is now running correctly. - -## 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 like so: - -```bash -cd modmail && git pull +python3.9 -m pipenv run bot ``` -Be sure to restart your bot to apply the uupdate. +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/installation/local-hosting-vps/debian.md b/installation/local-hosting-vps/debian.md index c870b72..9046ff8 100644 --- a/installation/local-hosting-vps/debian.md +++ b/installation/local-hosting-vps/debian.md @@ -4,14 +4,22 @@ description: Deploy Modmail on Debian / Raspberry Pi OS. # Debian +{% hint style="warning" %} +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). +{% endhint %} + 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 -* Root access (**`sudo`**). -* Minimum 1GB of RAM -* At least 2GB available disk space. -* Supported releases: Debian 11 Bullseye, Debian 10 Buster, Raspberry Pi OS 11 Bullseye, and Raspberry Pi OS 10 (Legacy) Buster +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 @@ -36,8 +44,9 @@ 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). +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. +{% code lineNumbers="true" %} ```bash sudo apt update && sudo apt upgrade -y # Update and upgrade all packages sudo apt install -y software-properties-common \ @@ -52,31 +61,36 @@ cd Python-3.10.9 ./configure --enable-optimizations sudo make altinstall ``` +{% endcode %} -After following this step, make sure to specify the version when running user-level Python commands later in the guide. +After that, ensure `pip` is installed and updated for Python 3.10 with: -For example: +``` +python3.10 -m ensurepip --upgrade +``` -* `pip install pipenv` to `pip3.10 install pipenv` -* `python bot.py` to `python3.10 bot.py` +Then **log out and log back in** to continue the installation steps. ## Installing Bot -In your home directory, clone and cd into the official Modmail repository with: +Clone and change directory into the Modmail folder with: ```bash -cd ~ git clone https://github.com/modmail-dev/modmail cd modmail ``` -Inside the Modmail folder, Install `pipenv` and the bot dependencies with: +Inside the Modmail folder, Install `pipenv` and the bot dependencies with: ```bash -pip install pipenv -pipenv install +python3.9 -m pip install pipenv +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. +{% 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. ```bash @@ -94,19 +108,11 @@ If using the `nano` editor is a bit of a learning curve, you can always FTP into After your `.env` file is ready, you can now go ahead and try running your bot with: ```bash -pipenv run bot +python3.9 -m pipenv run bot ``` -If no error shows up, it means your bot is now running correctly. - -## 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 like so: - -```bash -cd modmail && git pull -``` +{% 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. +{% endhint %} -Be sure to restart your bot to apply the update. +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/installation/local-hosting-vps/docker.md b/installation/local-hosting-vps/docker.md index 60d9a1b..68f65aa 100644 --- a/installation/local-hosting-vps/docker.md +++ b/installation/local-hosting-vps/docker.md @@ -8,6 +8,8 @@ description: Deploy Modmail on Docker. Docker is considered an advanced setup, it is recommended that you understand how Docker works before deciding to use this method. {% endhint %} +

A simple illustration explaining how Docker works

+ ## Prerequisites * Supported OS for Docker @@ -107,9 +109,9 @@ docker run -d --name modmail \ --restart always myname/modmail:latest ``` -## Updating +## 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 run 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. +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. diff --git a/installation/local-hosting-vps/fedora.md b/installation/local-hosting-vps/fedora.md index 9fc9b8c..a5a629b 100644 --- a/installation/local-hosting-vps/fedora.md +++ b/installation/local-hosting-vps/fedora.md @@ -4,16 +4,24 @@ description: Deploy Modmail on a Fedora server. # Fedora +{% hint style="warning" %} +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). +{% endhint %} + ## Prerequisites -* Root access (**`sudo`**). -* Minimum 1GB of RAM -* At least 2GB available disk space. -* Supported releases: Fedora 37, Fedora 36, Fedora 35. +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.9 +* Python 3.10 * Tools: `git`, `wget`, `nano` * Additional Modmail requirements: `g++` @@ -24,31 +32,29 @@ All code blocks should be executed in bash and line by line unless specified oth Fedora Linux 35 and above has all required packages available in official repositories. Install them with `dnf`. ```bash -sudo dnf -y install python39 git nano g++ gtk3 +sudo dnf -y install python310 git nano g++ gtk3 ``` -## Installing Bot - -In your home directory, clone and cd into the official Modmail repository with: +And then, make sure `pip` is installed for Python 3.10 with: ```bash -cd ~ -git clone https://github.com/modmail-dev/modmail -cd modmail +python3.10 -m ensurepip --upgrade ``` -Inside the Modmail folder, ensure `pip` is installed correctly and is defaulting to Python 3.9 with: +## Installing Bot + +Clone and change directory into the Modmail folder with: ```bash -python3.9 -m ensurepip --default-pip +git clone https://github.com/modmail-dev/modmail +cd modmail ``` And then, install `pipenv` and the bot dependencies with: -```bash -pip install pipenv -pipenv install --python 3.9 -``` +
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. @@ -67,20 +73,8 @@ If using the `nano` editor is a bit of a learning curve, you can always FTP into After your `.env` file is ready, you can now go ahead and try running your bot with: ```bash -pipenv run bot -``` - -If no error shows up, it means your bot is now running correctly. - -## 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 like so: - -```bash -cd modmail && git pull +python3.10 -m pipenv run bot ``` -Be sure to restart your bot to apply the update. +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/installation/local-hosting-vps/ubuntu.md b/installation/local-hosting-vps/ubuntu.md index 2104a67..5f73513 100644 --- a/installation/local-hosting-vps/ubuntu.md +++ b/installation/local-hosting-vps/ubuntu.md @@ -4,12 +4,19 @@ description: Deploy Modmail on an Ubuntu server. # Ubuntu +{% hint style="warning" %} +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). +{% endhint %} + ## Prerequisites -* Root access (**`sudo`**). -* Minimum 1GB of RAM -* At least 2GB available disk space. -* Supported releases: Ubuntu 18.04 LTS, Ubuntu 20.04 LTS, Ubuntu 22.04 LTS. +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 @@ -38,15 +45,22 @@ Now install the pre-requirements with `apt`, you can copy and run these 3 lines ```bash sudo apt -y install python3.10 python3.10-dev python3.10-venv python3-pip \ libcairo2-dev libffi-dev g++ \ - git wget nano + 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). +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 \ @@ -61,32 +75,23 @@ cd Python-3.10.9 ./configure --enable-optimizations make altinstall ``` - -After following this step, make sure to specify the version when running user-level Python commands later in the guide. - -For example: - -* `pip install pipenv` to `pip3.10 install pipenv` -* `python bot.py` to `python3.10 bot.py` +{% endcode %}
## Installing Bot -In your home directory, clone and cd into the official Modmail repository with: +Clone and change directory into the Modmail folder with: ```bash -cd ~ git clone https://github.com/modmail-dev/modmail cd modmail ``` -Inside the Modmail folder, Install `pipenv` and the bot dependencies with: +Inside the Modmail folder, Install `pipenv` and its Python packages with: -```bash -pip install pipenv -pipenv install -``` +
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. @@ -105,19 +110,7 @@ If using the `nano` editor is a bit of a learning curve, you can always FTP into After your `.env` file is ready, you can now go ahead and try running your bot with: ```bash -pipenv run bot -``` - -If no error shows up, it means your bot is now running correctly. - -## 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 like so: - -```bash -cd modmail && git pull +python3.10 -m pipenv run bot ``` -Be sure to restart your bot to apply the update. +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/installation/local-hosting-vps/windows.md b/installation/local-hosting-vps/windows.md index 9652e9d..aa19ea1 100644 --- a/installation/local-hosting-vps/windows.md +++ b/installation/local-hosting-vps/windows.md @@ -6,9 +6,11 @@ description: Deploy Modmail on a Windows machine. ## Prerequisites -* Minimum 2GB of RAM**\*** -* At least 2GB available disk space. -* Supported Windows version: Windows 10 or Windows 11. +1. Minimum 2GB of RAM\* +2. At least 2GB available disk space. +3. Supported Windows version: + * Windows 10 + * 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. @@ -40,6 +42,13 @@ 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 @@ -49,13 +58,14 @@ In any folder location of your choice, `Shift+Right Click` and click on `Open Po 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 +git clone https://github.com/modmail-dev/modmail +cd modmail ``` -Install Pipenv and project dependencies with: +Install project dependencies inside Modmail's pipenv with: ```powershell -pip install pipenv; pipenv install +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. @@ -65,19 +75,8 @@ Create a new file in the modmail folder named `.env` and paste in your environme Lastly, in your PowerShell window simply enter the command below to run your Modmail bot: ```powershell -pipenv run bot +py -3.10 -m pipenv run bot ``` If no error shows up, it means that your Modmail is now running correctly. -## 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 opening PowerShell or any terminal application in your modmail folder and pulling the latest changes from GitHub like so: - -``` -git pull -``` - -After that, simply restart your bot to apply the latest changes. diff --git a/setting-up-auto-restart.md b/setting-up-auto-restart.md index aea9de1..287c1b7 100644 --- a/setting-up-auto-restart.md +++ b/setting-up-auto-restart.md @@ -1,25 +1,31 @@ # Setting up auto-restart -## Using pm2 on Linux +## Using PM2 on Linux -`pm2` is a process manager 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.js. +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`: +#### Installing `pm2` Using `apt` (Ubuntu, Debian, etc): ```bash sudo apt install npm -y && sudo npm i pm2 -g ``` -#### Installing `pm2` using `dnf`: +#### 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 with: +Then, in the Modmail folder, start the Modmail process in the background with: ``` -sudo pm2 start modmail.sh --name "modmail" +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: @@ -28,28 +34,28 @@ And then, to make sure that `pm2` stays active and persistent between machine re pm2 save && pm2 startup ``` -## Using systemd on Linux - -To have the bot auto-restart on crash or system reboot, we will be using `systemd` 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 repository `path` and your Pipenv `path`. - -First, your Linux `username` can be fetched with the following command: +Here's some of the other PM2 commands for future reference: ```bash -whoami +pm2 restart modmail +pm2 reload modmail +pm2 stop modmail +pm2 delete modmail +pm2 list ``` -If you have cloned the Modmail repo as a `root` user, your Modmail repo path should be: +## Using systemd on Linux -```bash -/root/modmail -``` +`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. -Otherwise, your path should be: +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 -/home/$USER/modmail/ +whoami ``` You can get your `pipenv_path` with: @@ -111,7 +117,11 @@ sudo systemctl stop modmail sudo systemctl disable modmail ``` -## Using `nssm` on Windows +## 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. @@ -150,7 +160,7 @@ cd "C:\Users\Raiden\Downloads\nssm-2.24\win64" ``` {% hint style="info" %} -Wrapping "your folder\directory" on Windows in doublequotes is necessary to make sure spaces in our file path is parsed correctly. +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: diff --git a/updating (1).md b/updating (1).md new file mode 100644 index 0000000..e2485ce --- /dev/null +++ b/updating (1).md @@ -0,0 +1,38 @@ +# 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. + + ![sync-fork-dropdown](https://user-images.githubusercontent.com/70805800/194696934-5333af5d-165e-4873-b5b7-bd01f0461185.png) +3. Then click Update branch. + + ![update-branch-button](https://user-images.githubusercontent.com/70805800/194696947-68891d50-a624-4901-a03d-e49564852a23.png) + +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 ![](https://i.imgur.com/qjWraS0.png) +5. Turn on automatic deploys ![](https://i.imgur.com/jgUVl7f.png) +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. diff --git a/updating.md b/updating.md index e2485ce..bfb504f 100644 --- a/updating.md +++ b/updating.md @@ -1,38 +1,36 @@ -# Updating - -## Updating Modmail +--- +description: Guide on how to update the Modmail bot. +--- -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 +# Updating -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. +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. -### Syncing a fork branch from the web UI +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. -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. +First, determine whether you have the official Modmail repository cloned or a fork by observing the output of the command below: - ![sync-fork-dropdown](https://user-images.githubusercontent.com/70805800/194696934-5333af5d-165e-4873-b5b7-bd01f0461185.png) -3. Then click Update branch. +``` +cat .git/config +``` - ![update-branch-button](https://user-images.githubusercontent.com/70805800/194696947-68891d50-a624-4901-a03d-e49564852a23.png) +If the output shows this exact URL as shown below, -If the changes from the upstream repository cause conflicts, GitHub will prompt you to create a pull request to resolve the conflicts. +``` +[remote "origin"] + url = https://github.com/modmail-dev/modmail.git +``` -### I want to enable automatic updates +you can go ahead and run the command below to pull in the latest changes: -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 ![](https://i.imgur.com/qjWraS0.png) -5. Turn on automatic deploys ![](https://i.imgur.com/jgUVl7f.png) -6. Restart the bot +```bash +git pull +``` -### I want to update the bot once +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: -[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. +Run the `git pull` command above locally after syncing your fork. -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. +And then, be sure to restart your bot to apply the update.