Skip to content

Latest commit

 

History

History
182 lines (114 loc) · 7.62 KB

CONTRIBUTING.md

File metadata and controls

182 lines (114 loc) · 7.62 KB
Raw

SRCBot Installation, Development, and Contribution Guide

Thank you for contributing to this project. All contributions are welcome. But for the sake of sanity, please follow the guidelines to contribute to SRCBot.

Requirements

SRCBot requires a few things to get going:

  1. Git and GitHub account
  2. A recent Node.js LTS version, v16.6.1 (Gallium) and above
  3. MongoDB 4.0 and above
  4. Configure environment variables for the application
  5. A Discord account for Discord bot registration

On the server or development workstation, Node.js, and MongoDB must be installed and correctly working. Otherwise, these instructions may fail.

See below on how to contribute using branches and pull requests.

Optional Requirements

  • An IDE or code editor is highly recommended, preferably with Node.js integration and debugger
  • GitHub Desktop can make working with GitHub a lot easier on Windows or Mac platforms
  • A Bugsnag account and API token if you want crash reporting and analysis

Install and configure servers

Install node.js and npm

Download the latest stable version of Node.js for your platform, and let it install. After installation, restart your terminal or PowerShell window to ensure that Node.js is now on the default path and check that both these commands work:

    foo@bar:~$ node -v
    v16.6.1
    foo@bar:~$ npm -v
    7.20.3

Update npm:

    foo@bar:~$ npm update

Install and Configure MongoDB

  • Install MongoDB, and use the default port 27017
  • Enabling access control is essential for production environments and optional for development environments.
  • Create a database in the MongoDB instance, srcbot containing a two collections called guilds and src

Obtain source code and install dependencies

Building SRCBot is relatively straightforward if taken step by step. Being a more extensive app split into five parts, there's a bit more work than a typical demo or a smaller application.

Fork and then clone the SRCBot repo

    foo@bar:~$ git clone [email protected]:[your-username]/srcbot.git

Install dependencies

Let's first get all the dependencies needed to build and run the underlying servers that run SRCBot installed.

    foo@bar:~$ npm ci

Configure source code

Create a .env file

The .env file is used by SRCBot to store configurable properties.

Create a new .env file in the project folder

src/secrets.ts

SRCBOT_PORT=3001

SRCBOT_DISCORD_TOKEN=[Discord token for bot]

SRCBOT_DB_USER=[username for srcbot db]
SRCBOT_DB_PASSWORD=[password for srcbot db]
SRCBOT_DB_HOST=mongodb://localhost:27017/srcbot

SRCBOT_BUGSNAG_TOKEN=[Bugsnag token for the Express app]
SRCBOT_BUGSNAG_ENABLED=[true/false]
  • SRCBOT_PORT the port on which the bot will run
  • SRCBOT_DISCORD_TOKEN is your Discord bot token. Read here for info
  • SRCBOT_DB_USER if you have set up MongoDB access control (mandatory in production environments), the username for the srcbot collection, or blank in development
  • SRCBOT_DB_PASSWORD if you have set up MongoDB access control (mandatory in production environments), the password for the srcbot collection, or blank in development
  • SRCBOT_DB_HOST SRCBot assumes a local MongoDB installation on port 27017. Change this if you have a cloud or different MongoDB configuration
  • SRCBOT_BUGSNAG_TOKEN is your BugSnag API key for thhe Express app. Please don't set it if SRCBOT_BUGSNAG_ENABLED is false
  • SRCBOT_BUGSNAG_ENABLED enables BugSnag if set to true, set to false otherwise

NB: Although MongoDB access control is strongly recommended, MongoDB has significant password composition limitations. We suggest a long random alphanumeric password rather than a highly complex password because many punctuation characters, including ; are not valid MongoDB passwords.

Security notice: Do not add or commit your .env file to Git.

Build SRCBot

SRCBot is a TypeScript application, and it needs to be transpiled into a Node.js-friendly code. To do this, we first install TypeScript command line tools, which the build process uses, and then build the code:

    foo@bar:~$ cd srcbot
    foo@bar:~$ tsc -v
    Version 4.5.4

If tsc works, we can go ahead and build SRCBot:

    foo@bar:~$ npm run build

Please take care of any errors you see. Sometimes, two attempts are required to get a successful build. You may need to add more node modules locally to get it to build. In development, you will likely see warnings about the production environment not being used, and that's correct. Developers can generally ignore other alerts as long as the build succeeds. Feel free to submit a pull request to fix or address these warnings.

Monitor SRCBot via BugSnag

BugSnag is an error capture and analysis platform. This is great for production, but as you have access to errors in the console, it's unnecessary for development unless you're testing BugSnag integration or fixing issues with BugSnag. If you are using the free Lite tier, it has limited events per day. If you are in development mode, consider only using BugSnag integration if you intend to work on or test BugSnag related functionality.

If you want to use BugSnag, create a BugSnag account, then an application, and obtain the application's API key.

Create an Express application for SRCBot and

  • set SRCBOT_BUGSNAG_ENABLED to true
  • set SRCBOT_BUGSNAG_TOKEN to your BugSnag application API key

Security notice: Do not add or commit your .env file to Git.

Running and debugging SRCBot

Ports

SRCBot runs on the following default ports

Prod Dev Debug
4001 3001 9229

Development Mode

If you've read this far, you're likely to be developing SRCBot or want to run your custom version. Developers can start development mode in their IDE, via the command line, or within a debugger like this:

    foo@bar:~$ cd srcbot
    foo@bar:~$ npm start

You can also use your IDE to navigate to package.json and configure, run, or debug a script target, which gives you great control over the development process.

Production Mode

To execute the project in production mode:

    foo@bar:~$ cd srcbot
    foo@bar:~$ pm2 start --env production

Review the HTTP ports above or set up a port forwarding or caching configuration to scale and serve many clients.

You will need to establish a TLS listener and, if very busy, a load balancer, such as via a cloud router or Nginx or Apache Reverse Proxy, and ensure that your URL's DNS servers point to your server and the URL you have chosen.

Contributing fixes and enhancements back to SRCBot

SRCBot is an open-source project and relies upon contributors such as yourself fixing issues or creating new features for the benefit of all. SRCBot follows standard GitHub industry practices, including that new fixes or features should be in their branch and committed via a pull request. GitHub has many excellent articles on how to install and get going with pull requests and branches.

Working on a branch

Find an issue you want to fix or enhance, and let folks know that you want to work on it. Create a new branch for your issue or enhancement:

git checkout -b [name-of-your-new-branch]

Create a pull request for your issue fix or enhancement

After you have made the necessary changes and committed them, push them to your forked repository. Then create a pull request to the master base branch.

I will review the PR and might ask to make changes before accepting them.