# Oracle Cloud Sign Up The first step is to sign up for Oracle Cloud {% hint style="info" %} It is recommended to use a PC for Sign Up {% endhint %} ## Sign Up In order to sign up, go to .\ Enter the information asked and click on "Verify my email"
An email will be sent to the address provided in the registration form.\ Click "Verify Email" in the email. You will then be asked to create a password as well as an account name and your preferred region. {% hint style="warning" %} It is recommended to select a region close to you to achieve the best possible performance. {% endhint %} Scroll to the bottom and click on "Continue"
You will then be asked to provide your home address as well as a mobile phone.
Finally, you will be asked to provide a payment method.
After you enter your payment method you should be redirected to the Oracle panel (in some regions it might take some time in order for your account to be set up {% hint style="warning" %} By registering for Oracle, you will get 300$ in credits for one month. After the credits expire, you will have up to four free VPSs of up to 24GB ram (in total) or two AMD based Compute VMs with 1/8 OCPU and 1 GB memory each. The next page will show you how to deploy a VPS which will work both in the free tier and the free trial. {% endhint %} {% hint style="danger" %} You will never get charged by Oracle after your 300$ in credits expire unless you upgrade to a paid plan. Make sure you don't. {% endhint %} # Deploying a VPS Here you will learn how to setup a VPS under Oracle's free tier. ## Deploying a VPS To begin, click on the three dashes in the top left corner. Go to Compute and click on Instances.
Click on "Create Instance"
Type a name of your choice. Under Image click on Change Image, click on Ubuntu, and choose Canonical Ubuntu 22.04. {% hint style="warning" %} We do not support nor recommend Ubuntu 24.04. Due to the introduction of PEP 668 and the upgrade of Python to a newer version, a lot of issues regarding dependencies have been created. We plan on supporting Oracle Linux, which uses DNF as its package manager, in the future. {% endhint %}
{% hint style="danger" %} Make sure you choose Always-Free Eligible images. {% endhint %} {% hint style="info" %} Although this guide has instructions for Ubuntu 22.04 only (currently), you can choose whatever OS you'd like as long as you are familiar with installing the required dependencies. {% endhint %} If you'd like to change the RAM/OCPUs of your VPS, you can click on Change shape under Shape. {% hint style="info" %} Although you can choose up to 24 GB of RAM for free, Modmail runs perfectly on 1 GB of RAM unless you are planning on hosting more than one instance or have a quite large server. {% endhint %} Click on Next (bottom left) and go to Security. There's nothing of importance in Security so click on next and go to Network. {% hint style="info" %} If you already have a VCN and subnet, it is recommended to use the same one. Please note that you can't create more than 2 VCNs under Oracle's free plan. Ingress and egress rules apply to all VPSs under the subnet. If you're planning on using different security rules, create a new VCN and subnet (as long as you don't go above the quota). {% endhint %} Scroll down to Add SSH keys, select Generate a key pair for me, and click on Download private key.
Click on Next to go to Storage. If you'd like to change the default storage, click on the toggle under "Specify a custom boot volume size and performance setting". Please note that you can't have more than 200 GB of space (in total) under Oracle's free plan. Once you are done, click on Next and once you review everything, click on Create.
{% hint style="danger" %} Depending on your region, you might get a "Out of capacity for shape VM.Standard.A1.Flex" error. In that case go back to Basic information. Above Availability domain you'll see a warning which specifies which availability domain supports the VM.Standard.E2.1.Micro shape. Select the availability domain and then scroll down to Shape. Click on Change shape, scroll down to Shape series, choose Specialty and previous generation and select VM.Standard.E2.1.Micro. {% endhint %} You are now ready to move to the next page! # Connecting to your VPS Here you will learn the basics of connecting to your VPS. Once your VPS has done provisioning, go to Details.
{% hint style="info" %} You'll now have to connect to your VPS. You can use PuTTY, Termius, or ssh. PuTTY is recommended for Windows while ssh is recommended for Linux and MacOS. For users who fancy a modern GUI, they can use Termius which is available on every OS. {% endhint %} ## PuTTY {% hint style="info" %} Instruction on how to instal PuTTY can be found in the [Install prerequisites](/installing-dependencies#putty) page. {% endhint %} ### Convert your SSH key into a PuTTY private Key In order to convert your SSH key into a PuTTY compatible key, you'll have to open PuTTYgen (this can be found from the Windows search bar) Once you are in PuTTYgen click "Load"
Make sure you choose "All Files" then choose the SSH key you downloaded previously.
Finally click on "Save private key" and make sure you save it somewhere you can remember.
### Import SSH key into PuTTY To start, open the PuTTY application. Go to Connection, then SSH, then click the + next to Auth, and finally, click on Credentials.
Finally click on browse and select the SSH key you saved in the previous step using PuTTYgen In order to connect to your VPS along with your SSH key you'll also need your instance's public IP and username. These can be found in the Details tab of your instance.
Go to Session and paste your IP address into the Host Name field.
Finally, click on "Open". If this prompt appears, click on "Accept"
When the login as: prompt appears, type your instance's username. Once you have connected to your VPS, move over to [Installing dependencies](/installing-dependencies#on-the-vps) ## Termius {% hint style="info" %} Instructions on how to install Termius can be found in the [Install prerequisites](/installing-dependencies#termius) page. {% endhint %} In order to connect to your VPS along with your SSH key you'll also need your instance's public IP and username. These can be found in the Details tab of your instance.
Click on "Add" then "New host"
Enter your IP address in the "Address" field. Import your key by clicking "Set a key" then "Create a new key" and select the key you've downloaded from Oracle. Enter your username and click on connect. Once you have connected to your VPS, move over to [Installing dependencies](/installing-dependencies#on-the-vps) ## Linux/MacOS built in SSH client In order to connect to your VPS along with your SSH key you'll also need your instance's public IP and username. These can be found in the Details tab of your instance.
Connect to your VM by running: ``` sudo ssh -i /path/to/key username@server-ip ``` Once you have connected to your VPS, move over to [Installing dependencies](/installing-dependencies#on-the-vps) # Installing dependencies Before using modmail you have to install some prerequisites. ## On your computer ### Putty #### Windows Install PuTTY on Windows directly from [here](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html). #### Linux {% hint style="warning" %} It is not recommended to use PuTTY on Linux. {% endhint %} Enable the universe repository using: ``` sudo add-apt-repository universe ``` Install PuTTY by using: ``` sudo apt install -y putty ``` You can open PuTTY by running `putty` on the terminal or you can manually search for the application. #### Mac {% hint style="warning" %} It is not recommended to use PuTTY on MacOS. {% endhint %} Install XCode developer tools from the app store [here](https://apps.apple.com/us/app/xcode/id497799835) and run these two commands. ``` xcodebuild -license ``` ``` xcode-select --install ``` Install XQuartz from [here](https://www.xquartz.org/). Install PuTTY by running this command ``` sudo port install putty ``` Run putty by using `putty` ### Termius #### Windows and Mac Install Termius directly from [here](https://termius.com/free-ssh-client-for-windows) for Windows or [here](https://termius.com/free-ssh-client-for-mac-os) for Mac. #### Linux Install Termius by running the command below otherwise you can install the .deb package from [here](https://termius.com/linux) if you are on a debian-based distro (Ubuntu, Debian, Linux Mint, etc). ``` sudo snap install termius-app ``` {% hint style="info" %} If you don't have Snap installed, you can find instructions on how to download it [here](https://snapcraft.io/docs/installing-snapd). {% endhint %} ## On your VPS {% hint style="danger" %} If at any time during installing dependencies the "(package name) has no installation candidate/(package name) is not available" error appears, your apt version is outdated as explained below. Run "sudo apt update && sudo apt upgrade" to fix this issue. {% endhint %} ### Upgrading the system It is necessary to update the system before proceeding. Start by updating the repositories: ``` sudo apt update ``` Then upgrade all packages: ``` sudo apt upgrade ``` {% hint style="info" %} If "Pending kernel upgrade" or "Daemons using outdated libraries" appears, hit Enter. {% endhint %} Once apt has finished upgrading, reboot the VPS: ``` sudo reboot ``` Wait \~1 minute for the reboot to finish then reconnect to your VPS. Sometimes apt doesn't get upgraded. To avoid this, upgrade the system once more. ``` sudo apt update ``` Then: ``` sudo apt upgrade ``` ### Pip and pipenv Install pip by running: ``` sudo apt install python3-pip ``` Install pipenv by running: ``` sudo pip install pipenv ``` ### PM2 {% hint style="warning" %} If you're not planning on using PM2, skip this section. PM2 is required for keeping your bot alive 24/7. {% endhint %} Start by installing node.js and npm: ``` sudo apt install nodejs npm ``` {% hint style="info" %} npm depends on a considerable amount of packages. Expect this to take some time. {% endhint %} Install pm2 by running: ``` sudo npm i -g pm2 ``` ### libcairosvg Install libcairosvg by running: ``` sudo apt install libpangocairo-1.0-0 ``` # Making Bot Application ## Create bot application First head on and click on " New Application. Input the name of your choice and click "Confirm"
A new screen should pop up. Navigate to the `Bot` section and click on `Add Bot`. Click on `Yes, do it!` to confirm.
After this, a dashboard for your bot will open. Give your bot a nice profile picture if you want to. It's recommended you switch off the `Public Bot` option. That way, no one except yourself will be able to add this bot to their server. Lastly, copy the token and paste this in your notepad.
Enable the "Presence Intent", "Server Members" and "Message content" intent within the dashboard.
The last thing you need to do in Discord's developer portal is to obtain an invite link for the bot. To do this, head over to the `OAuth2` tab. Scroll down a bit and select the `Bot` section. Scroll a bit further down and you will see a few permissions. Make sure to select `View Audit Log`, `Manage Channels` and `Manage Messages`.
Before you press "copy", scroll down and select the following permissions:
`Copy` the link and paste it in your address bar. A new screen will open: choose your server and select all options. Click on `Authorize` and your bot should be offline in your server.
# Setting Up MongoDB To be able to store data such as logs, you will need to use your own database. A database is required, as the database also stores configuration data for your bot. Upon creating an account, you will be greeted with this page. Make sure you select Starter Cluster.
After this, you will be taken to the below screen:
Select one of the servers marked with `FREE TIER AVAILABLE` and click on `Create Cluster`. It will only take a couple of minutes to configure everything for you. Follow the "Getting Started" tutorial on the bottom left.
Go to the `Database Access` section in the `security` tab. Click on `+ Add New User` to create a new user, whereupon a new screen will pop up. `Select Read and write to any database`, so the bot can properly store the data. Choose a username and password, but make sure they both **don't contain any special character like** `!`, `-`, `?`. Copy the password into your notepad. Finally, click `Add User` to finish the creation.
Go to the `Network Access` section in the `security` tab. Click on `+ Add IP Address` to add an IP address, whereupon a new screen will pop up. Click the `Allow Access From Everywhere` button and `0.0.0.0/0` should appear in the `Whitelist Entry`. Otherwise, make sure to put input that manually. Finally, click `Confirm` to confirm your changes.
The last part is to generate a Mongo URI. Go to the `Clusters` section in the `Atlas` tab. Click on `Connect` on the left side of your Cluster dashboard. This will open up a new screen where you have three options. For our purposes, select the middle option `Connect Your Application.`
You need to copy the connection string, which can be easily done by clicking the `Copy` button. Remove everything past `` but keeping the `/`. Then replace `` with the password for your user and `` with your database-username, which you set earlier. Paste the URI in your notepad. The final URI looks similar to this: `mongodb+srv://Username:MyPassword@modmail-kjvn21.mongodb.net/.`
# Installing and configuring Modmail ## Installing Modmail In order to install Modmail start by running: ``` git clone https://github.com/kyb3r/modmail ``` Go to the Modmail folder by running: ``` cd modmail ``` ## Configuring Modmail {% hint style="info" %} To paste text in PuTTY, right click or press Shift+Insert. {% endhint %} Start by renaming the .env.example file by running: ``` mv .env.example .env ``` Edit your .env file by running: ``` nano .env ``` In `TOKEN` paste your bot token that you created in [Making Bot Application](/making-bot-application)\ In `OWNERS` paste the ID of all the users that will have owner privileges.\ In `GUILD_ID` paste the ID of your server\ In `CONNECTION_URI` enter your MongoDB connection URI\ In `LOG_URL` enter your logviewer link To save your changes press Ctrl+X. On save modified buffer press Y. When File Name to Write: appears press enter. ## Starting Modmail ### Using Pipenv Install dependencies by running: ``` pipenv install ``` Finally run it by using ``` pipenv run bot ``` ### Using PM2 (recommended) {% hint style="warning" %} You need to use pipenv at least once before using PM2. {% endhint %} To start your bot using PM2 run ``` pm2 start modmail.sh --name "modmail" && pm2 save && pm2 startup ``` Once you run this command, you should see a command below "\[PM2] To setup the Startup Script, copy/paste the following command:". Copy and run the command. The command should look like this: ``` sudo env PATH=$PATH:/usr/bin /usr/local/lib/node_modules/pm2/bin/pm2 startup systemd -u ubuntu --hp /home/ubuntu ``` Congratulations! You now have a working Modmail. If you'd like to set up logviewer, continue to [Installing dependencies (logviewer)](/installing-dependencies-logviewer) {% hint style="danger" %} For any issues before the Installing dependencies step, please contact me (lidistat67). You can ping me in the server and I'll reply ASAP. For any issues during or after the Installing dependencies step, you may also contact the Modmail support team. {% endhint %} # Installing dependencies (logviewer) {% hint style="danger" %} As this page involves editing security rules, please follow the instructions below. Failure to do so may expose your VPS to security vulnerabilities. {% endhint %} ## Amending subnet rules Start by going to your instance's page on Oracle. Scroll down to Instance details and click on your Virtual cloud network.
Go to Subnets and click on your subnet.
Go to Security and click on your security list.
Click on Security rules and click on Add Ingress Rules.
Fill in the following: Source Type: `CIDR` \ Source CIDR: `0.0.0.0/0` \ IP Protocol: `TCP` \ Source Port Range: Blank\ Destination Port Range: `8000` (if you are planning on hosting logviewer on a different port, change this to the port of your choice.)\ Description: Blank Click on Add Ingress Rules to save your changes.
Now move over to your VPS in order to install additional dependencies. ## Python 3.9 Logviewer needs Python 3.9 in order to run. Don't worry as pipenv automatically detects which Python version to use and this won't interfere with your Modmail installation. Begin by adding the deadsnakes ppa: ``` sudo add-apt-repository ppa:deadsnakes/ppa ``` Install Python 3.9 and its distutils: ``` sudo apt install python3.9 python3.9-distutils ``` ## Amending iptables rules. iptables will prevent your public IP from being accessed. Solve this by running: ``` sudo iptables -I INPUT -j ACCEPT ``` Save this change permanently by doing the following: First of all, switch to the root account by running: ``` sudo su ``` Save the iptables change by running: ``` iptables-save > /etc/iptables/rules.v4 ``` Exit from the root account by running: ``` exit ``` ## PM2 {% hint style="info" %} If you installed PM2 during [Installing dependencies](/installing-dependencies#pm2), you may skip this step {% endhint %} {% hint style="warning" %} If you're not planning on using PM2, skip this section. PM2 is required for keeping your logviewer alive 24/7. {% endhint %} Start by installing node.js and npm: ``` sudo apt install nodejs npm ``` {% hint style="info" %} npm depends on a considerable amount of packages. Expect this to take some time. {% endhint %} Install pm2 by running: ``` sudo npm i -g pm2 ``` # Installing and configuring logviewer ## Installing logviewer Start by cloning the git repository: ``` git clone https://github.com/modmail-dev/logviewer logviewer ``` Move to the logviewer folder by running: ``` cd logviewer ``` ## Configuring logviewer Start by renaming the env file: ``` mv .env.example .env ``` Then edit it using: ``` nano .env ``` Fill `CONNECTION_URI=` with the MongoDB URI you obtained from [Setting Up MongoDB](/setting-up-mongodb). You don't need to edit anything else. Press CTRL+X, type Y, then hit enter to save your changes. ## Starting logviewer ### Using pipenv Install dependencies by running: ``` pipenv install ``` Run logviewer with: ``` pipenv run bot ``` ### Using PM2 (recommended) {% hint style="warning" %} You need to use pipenv at least once before using PM2. {% endhint %} To start logviewer using pm2 run: ``` pm2 start logviewer.sh --name "logviewer" && pm2 save ``` If this is the first time you're using PM2 and you haven't used it for Modmail you should see a command below "\[PM2] To setup the Startup Script, copy/paste the following command:". Copy and run the command. The command should look like this: ``` sudo env PATH=$PATH:/usr/bin /usr/local/lib/node_modules/pm2/bin/pm2 startup systemd -u ubuntu --hp /home/ubuntu ``` Congratulations! You now have a working Modmail and logviewer. {% hint style="danger" %} For any issues before the Installing dependencies step, please contact me (lidistat67). You can ping me in the server and I'll reply ASAP. For any issues during or after the Installing dependencies step, you may also contact the Modmail support team. {% endhint %}