Merge pull request #55 from Mimickal/v2-docs

Author: Mimickal

README.md

@@ -132,59 +132,10 @@ up react roles for `@everyone` like you would for any other role. It's silly, it
 won't do anything, but you *could* do it...
 
 ## Hosting your own instance
-This bot is built on [discord.js](https://discord.js.org/#/) v13, so you'll need
-Node.js 16.6.0 (or newer) installed. You will also need your own Discord bot
-account.
-
-If you're upgrading from an older Discord.js v12 version of the bot, the Node.js
-16.6.0 requirement might be problematic. you might consider using something like
-https://github.com/nvm-sh/nvm to make the transition easier.
-
-The `resources` directory has a service file that can be used with Linux distros
-with systemd. If you're installing this on some other operating system, you're
-on your own.
-
-### Running as a service
-The provided service file expects to find the bot code at
-`/srv/discord/ReactionRoleBot/`, and will want to create the sqlite database at
-`/srv/discord/rolebot.sqlite`. The easiest way to do this is to create a
-`/srv/discord` directory, and `chown` it so it belongs to the user running the
-bot.
-
-The following will prepare the bot to run. Run this from `/srv/discord`:
-```
-git clone https://github.com/Mimickal/ReactionRoleBot.git
-cd ReactionRoleBot
-npm install
-NODE_ENV=prod npm run knex migrate:latest
-```
-
-Create a file `/etc/discord/ReactionRoleBot/config.json` and paste in the
-following (obviously fill in the blanks with your bot's info):
-```json
-{
-  "token": "<your token here>",
-  "app_id": "<your bot application ID here>"
-}
-```
-
-Install `reactionrolebot.service` into `/etc/systemd/system/`.
-
-Now you should be able to run `systemctl restart reactionrolebot.service` to
-start your bot.
-
-### Running locally (in dev-mode)
-Run this wherever you want:
-```
-git clone https://github.com/Mimickal/ReactionRoleBot.git
-cd ReactionRoleBot
-npm install
-npm run knex migrate:latest
-```
-
-Create a file containing your bot token in plain text.
-
-Run this to start the bot: `node main.js path/to/your/config`
+[See the guide here](docs/hosting.md).
+
+If you are upgrading from version 1.x, [see the migration guide](
+docs/migrate.md).
 
 ## License
 Copyright 2020 [Mimickal](https://github.com/Mimickal)

docs/hosting.md

@@ -0,0 +1,74 @@
+# Hosting your own instance
+
+This bot is built on [discord.js](https://discord.js.org/#/) v13, so you'll need
+Node.js 16.6.0 (or newer) installed. You will also need your own Discord bot
+account. If your platform does not have Node.js 16.6.0, consider using something
+like https://github.com/nvm-sh/nvm.
+
+This guide assumes you're hosting on a Linux distro with `systemd`. The bot will
+work on other platforms, but you're on your own figuring that out.
+
+## Running as a user (in dev-mode)
+Quick and easy. Also (mostly) platform-independent!
+
+Create a file `config.json` and paste in the following (obviously fill in the
+blanks with your bot's info):
+```json
+{
+  "token": "<your token here>",
+  "app_id": "<your bot application ID here>"
+}
+```
+
+Install dependencies, register Discord slash commands, and set up the database
+for your bot:
+```
+git clone https://github.com/Mimickal/ReactionRoleBot.git
+cd ReactionRoleBot
+npm ci
+npm run register path/to/your/config.json
+npm run knex migrate:latest
+```
+
+Start the bot:
+```
+npm start path/to/your/config.json
+```
+
+## Running as a service
+A little more effort to set up, but better for long-term use.
+
+The provided service file expects to find the bot code at
+`/srv/discord/ReactionRoleBot/`, and will want to create the sqlite database at
+`/srv/discord/rolebot.sqlite`. The easiest way to do this is to create a
+`/srv/discord` directory, and `chown` it so it belongs to the user running the
+bot.
+
+Create a file `/etc/discord/ReactionRoleBot/config.json` and paste in the
+following (obviously fill in the blanks with your bot's info):
+```json
+{
+  "token": "<your token here>",
+  "app_id": "<your bot application ID here>"
+}
+```
+
+The following will prepare the bot to run by installing dependencies,
+registering slash commands for your Discord bot account, and setting up the
+bot's database. Run this from `/srv/discord`:
+```
+git clone https://github.com/Mimickal/ReactionRoleBot.git
+cd ReactionRoleBot
+npm ci
+npm run register /etc/discord/ReactionRoleBot/config.json
+NODE_ENV=prod npm run knex migrate:latest
+```
+
+Add your user to `reactionrolebot.service`, then install it into
+`/etc/systemd/system/` (just copy the file into that directory). This service
+file depends on the above directories, so if you want to change them, you'll
+also need to edit those fields. If you are using `nvm`, you may need to tweak
+the service file a bit (see comments in provided service file).
+
+Now you should be able to run `systemctl restart reactionrolebot.service` to
+start your bot.

docs/migrate.md

@@ -0,0 +1,31 @@
+# Migrating your instance to 2.x
+
+This guide is for people who were running their own 1.x instance of the bot.
+
+This bot now runs Discord.js v13, which requires Node.js 16.6.0. On some
+platforms (older distros, cloud hosting, etc...) this may be problematic.
+Something like https://github.com/nvm-sh/nvm can make the transition easier.
+
+1. Get the updated bot code (either `git pull origin master` if you cloned with
+   git (which you should) or download `master` as a zip).
+1. Make a copy of your old database
+   - **Running as a service**: probably `/srv/discord/rolebot.sqlite3`
+   - **Running in dev-mode**: `dev.sqlite3`
+1. Replace bot token file with a `config.json` file that looks like this:
+   ```json
+   {
+     "token": "<your token here>",
+     "app_id": "<your bot application ID here>"
+   }
+   ```
+   - **Running as a service**: Replace `/etc/discord/ReactionRoleBot/token`
+     with `/etc/discord/ReactionRoleBot/config.json`
+   - **Running in dev-mode**: Some local token file
+1. Install updated dependencies: `npm ci`
+1. Register slash commands: `npm run register path/to/your/config.json`
+1. Update your database: `npm run knex migrate:latest`
+1. Start the bot
+   - **Running as a service**: update `reactionrolebot.service` ([see reference
+   implementation](../resources/reactionrolebot.service)). Restart service
+   `systemctl restart reactionrolebot.service`.
+   - **Running in dev-mode**: `npm start path/to/your/config.json`

package.json

@@ -14,6 +14,7 @@
     "winston": "^3.3.3"
   },
   "scripts": {
+    "start": "node .",
     "dev": "node . dev-config.json",
     "knex": "npx knex --knexfile src/knexfile.js",
     "register": "node src/register.js",

resources/post-receive

@@ -11,7 +11,7 @@ NODE_ENV="prod"
 mkdir -p $TEMP
 /usr/bin/env git --work-tree=$TEMP --git-dir=$REPO checkout -f
 cd $TEMP
-/usr/bin/env npm install
+/usr/bin/env npm ci
 NODE_ENV=$NODE_ENV /usr/bin/env npm run knex migrate:latest
 
 # Now install the code

resources/reactionrolebot.service

@@ -11,7 +11,10 @@ Restart=on-failure
 RestartSec=10
 User=<user>
 Environment="NODE_ENV=prod"
-ExecStart=/usr/bin/env nodejs /srv/discord/ReactionRoleBot/main.js
+ExecStart=/usr/bin/env npm start --prefix /srv/discord/ReactionRoleBot/
+# If using nvm, you may need to do something like this instead:
+#Environment="NODE_ENV=prod" "NODE_VERSION=<version>"
+#ExecStart=<path to nvm-exec> npm start --prefix /srv/discord/ReactionRoleBot
 
 [Install]
 WantedBy=multi-user.target