or: _ebooks Leaves the Nest
THIS TUTORIAL IS DEPRECATED. FOR ENTERTAINMENT PURPOSES ONLY.
Heroku's free tier no longer suports long-running processes.
About a digital century ago, I wrote up some instructions for getting your own _ebooks bot up and running. A not insignificant number of people used those instructions to bring weird digital versions of themselves or their friends into the world. That made me very happy, but there were some problems.
First of all, I had people put secret credentials into their code as plain text, and their robots only had a presence on Twitter if the creator's computer was running and online; these issues will be addressed here, belatedly.
The steps below should take from 45-90 minutes, assuming you've already done everything in Step 0.
0. Read The Original Post
Instructions below assume you followed the original How To Make an _ebooks Bot and your bot is running smoothly. Specifically, it assumes you already have the following software installed:
ruby(version 1.9.3 or greater)rubydevkit (orruby-develpackage)twitter_ebooksruby gem (version 2.2.6)
It also assumes you have the Twitter API Consumer Key/Secret, and OAuth Access Token/Secret from a Twitter app that has Read, Write, and Access Direct Messages privileges, and that you have a my_ebooks folder containing run.rb, bots.rb, Procfile, and model/my_ebooks.model.
All good? Let's get started!
1. Download Some Files
There are three (small) files I've made to save you some copying and pasting. All of these should go in your my_ebooks directory:
.env
.gitignore
Gemfile
2. Hide the Keys
Right now, your bots.rb file would let anyone impersonate your bot on Twitter if they saw it. You don't want your robot turning into one of those bad robots, and if you want to make more weird internet things, or share cool bot customizations with friends and strangers, it's important to protect these secrets as a rule.
First, install a handy gem called dotenv by running:
gem install dotenv
Next, Open up your bots.rb and cut/paste the secrets into your .env file.
While you have bots.rb open, tell the program how and where to find the keys later by adding a couple lines before your secrets, and changing what comes after the equals signs:
require 'dotenv'
Dotenv.load(".env")
CONSUMER_KEY = ENV['EBOOKS_CONSUMER_KEY']
CONSUMER_SECRET = ENV['EBOOKS_CONSUMER_SECRET']
OAUTH_TOKEN = ENV['EBOOKS_OAUTH_TOKEN']
OAUTH_TOKEN_SECRET = ENV['EBOOKS_OAUTH_TOKEN_SECRET']
Now your run.rb should work just like it did before, but you'll feel the subtle warmth of increased security, and you can safely share your bots.rb file with others!
3. Heroku, Sheroku, Zheroku, We All Roku
Having your robot friend on your computer has been fun, but as time passes it yearns to move out and spread its wings. There are a number of services that provide a place for robots to live (for a fee) but here we'll be focusing on Heroku, which has a free service tier for small programs like this one.
After creating an account at Heroku, you can use their basic setup page instructions to install the Heroku Toolbelt on your computer, and ensure you can log in. If you're prompted to create a public key, you want to say Y to that.
All working? Go create a new app in the web dashboard and name it something like my-ebooks (you can't use underscores here!)
4. Bundling Up
Before you send your robot out into the world, you'll want to make sure that it has all the comforts of home wherever it ends up; specifically the twitter_ebooks and dotenv gems.
You should have the Gemfile in your my_ebooks directory from earlier, and running these two commands will make a much more detailed version of that list called Gemfile.lock:
gem install bundler
bundle install
This may take a couple minutes, so don't get nervous!
5. Sharing, Without Oversharing
You'll have to let your computer know which files to send along to the Heroku server using git, a super-complicated version control system that is complete overkill for what you're doing! But it's what Heroku demands of us, and your use of it will be super simple.
The .gitignore file from earlier will prevent you from uploading your secret .env file and your Twitter archive file publicly.
You can tell git to track files in this directory and to add everything except the ones we ignore above this way:
git init
git add .
Run git status -s to see a list of files that will be sent out when you deploy the robot. It should look like this:
A .gitignore
A Gemfile
A Gemfile.lock
A Procfile
A bots.rb
A model/.gitignore
A model/my_ebooks.model
A run.rb
[HELP: I HAVE OTHER FILES LISTED!]
If you see any files listed that shouldn't be shared, like .env or my-secret-diary.txt you can remove them from the current list this time by running:
git rm --cached .env
git rm --cached my-secret.diary.txt
You'll also want to add them as new lines to the .gitignore file, and run git add .gitignore to update that list for the future.
[ALRIGHT, LOOKS GOOD!]
With only what you want to share listed, commit the list:
git commit -m "First commit"
6. Deployment
You've hidden your secrets under a rock, found a free place for your robot to live, and packed its bags. Now let's send it off!
These commands will set it up so it's ready to go when you give the green light:
heroku git:remote -a my-ebooks
git push heroku master
heroku plugins:install https://github.com/ddollar/heroku-config
heroku config:push
Now your computer knows where to put files when you say to send them to Heroku, it sends over the files we've indicated as safe to share, and using this handy plugin it sends the secrets to a separate place at Heroku.
You can see your secrets under Config Variables on the Settings page for your my-ebooks Heroku app if you want to confirm they were safely received.
[HELP! "PERMISSION DENIED (PUBLICKEY)"]
If you already use ssh, putty, git, or similar programs, you may already have a public key for identifying your computer to other servers, but Heroku may not know about it.
You'll need to send that public key over to Heroku to let them know that yes, this is you. Where your public key is stored will differ from platform to platform, but generally on Linux or OSX you can run:
heroku keys:add ~/.ssh/id_rsa.pub
or on Windows, try:
heroku keys:add %USERPROFILE%\.ssh\id_rsa.pub
7. Run, Robot, Run!
This is the good part!
Go to the Resources page for your my-ebooks Heroku app.
Click the Edit button, move the slider for Dynos to 1, and hit Save. That's it!
You can confirm the robot is running by remotely checking its output from your computer:
heroku logs -tn 5
It's so rewarding seeing them off and making it in the world on their own. Brings a tear to your eye!
Acknowledgements, &c.
Big thanks to:
@ckolderup for rightly pointing out the importance of keeping keys out of your code, even for beginners.
@hybernaut for pointing us to Brandon Keeper's dotenv gem.
David Dollar for making heroku-config, a simple and great plug-in.
@ckolderup again for suggesting the heroku-config plug-in.
@WarrenIsDead for his notes on Heroku deployment.
and a lot of other people, probably.
AND TO READERS LIKE YOU.
