Skip to content

Heroku and the Sensu docs

Jump to bottom
Hillary Fraley edited this page Nov 23, 2022 · 1 revision

The Sensu docs site is published with Heroku. The sensu-docs pipeline includes review apps for every /sensu-docs pull request (PR), a sensu-docs-stage staging app, and the sensu-docs-site production app.

Review apps

The sensu-docs pipeline is set up to automatically create a review app for every PR in the /sensu-docs GitHub repository. Access the review app from the GitHub PR with the View Deployment button or by logging into Heroku.

Heroku takes a few minutes to build the review app. Until the app is available, you will see a message in the GitHub PR similar to $github_user requested a deployment to sensu-docs-branch-name-eqfhc5cwz5 2 minutes ago Pending.

If you push a new commit to an existing GitHub PR, Heroku will automatically rebuild the review app and update the link in the PR.

Review apps create a preview of the docs site as it will appear with the PR changes merged. They simplify PR reviews and allow you to confirm formatting before publishing any changes.

Manually deploy a review app

Review apps expire after 5 days. To redeploy a review app for a PR, use Heroku:

  1. Create a pull request for the site updates you want to test in the sensu-docs repo.
  2. Log in to the Sensu Heroku apps.
  3. Click the sensu-docs pipeline.
  4. Find the PR in the left-most column, REVIEW APPS.
  5. Click the Create a review app button for the PR.

Wait for Heroku to run the deploy process. When it is finished, the Open app button will appear. Click the Open app button to view the review app for the PR.

The review app link will also be reactivated on the GitHub PR.

Automatic publishing

When a /sensu-docs PR is merged to main, Heroku automatically publishes the changes contained in that PR to the public docs site, https://docs.sensu.io. View build progress in the /sensu-docs-site app in Heroku.

Install the heroku cli

The Heroku CLI provides helpful tooling to manage Heroku applications. See Heroku's DevCenter documentation for installation instructions.

Add Heroku buildpacks

To deploy to Heroku, you need to configure the app with buildpacks. The buildpack configuration is persistent and shouldn't need to be modified on a regular basis.

We use a combination of two buildpacks:

To add the buildpacks, run:

heroku buildpacks:add --index 1 heroku/nodejs
heroku buildpacks:add --index 2 https://github.com/sensu/heroku-buildpack-static.git

Publish to Heroku manually

You may need to manually publish updates to https://docs.sensu.io in case of issues with Heroku's automatic publishing feature. In this case, you can use git to push your changes to the heroku remote's main branch.

NOTE: You must install the Heroku CLI before following these steps.

  1. Merge all PRs whose changes you want to publish.

  2. Clone the sensu-docs repo:

git clone https://github.com/sensu/sensu-docs.git && cd sensu-docs
  1. Add the heroku remote to your local copy of the repo:
heroku git:remote -a sensu-docs-site

You may be prompted to log in to Heroku through the browser.

  1. Push the local copy of the repo to the heroku remote:
git push heroku main

Heroku will begin building the production app to publish the changes to https://docs.sensu.io.

Manually deploy to the sensu-docs-stage app

To test changes to the sensu-docs site before publishing, use Heroku to deploy it to https://docs-staging.sensu.io.

  1. Create a pull request for the site updates you want to test in the sensu-docs repo.
  2. Log in to the Sensu Heroku apps.
  3. Click sensu-docs.
  4. Click sensu-docs-stage.
  5. Select the Deploy tab.
  6. Scroll down to the Manual deploy section. In the drop-down menu, select the /sensu-docs repo branch that includes the PR you want to test.
  7. Click Deploy Branch.

The staging site for the docs is available at https://docs-staging.sensu.io. Deploying to staging is a manual, as-needed process for complex PR reviews and site functionality testing.

Heroku slug size

During app deployment, Heroku compiles a slug, essentially a compressed and optimized copy of the app.

Heroku enforces slug size limits (300 MB soft and 500 MG hard). When your slug size exceeds 300 MB, you will see the following message in the Heroku deployment log:

Warning: Your slug size (308 MB) exceeds our soft limit (300 MB) which may affect boot time.

We are not near the 500-MB hard limit right now, but we will approach it as we add docs (especially when the web UI diverges among Sensu versions).

To get a list of everything the Heroku slug includes, run:

heroku run bash -a sensu-docs-site

and then run:

du -hs *
Clone this wiki locally