From 9260b12982bbb4202597c8a84d6b661c4f0282d7 Mon Sep 17 00:00:00 2001 From: Tristan Gosselin-Hane Date: Sat, 10 Nov 2018 01:01:03 -0500 Subject: [PATCH] Add more documentation in the README --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 42 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 2a1feb0..955b15c 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,18 @@ # Minecraft Discord Bridge Required Python version: 3.6 or later. -Docker support: yes, recommended. +Docker is not required to run this bot but its use is strongly encouraged for ease of management. ## Installation instructions -1. Clone the repository -2. Edit the config.json file to your liking, an example is provided in `config.example.json` +1. Clone the repository. +2. Edit the config.json file to your liking, an example is provided in `config.example.json`. ``` mv config.example.json config.json vi config.json ``` -3. If you are using an sqlite database (like the default one in the config, create it now) + +3. If you are using an sqlite database (like the default one in the config, create it now). ``` touch db.sqlite @@ -19,28 +20,55 @@ Docker support: yes, recommended. 4. Run the bridge! 1. If you are not using docker, just install the dependencies and start the bot. + ``` python -m pipenv --three python -m pipenv install python -m pipenv run ./webhook-bridge.py ``` - 2. If you are using docker, just use the included `docker-compose.yml` to get up and running + + 2. If you are using docker, just use the included `docker-compose.yml` to get up and running. + ``` docker-compose up -d ``` - 5. If this is the first time you run this bridge, you need to invite it to your discord guild with the following link: - - **Note:** Make sure to replace the "" in the link below with your bot's client ID +5. If this is the first time you run this bridge, you need to invite it to your discord guild with the following link: + + **Note:** Make sure to replace the "" in the link below with your bot's client ID - `https://discordapp.com/oauth2/authorize?client_id=&scope=bot&permissions=536879104` + `https://discordapp.com/oauth2/authorize?client_id=&scope=bot&permissions=536879104` - Once it has joined your server, create a text channel for it to post in, then press the "Edit Channel" button on that channel. From there, press the "Permissions" button and click the "+" button and add "Minecraft Chat Bridge" to the room and close the permissions window. + Once it has joined your server, create a text channel for it to post in, then press the "Edit Channel" button on that channel. From there, press the "Permissions" button and click the "+" button and add "Minecraft Chat Bridge" to the room and close the permissions window. - Now that permissions are set, all you need to do is to do is to type "mc!chathere" and the bridge will take over if it is running. + Now that permissions are set, all you need to do is to do is to type "mc!chathere" and the bridge will take over if it is running. - - +## Creating a discord bot and getting its discord token + +1. Head over to the [discord developer portal](https://discordapp.com/developers/applications) and sign in if you haven't already. + +2. Press "Create an application". Once you do so, you may give the application a name and an icon if desired. + +3. From the left menu, click "Bot", then press "Add bot" on the next screen and "Yes do it" on the popup that appears. + +4. From here, you can once again give the Bot account your desired username and profile picture. + +5. Finally, Press the "Copy" button under the "Token" section to get your discord bot token. You can now paste it into this bridge's `config.json` file. + +## Creating the wildcard DNS record + +This step can be achieved in a variety of ways but I will cover basic steps for setting this up using the cloudflare DNS servers. + +1. [Create an account and add your domain to cloudflare](https://support.cloudflare.com/hc/en-us/articles/201720164-Step-2-Create-a-Cloudflare-account-and-add-a-website) + +2. From the cloudflare dashboard, click on your site and then click on the blue "DNS" icon at the top of the dashboard. + +3. From the DNS records section, select "A" in the dropdown, type any name you want in the "name" field and type in your computer's public IPv4 address into the "IPv4 address" field, then click on the orange cloud icon until it becomes gray and press the "Add Record" button. **Note:** If your computer is behind a NAT gateway, you will need to "port forward" the port specified in the `AUTH_SERVER.PORT` inside `config.json` to your computer's private IPv4 address. + +4. Repeat this process but choose "CNAME" from the dropdown, then type `*.authentication` (or anything you want as long as it starts with `*.`) and type whatever name you chose in step 3 into the "Domain name" box. Click on the orange cloud icon until it becomes gray and press the "Add Record" button. + +5. Set the `AUTH_SERVER.DNS_WILDCARD` node in `config.json` to the name you chose in step 4 (but without the `*.` part!!!) and append `.yourdomain.tld` to it where `yourdomain.tld` is the name of your domain. **e.g.** *For the record `*.authentication` on domain `example.com`, you would write `authentication.example.com`.* + ## Configuration All of the configuration data is stored in a file called `config.json` that must be stored in the same directory as the executable @@ -58,7 +86,7 @@ All of the configuration data is stored in a file called `config.json` that must |MAIN.ADMINS |\[283983554051047425\] |Array of discord user ids that have administrative access to the bot |AUTH_SERVER.BIND.IP |"" |The IPv4 address which the authentication server will bind to (set to blank for 0.0.0.0) |AUTH_SERVER.PORT |9822 |The port which the authentication server will bind to -|AUTH_SERVER.DNS_WILDCARD |"" |Must be set to a wildcard DNS `CNAME` record that points to and `A` record pointing to the authentication server's IP address +|AUTH_SERVER.DNS_WILDCARD |"" |Must be set to a wildcard DNS `CNAME` record that points to an `A` record pointing to the authentication server's IP address |DATABASE.CONNECTION_STRING |"sqlite:////data/db.sqlite"|Must be set to any valid `SQLAlchemy` connection string. Defaults to an empty sqlit database in `/data` for docker user |ELASTICSEARCH.ENABLED |false |Whether or not to enable elasticsearch analytics collection |ELASTICSEARCH.URL |"" |Fully qualified URL to the elasticsearch server