Skip to content

Commit 88676e5

Browse files
Taaku18Taaku18
committed
Update docker compose, changelog, and installation guide
1 parent 5ea119f commit 88676e5

File tree

3 files changed

+74
-63
lines changed

3 files changed

+74
-63
lines changed

‎CHANGELOG.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ however, insignificant breaking changes do not guarantee a major version bump, s
2323
### Changed
2424

2525
- Plain messages no longer forces `()` around the respondent text. ([PR #3234](https://github.com/kyb3r/modmail/pull/3234))
26+
- Added workflow to automatically build Docker image ([PR #3232](https://github.com/kyb3r/modmail/pull/3228))
27+
- Updated installation guide to reflect new preferred hosting methods
2628

2729
# v4.0.1
2830

‎README.md

Lines changed: 70 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -84,80 +84,89 @@ This list is ever-growing thanks to active development and our exceptional contr
8484

8585
## Installation
8686

87-
Where can I find the Modmail bot invite link?
87+
Q: Where can I find the Modmail bot invite link?
88+
89+
A: Unfortunately, due to how this bot functions, it cannot be invited. The lack of an invite link is to ensure an individuality to your server and grant you full control over your bot and data. Nonetheless, you can quickly obtain a free copy of Modmail for your server by following one of the methods listed below (roughly takes 15 minutes of your time).
90+
91+
There are a few options for hosting your very own dedicated Modmail bot.
92+
93+
1. Patreon hosting
94+
2. Local hosting (VPS, Dedicated Server, RPi, your computer, etc.)
95+
3. PaaS (we provide a guide for Heroku)
96+
97+
### Patreon Hosting
98+
99+
If you don't want the trouble of renting and configuring your server to host Modmail, we got a solution for you! We offer hosting and maintenance of your own, private Modmail bot (including a Logviewer) through [**Patreon**](https://patreon.com/kyber). Join our [Modmail Discord Server](https://discord.gg/etJNHCQ) for more info!
100+
101+
### Local hosting (General Guide)
102+
103+
Modmail can be hosted on any modern hardware, including your PC. For stability and reliability, we suggest purchasing a cloud server (VPS) for under $10/mo. If you need recommendations on choosing a VPS, join our [Discord server](https://discord.gg/j5e9p8w), and we'll send you a list of non-affiliated hosting providers. Alternatively, we can host Modmail for you when you're subscribed to our [Patreon](https://patreon.com/kyber).
104+
105+
This guide assumes you've downloaded [`Python 3.10`](https://www.python.org/downloads/release/python-376/) and added python and pip to PATH.
106+
107+
1. Clone this repo
108+
```console
109+
$ git clone https://github.com/kyb3r/modmail
110+
$ cd modmail
111+
```
112+
2. Create a Discord bot account, grant the necessary intents, and invite the bot ([guide](https://github.com/kyb3r/modmail/wiki/Installation#2-discord-bot-account))
113+
3. Create a free MongoDB database ([guide](https://github.com/kyb3r/modmail/wiki/Installation-(cont.)#3-create-a-database), follow it carefully!)
114+
4. Rename the file `.env.example` to `.env` and fill it with appropriate values
115+
- If you can't find `.env.example` because it's hidden, create a new text file named `.env`, then copy the contents of [this file](https://raw.githubusercontent.com/kyb3r/modmail/master/.env.example) and replace the placeholders with their values
116+
- If you're on Windows and cannot save the file as `.env`, save it as `.env.` instead (this only applies to Windows!)
117+
- If you do not have a Logviewer yet, leave the `LOG_URL` field as-is
118+
5. Update pip, install pipenv, and install dependencies using pipenv
119+
```console
120+
$ pip install -U pip
121+
$ pip install pipenv
122+
$ pipenv install
123+
```
124+
6. Start the bot
125+
```console
126+
$ pipenv run bot
127+
```
128+
7. Set up the Logviewer, see the [Logviewer installation guide](https://github.com/kyb3r/logviewer)
129+
130+
### Local Hosting (Docker)
131+
132+
We provide support for Docker to simplify the deployment of Modmail and Logviewer.
133+
We assume you already have Docker and Docker Compose Plugin installed, if not, see [here](https://docs.docker.com/get-docker/).
134+
135+
1. Create a Discord bot account, grant the necessary intents, and invite the bot ([guide](https://github.com/kyb3r/modmail/wiki/Installation#2-discord-bot-account))
136+
2. Create a file named `.env`, then copy the contents of [this file](https://raw.githubusercontent.com/kyb3r/modmail/master/.env.example) and replace the placeholders with their values
137+
3. Create a file named `docker-compose.yml`, then copy the contents of [this file](https://raw.githubusercontent.com/kyb3r/modmail/master/docker-compose.yml), do not change anything!
138+
4. Start the bot
139+
```console
140+
$ docker compose up -d
141+
```
142+
- For older Docker versions, you may need to run `docker-compose up -d` instead
143+
5. View the status of your bot, using `docker ps` and `docker logs [container-id]`
144+
145+
Our Docker images are hosted on [GitHub Container Registry](ghcr.io), you can build your own image if you wish:
146+
```console
147+
$ docker build --tag=modmail:master .
148+
```
149+
150+
Then simply remove `ghcr.io/kyb3r/` from the `docker-compose.yml` file.
88151

89-
Unfortunately, due to how this bot functions, it cannot be invited. The lack of an invite link is to ensure an individuality to your server and grant you full control over your bot and data. Nonetheless, you can quickly obtain a free copy of Modmail for your server by following one of the methods listed below (roughly takes 15 minutes of your time).
152+
### Local Hosting (OS-Specific)
90153

91-
### Heroku
154+
This guide is a WIP. Join our [Discord server](https://discord.gg/j5e9p8w) for more info.
92155

93-
You can host this bot on Heroku.
156+
### Platform as a Service (PaaS)
157+
158+
You can host this bot on Heroku (no longer free).
94159

95160
Installation via Heroku is possible with your web browser alone.
96161
The [**installation guide**](https://github.com/kyb3r/modmail/wiki/Installation) (which includes a video tutorial!) will guide you through the entire installation process. If you run into any problems, join our [Modmail Discord Server](https://discord.gg/etJNHCQ) for help and support.
97162

98-
To configure automatic updates:
163+
When using Heroku, you can configure automatic updates:
99164
- Login to [GitHub](https://github.com/) and verify your account.
100165
- [Fork the repo](https://github.com/kyb3r/modmail/fork).
101166
- Install the [Pull app](https://github.com/apps/pull) for your fork.
102167
- Then go to the Deploy tab in your [Heroku account](https://dashboard.heroku.com/apps) of your bot app, select GitHub and connect your fork (usually by typing "Modmail").
103168
- Turn on auto-deploy for the `master` branch.
104169

105-
### Hosting for Patreons
106-
107-
If you don't want to go through the trouble of setting up your very own Modmail bot or wish to support this project, we got a solution for you! We offer the complete installation, hosting, and maintenance of your Modmail with [**Patreon**](https://patreon.com/kyber). Join our [Modmail Discord Server](https://discord.gg/etJNHCQ) for more info!
108-
109-
### Locally
110-
111-
Local hosting of Modmail is also possible. First, you will need at least [`Python 3.8`](https://www.python.org/downloads/release/python-376/).
112-
113-
Follow the [**installation guide**](https://github.com/kyb3r/modmail/wiki/Installation) and disregard deploying the Heroku bot application. If you run into any problems, join our [Modmail Discord Server](https://discord.gg/etJNHCQ) for help and support.
114-
115-
Clone the repo:
116-
117-
```console
118-
$ git clone https://github.com/kyb3r/modmail
119-
$ cd modmail
120-
```
121-
122-
Install dependencies:
123-
124-
```console
125-
$ pipenv install
126-
```
127-
128-
Rename the `.env.example` to `.env` and fill out the fields. If `.env.example` is nonexistent (hidden), create a text file named `.env` and copy the contents of [`.env.example`](https://raw.githubusercontent.com/kyb3r/modmail/master/.env.example) then modify the values.
129-
130-
Finally, start Modmail.
131-
132-
```console
133-
$ pipenv run bot
134-
```
135-
136-
#### Docker
137-
138-
This repo supplies a Dockerfile for simplified deployment.
139-
140-
You can build your own Docker image:
141-
142-
```console
143-
$ docker build . --tag=modmail
144-
```
145-
146-
Or run directly from a pre-built version from https://hub.docker.com/.
147-
148-
- Kyber's:
149-
150-
```console
151-
$ docker pull kyb3rr/modmail
152-
```
153-
154-
And to run your docker image:
155-
156-
```console
157-
$ docker run --env-file .env kyb3rr/modmail
158-
```
159-
- `.env` should be the path to your env file; you can also supply a path: `/path/to/.env`.
160-
161170
## Sponsors
162171

163172
Special thanks to our sponsors for supporting the project.

‎docker-compose.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
version: "3.7"
22
services:
33
bot:
4-
image: kyb3rr/modmail
4+
image: ghcr.io/kyb3r/modmail:master
55
restart: always
66
env_file:
77
- .env
@@ -10,7 +10,7 @@ services:
1010
depends_on:
1111
- mongo
1212
logviewer:
13-
image: kyb3rr/logviewer
13+
image: ghcr.io/kyb3r/logviewer:master
1414
restart: always
1515
depends_on:
1616
- mongo

0 commit comments

Comments
 (0)