Installing on macOS (for technical writers)

Chris Rosser
6 min readJan 23, 2023

A job I recently applied to requires a candidate with experience writing docs for Backstage, Spotify’s open-source platform for creating developer portals. Backstage’s core TechDocs plugin uses MkDocs for content and YAML for configuration. While I’m very comfortable with MkDocs and YAML, my only experience with Backstage was watching introductory YouTube videos after a former colleague suggested we could use it at Specialized.

Naturally, I was intrigued, particularly as Backstage uses a documentation tool (MkDocs) I already use daily. However, being made redundant at Specialized put the kibosh on that ever becoming a possibility.

So, with time on my hands and the pressures of finding a job providing motivation, I installed it on my MacBook Pro, aiming to play with its documentation features and learn how the platform works in general.

While the Backstage docs are good, they don’t include an end-to-end process for installing on macOS, so I decided to write one for future reference, and for anyone else who might find it helpful.

In summary, the steps are:

  1. Install Homebrew
  2. Install NodeJS with Homebrew
  3. Install Postgres with Homebrew
  4. Install Backstage with npx
  5. Config Backstage to use Postgres

Homebrew is a utility for installing open-source utilities and libraries on macOS, analogous to the…



Chris Rosser

Technical writer and occasional author sharing thoughts on creativity, productivity and technology. Works at Canva.