Deploy Yard documentation server to Heroku

In a recent set of Rails services I built, my team wanted to quickly deploy to Heroku for testing. We also keep a YARD documentation server running and up to date for every deploy.

Turn out there is not a simple way to do this on Heroku, as you can only run one public-facing HTTP server per application.

My solution was to create a second heroku application

cd /path/to/your/repo
heroku create repo-name-doc
git remote add docs [email protected]:repo-name-doc.git

I created a Procfile.docs placed it in the root of the project, and commited it to git:

echo "web: yard server -p \$PORT" > Procfile.docs

I then wrote a simple shell script, called deploy.sh (be sure to chmod +x it).

#! /bin/sh

# copy documentation server Procfile to root
cp Procfile.docs Procfile

# add Procfile to Git
git add Procfile
git commit -m "Deploy documentation"

# deploy documentation server
git push docs $(git rev-parse --abbrev-ref HEAD):master -f

# roll back documentation commit
git reset head~1 --hard

# push main app to heroku
git push heroku $(git rev-parse --abbrev-ref HEAD):master -f

What this does is simple:

1. It copies the Procfile.docs to Procfile, as Heroku expects.
   
2. It commits this change with the message "Deploy documentation".
3. It then deploys the YARD server to the docs remote.
4. It then rolls back this commit, and pushes to the production remote, heroku.
   

To invoke this script, simply run sh deploy.sh. It runs on whatever your current branch is, so be careful!

Enjoy.