Setup

This is a setup guide for using rforms on Heroku. Note that it's still a work in progress. It's recommended that you read the guide in full before attempting to install this.

---

1. Create a reddit account

If you don't have a reddit account, go make one! You will need it to manage your instance.

You will also need a bot account to handle some of the backend processes. You can also use your main reddit account, but this is not recommended since the actions will all be done as this user. In order to function properly (i.e. without encountering CAPTCHAs), the bot will need karma.

2. Make a Heroku account

Heroku is a Platform as a Service (PaaS) that you will be using to host your instance of rforms. Other hosting sites aren't supported yet, as this project was designed with Heroku in mind. It's recommended that you make a new Heroku account for each instance that you create because Heroku only gives you enough free time per month to host one web app.

Create a Heroku Account

3. Click "Deploy to Heroku" in README.md

Click the button below, or on the homepage of the project (both do the same thing).

After you click it, you will be directed to Heroku to begin creating your app.

4. Enter an app name

Once the install screen loads, Heroku will ask you to enter a bunch of information. The only one that you need to worry about is "App Name (optional)". Enter a unique name here, and wait for Heroku to confirm that the name is available. This name will show up on your dashboard on Heroku, and more importantly it will be your app's subdomain. Keep this tab open in the background for now.

^{This is what the page should look like after you are done with this step}

5. Make reddit OAuth Apps

Open a new tab and login to reddit, and navigate to the "apps" section of preferences. You'll be making 2 apps here. Click the "create another app..." button to get started.

first app

This will be the OAuth app that users use to login. In the documentation, and elsewhere on rforms, this is referred to as the "frontend application". Keep in mind that they will be able to view the title, description and about url fields.

• name: put something here that represents your app. This field isn't super important.
• type: select "web app".
• description: put something here that represents your app. This field isn't super important.
• about url: put a valid URL that users can use to find out more about the form (e.g. if this form was for r/AskReddit, you may put "https://www.reddit.com/r/AskReddit. if there was a specific announcement post about the form, you would link that).
• redirect uri: must match this format exactly: https://{app_name}.herokuapp.com/callback. Replace {app_name} with what you entered as the app name on Heroku.

^{this is a screenshot of what the frontend app will look like}

click "create app"

second app

After you click create app, a frontend application will be created. The form to create an app remains with all the same data though. Simply change the type from "web app" to "script" and submit. Users won't be looking at any of the info here, so it doesn't matter that it's the same as the frontend. You may want to modify the title field, though, to include "backend" so you don't get the two apps confused. After the app is created, type in the bot's username to the "add developer" box and add it (this is important).

^{this is a screenshot of what the backend app will look like}

6. Enter config values into Heroku

Go back to the Heroku tab, and we're going to enter some data now. Below is a table containing all of the different config values, and where they come from.

^{the frontend app}

^{the backend app}

config variable	location or value
REDDIT_FRONTEND_REDIRECT_URI	redirect uri from frontend app
REDDIT_FRONTEND_CLIENT_ID	jumble of letters/numbers two lines below the name of the frontend app. see the above picture for details
REDDIT_FRONTEND_CLIENT_SECRET	the text next to "secret" from the frontend app
REDDIT_BACKEND_REDIRECT_URI	redirect uri from backend app
REDDIT_BACKEND_CLIENT_ID	jumble of letters/numbers two lines below the name of the backend app. see the above picture for details
REDDIT_BACKEND_USERNAME	the username of the bot account used for backend processes.
REDDIT_BACKEND_PASSWORD	the password of the bot account used for backend processes.
REDDIT_USER_AGENT	modify the value that's already there to include your username.

After all of these values have been entered, you can deploy it!

7. Login to your new site

If all goes well, Heroku will say that it deployed successfully. Now, navigate to https://{app_name}.herokuapp.com/mod/settings. This will redirect you to reddit to login with OAuth. If the OAuth stuff was setup successfully, reddit will look something like this:

Click allow, and continue. You have now completed setting it up. There's still one more thing that needs to be set up offsite

8. Create script

First, go to https://{app_name}.herokuapp.com/mod/api. Copy the API key from the textbox near the top of the page.

You'll need a Google account to do this. After logging in, go to https://script.google.com. This will create a new Google Apps Script. Paste the script found below, but replace "YOUR_DOMAIN_HERE" with your app's domain (e.g. https://rforms.herokuapp.com, notice that there is no slash at the end), and "API_KEY" with the API key you acquired above.

function fetch() {
  var domain = "YOUR_DOMAIN_HERE";
  var key = "API_KEY";
  UrlFetchApp.fetch(domain + "/api/process?key=" + key);
}

Save the script. Then click the button that looks like a clock in the top pane. Click the button to create a new trigger. Then, set the dropdowns to have the following values: "fetch", "Time-driven", "Minutes timer", "Every 5 minutes". This means that the script will execute every 15 minutes. If needed, this can be adjusted to be more frequent. Click save, and you're done with this.

^{It should look like this}

This script is necessary for two reasons:

• Heroku will put apps to "sleep" if no one accesses them for an hour. By running this, it makes sure that the app is always running
• In order to keep to the goal of keeping this project as free as possible, it's preferable to use an external thing like this over an addon like Heroku Cron, which requires a credit card to use.

---

You have now completed setup! Feel free to browse these pages for details on how to configure this app:

• A guide to configuring the settings
• How to define questions