Slate + Heroku


Damn, after searching on Google i found that Heroku already provide a one-click-button to deploy Slate on Heroku. Poor me.


I’ve been using Apiary to create API Documentation before. But unfortunately, with a free account in Apiary I can only create no more than 5 non-private API documentation project. And also can’t create any team to collaborate building API documentation.

Since that, i decided to switch from Apiary to Slate to create API documentation from now. My API documentation should be accessible by others, so i need to deploy my Slate project on a hosting. Actually, I can simply deploy my Slate project to Github and see it live on, but for future purpose (actually idk what purpose it was, hahaha) i decided to deploy Slate project on a free Heroku hosting.

I followed this official step-by-step tutorial, but in case you are too lazy to just open and read those link, you can just copy-paste-enter all of command below on your terminal.


Before starting this tutorial please make sure all of this stuff have been installed on your local computer.

  1. Git (+ Github account)
  2. Heroku CLI (+ Heroku account)
  3. Ruby 2.2.5 or newer
  4. Bundler

I do all of this steps on Ubuntu, so it might be slightly different if you running on Windows or Mac :).

Install Slate on Local Computer

1. Fork lord/slate project to your github repo, then clone to your local computer.

git clone

2. Change directory to slate directory that you just cloned on your local computer.

cd slate

3. Install all dependencies required to run slate on your local computer.

bundle install

4. Command above will add vendor folder to your slate directory. Update .gitignore to make this folder ignored everytime you push your Slate project to remote repository.

echo ‘vendor/’ >> .gitignore

5. Start server on your local.

bundle exec middleman server

If those five commands above successfuly executed, you can see your Slate page live on your browser in http://localhost:4567. At default your Slate project will run on port 4567, if you want your Slate running on different port you can just change set :port value in config.rb.

sed -i ‘s/set :port, 4567/set :port, YOUR_NEW_PORT/g’ config.rb

6. Add all change to git.

git add .gitignore config.rb or just git add .

7. Commit that change.

git commit -m “Init project and modify .gitignore (and config.rb if you also do that)”

Deploy to Heroku

Now we move to the next step, deploy your Slate to Heroku.

1. Login to your heroku account using Heroku CLI in your terminal. Type your email and password.

heroku login

2. Create heroku app. Modify YOUR_APP_NAME with anything you want your app to be named.

heroku create YOUR_APP_NAME

3. Create Procfile on your slate directory to determine what command will run by your app’s dynos on the Heroku platform. Read this to get more clear explanation.

echo “web: bundle exec middleman server -p $PORT” > Procfile

4. Add all change to git (again).

git add Procfile or just git add .

5. Commit that change.

git commit -m “Add Procfile”

6. Push your change to Heroku.

git push heroku master

7. Open your Slate on your browser.

heroku open

Voila, now you can see your Slate live on! 

Now you can start build your API Documentation using Slate. Every time you add a new change you can just do git add, git commit, and git push to your heroku repo and see your Slate updated.


3 thoughts on “Slate + Heroku

  1. How might I require authentication on the published heroku site? I want the site only available to people who work on my team.
    thank you!


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s