Self-host Klaxon

ADMIN_EMAILS, SENDGRID_USERNAME, SENDGRID_PASSWORD, MAILER_FROM_ADDRESS, APPROVED_USER_DOMAINS (optional)

It will take you to a page to configure your new app in Heroku's dashboard. First, give your app a name in the first box. While this is technically optional, this will also double as the URL for your Klaxon instance, so think carefully about it for a moment. Try maybe an abbreviation for your newsroom with a hyphen and the word klaxon, like "wp-klaxon" or "sl-klaxon". This will become a URL as https://sl-klaxon.herokuapp.com/

Scroll down to the admin_emails field and add a comma-separated list of email addresses of your newsroom's Klaxon administrators. These administrators will be able to create accounts for users in your organization as well as configure the Slack and Discord integrations.

Click the big purple "Deploy" button. If you haven't given Heroku your credit card yet it will ask you for your information now. After that, give Heroku a few minutes for the app to build.

When you see this message:

...you're almost done.

Click on the button that says "Manage App". This takes you behind the scenes of the various components powering your Klaxon. On this resources screen, click on the link for "Heroku Scheduler," which will take you a new screen where you must add the very important piece. The scheduler is what runs every 10 minutes to actually check all the sites and pages you're watching. Click the long, purple "Add new job" button. In the text box next to the dollar sign, type the words "rake check:all" with the colon and without the quotes. Under "Frequency" change it from "Daily" to "Every 10 minutes". Click the purple "Save" button and your scheduler item should look like this:

Sendgrid now requires additional steps to confirm that you are not a spammer. Your new Sendgrid account is created in a "suspended" state. To get it unsuspended you have to contact Sendgrid support. You can do this by clicking the Sendgrid logo on the Resources tab.

If clicking on the logo takes you to an error page do not worry. This has been known to happen as Sendgrid's system has undergone redesigns. Instead go to Sendgrid's page to ask for support. Be sure to use the same email address associated with your Heroku account and provide the url of your Klaxon instance. When they ask for "Business impact," choose "P3 General - You have a question about Sendgrid or how to use its products".

This step is a nuisance, but important. You will not be able to get an email to log in to Klaxon until you are cleared by Sendgrid. This usually happens pretty quickly.

Unfortunately you are not yet done configuring Sendgrid. There are more steps to set up your account.

1. From the Heroku application page, click on the "Resources" tab, and click the link to the Sendgrid plugin, this will take you to the Sendgrid website.
2. In the left hand column choose Settings -> API Keys. Click the blue "Create an API Key" button in the top right corner.
3. In the form that appears fill in the API key name (doesn't matter what you name it), make sure the "Full Access" option is selected, and click "Create & View".
4. Click the API key to copy it to your clipboard. Then navigate back to Heroku.
5. In the "Settings" tab of your Heroku app click the "Reveal Config Vars" button.
6. Change the SENDGRID_PASSWORD variable to the API Key by clicking the pencil icon next to it, pasting it in, and saving it.
7. Change the SENDGRID_USERNAME variable to the string "apikey" in the same manner.

Next you'll need to set up a "Verified Sender" account in Sendgrid using an email address that you have access to. In your Sendgrid dashboard, click "Sender Authentication" and choose "Verify Single Sender".

When you've completed this process in Sendgrid, you'll need to set the MAILER_FROM_ADDRESS variable as you did above to your verified sender email address.

Finally, now, you should be done setting up your Sendgrid account.

At the top of the scheduler page, click the link that is the name of your app ("sl-klaxon"). This will take you to back to Klaxon's dashboard. Then click the button in the upper right that says "Open app," and this should take you to your Klaxon's login screen on the web.

Type the admin email address that you gave the Heroku dashboard earlier into the text box and hit the "Login" button. You'll then be redirected to a page that says an email has been sent to you. Check your inbox. This may take a minute or two to arrive.

In the email, click the "Go to Dashboard" button. You're now authenticated in the system and can access your Klaxon.

DATABASE_URL, SECRET_KEY_BASE, ADMIN_EMAILS, SENDGRID_USERNAME, SENDGRID_PASSWORD, MAILER_FROM_ADDRESS, APPROVED_USER_DOMAINS (optional)

First, ensure that you have the libpq-dev package, ruby 2.3.4 and the bundler gem installed:

• sudo apt-get install libpq-dev

• gem install bundler (required both locally and on remote server)

• rvm install ruby-2.3.4 (This assumes you have installed RVM.)

Deploy with capitrano or caphub.

Properly creating a capistrano deployment task is beyond the scope of these instructions. But additional information can be found below:

• https://github.com/capistrano/capistrano

• https://github.com/railsware/caphub

In our our own setup, we use caphub to deploy multiple applications from a single capistrano environment. The commands below are shown as an example of how we deploy the code to our server.

We deploy the code to the production environment.

• bundle exec cap klaxon:production deploy:setup
• bundle exec cap klaxon:production deploy

ON THE SERVER run the following commands:

• bundle exec rake db:create RAILS_ENV=production (This creates your database using the config/database.yml file. Only do this on initial deploy)

• bundle exec rake db:migrate RAILS_ENV=production

Deploy and set up your vhosts

We use nginx and have built capistrano tasks to build, deploy and enable reverse-proxy vhosts on our servers. You can perform these steps manually on your server. But we've included the step in capistrano commands that we run from our local Macs.

• bundle exec cap klaxon:production web:deploy_vhosts
• bundle exec cap klaxon:production web:enable

For an example of what a properly configured nginx vhosts might look like, please see the file klaxon-gninx-vhost-example.txt.

Set up default admin users

This step is important because without it, you'll be unable to login to your application. The list of emails are just a list of comma separated values.

After modifying the command below to use your own email addresses, please run (on the server):

• bundle exec rake users:create_admin RAILS_ENV=production ADMIN_EMAILS=FIRST_EMAIL@YOURDOMAIN.org,SECOND_EMAIL@YOURDOMAIN.org,THIRD_EMAIL@YOURDOMAIN.org