The Ops Community ⚙️: Natalie Lunbeck

How to Containerize Your Docusaurus (And Why You Should)

Natalie Lunbeck — Thu, 25 Jan 2024 19:28:48 +0000

This post was originally published on the Shipyard Blog

Containerizing your project’s documentation might be one of the easiest ways you can remove friction from iterating. Your docs are also probably one of the easiest things you can containerize. Here’s how you can get your docs up and running with Docker Compose in just a few minutes.

Why should I containerize my docs?

Simply put, containerizing your docs lets you hit the ground running when writing documentation.

Here are a few QoL improvements that come with doing this:

No need to install/update/manage dependencies
Work with the same development environment across machines
Start developing with just a single command

In short, it’s just easier. You don’t have to think about building and running the dev server, you can just open your terminal and your IDE, then start writing. When writing docs, you’re likely iterating often and adding small chunks at a time, so it makes sense to optimize your local dev environment to spin up as efficiently as possible.

Containerizing your Docusaurus build

At Shipyard, we’re big fans of Docusaurus. We’ve been using it to write our public documentation for three years. We’ve also been using Docker Compose for local docs development just as long. A lesson we've learned is that sometimes the best tools are the ones we're already using. We were using Docker Compose for everything else, why not extend it to our docs?

Writing the Dockerfile

Since Docusaurus is Node-based, the Dockerfile is pretty standard. You might need to swap in your docs’ custom run commands.

FROM node:16-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

CMD ["npm", "start"]

This Dockerfile Explained

If you’re newer to Docker, here’s a line-by-line rundown of what this Dockerfile is doing:

Start with a Node base image
Create and set the working directory within the container
Copy the Node dependencies to the working directory
Install dependencies within container
Copy the rest of the repo’s contents to the working directory
Run the Node project’s start command

Setting the host

In order to make the application accessible from outside the container (e.g. from your web browser), you’ll want to set the --host option to 0.0.0.0.

This can be done from your package.json:

 "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start --host 0.0.0.0",

Or in your Dockerfile as an argument to your project’s start command:

CMD ["npm", "start", “--host”, “0.0.0.0”]

Writing the Docker Compose file

Now that we have the Dockerfile, we can write a single-service Compose file to leverage it. Here, we’ll specify any Docker config options (so we don’t need to remember them for complex docker build and docker run commands).

version: '3'

services:
  docusaurus:
    build:
      context: .
    ports:
      - '3000:3000'
    volumes:
      - './docs:/app/docs'
      - './src:/app/src'
      - './static:/app/static'
      - './docusaurus.config.js:/app/docusaurus.config.js'
      - './sidebars.js:/app/sidebars.js'

Because we’re optimizing this Compose file for local development, we’ll want to define bind mounts from any files and directories that we plan to edit. This way, any local changes will be reflected in the Docker container.

In this example, I have a few bind mounts defined under the volumes option. The syntax for this involves specifying the local path (relative to the build context), followed by a colon, then followed by the corresponding location in the container.

Bonus: Writing the .dockerignore

Docker images tend to run pretty large, so writing a .dockerignore can help slim them down by weeding out any files irrelevant to your Docker build.

To exclude any Markdown files in the root directory (e.g. your README.md and LICENSE.md, but not your actual Markdown doc pages), you can use this glob pattern in the .dockerignore:

/*.md

Your Docker build also doesn’t need to include the Dockerfile or the Compose file. These glob patterns will match most naming conventions for those:

*compose*
*Dockerfile*

You can also exclude node_modules (likely the biggest bloat culprit):

node_modules

Docs that work right out of the box

Now that you’ve containerized your Docusaurus docs, you can spin them up locally with docker compose up and start editing.

Thanks for reading!

If you enjoyed this Docker Compose tutorial, check out this post I made a few months ago on how to write a Compose file for a Wordle clone.

Why won't Docker install on my older Mac? Your macOS is probably too old

Natalie Lunbeck — Tue, 16 Jan 2024 21:15:41 +0000

This post was originally published on the Shipyard blog

A few days ago, I tried manually upgrading Docker Desktop on my personal 2015 MacBook Pro (running macOS Mojave 10.14.6). I went to Docker’s website and downloaded the newest image for my Intel-based Mac, only to find an unhelpful and misleading message from macOS:

Warning: Docker DMG file is corrupt.

Of course I went back to make sure I didn't click on the ARM version and downloaded a brand new copy, but again, the “corrupt image” warning. A few panicked minutes of thinking I got MITM'd later, I realized it wasn't a corrupt image at all: my macOS was too old to install the latest and greatest version of Docker.

According to Docker's macOS System Requirements:

Docker supports Docker Desktop on the most recent versions of macOS. 
That is, the current release of macOS and the previous two releases. 
As new major versions of macOS are made generally available, 
Docker stops supporting the oldest version and supports the newest 
version of macOS (in addition to the previous two releases).

The current version of Docker (4.26.0 as of January 2024) supports macOS Sonoma, Ventura, and Monterey. Mac users on Big Sur or an earlier OS will need to find an alternate solution.

I did some digging and found a few different approaches to getting Docker working on my Mac.

Option 1 (Obvious and scary): Upgrade macOS

It’s important to consider whether your Docker use case warrants an entire OS upgrade. You might already be avoiding an upgrade for a myriad of reasons. For a few key reasons to think twice before upgrading, check out this article from How-To Geek. Remember, you have other software that might break because of the upgrade, and OS upgrades have been known to slow down older hardware.

These upgrades can take a good chunk of time and are a pretty big commitment if you are just trying to test out a new feature in Compose…

Before upgrading, you might also want to check that your Mac hardware can run Docker’s required macOS version. This article from Macworld lists the Macs supported by each macOS release since OS X Mountain Lion.

Option 2 (Quick and easy): Find an old supported version of Docker

Many users, myself included, choose to stay on an older version of macOS on older hardware for performance and/or compatibility reasons. Users with machines that are over four or five years old have no option to upgrade to the latest macOS version (by legitimate means, at least).

If you’d prefer to keep your current OS, you can simply install an older version of Docker. These aren’t listed alongside current downloads on the Docker website, but the links are still live.

This (unofficial) Gist includes the download links to previous Docker versions, expanded by this recent comment. For versions 4.18.0 and up, you can grab a download link directly from the release notes page.

When choosing a previous Docker version, cross reference with the release notes. This way, you can find a version that works with your current OS and includes the features and bug fixes that you need for your use case.

Option 3 (Fun and complex): Running a Linux VM

If you’re unable to upgrade macOS and need the latest version of Docker, there’s a last resort: you can run a Linux distro in a VM (via VirtualBox or QEMB) and install Docker there. This will allow you to use the same version of Docker on your Mac (Docker on macOS runs in a LinuxKit VM), however it’ll be much less optimized and will require more config since you won’t be running it natively.

Docker supports Ubuntu, Debian, and Fedora-based distros.

More Docker for your Mac

The swap from Intel to Apple Silicon added complexity to third-party software releases, and three years in, we’re seeing shorter support lifespans for Intel Macs. If an OS upgrade isn’t in the cards for you, it’s nice to know that Docker still hosts its older DMGs and that there’s support for mainstream Linux distros.

Want to automate your Docker builds in your CI? Check out this post I did a few months back on using GitHub Actions to build and push Docker images to a container registry.