Skip to content

Deployment troubleshooting

Jump to bottom
August edited this page Feb 17, 2025 · 4 revisions

Troubleshoot preview and production build issues

Sometimes, it makes sense to build and run the Docker image locally for troubleshooting purposes. If a build is failing in the preview (Netlify) or production (Github) deployment, but the issue can't be replicated in a local Docusaurus build, follow these steps:

  1. Check the Netlify and Github build logs
    • Netlify is responsible for the preview deployment, and Github workflows are responsible for the production deployment.
    • Since the docs repo is public, all Github users should have access to its build logs.
    • Netlify logs are restricted and users must be added by an administrator.
  2. Build and run the Docker image locally: see below

Build and run Docker image locally on a Unix (Mac/Linux) system

Install Docker

You'll need Docker to do this. There are two recommended installation methods:

  • Install the GUI application (Docker Desktop) and open the application.
    • Users unfamiliar with Homebrew and the CLI should select this option
  • Install Docker via Homebrew with brew install docker
    • This installs the CLI version of Docker, which does not come with a VM.
    • Install the Colima VM with brew install colima
    • Start the VM with colima start

Build

Build the docs from the Dockerfile included in the repository using the following commands.

Run the following commands sequentially:

docker build -t swdocs .
docker run -d -p 80:80 --name swdocs_run swdocs
open http://localhost # for mac

Or run the this equivalent, single command:

docker build -t swdocs . && docker run -d -p 80:80 --name swdocs_run swdocs && open http://localhost

Allocate more memory (optional)

If the build fails due to insufficient memory, temporarily modify the Dockerfile at the root of the directory to add the following line:

ENV NODE_OPTIONS="--max-old-space-size=4096"

Seen in context here:

FROM node:20 AS builder
WORKDIR /app
COPY . /app

-
+ ENV NODE_OPTIONS="--max-old-space-size=4096"

RUN npm run install-ci && npm run build

FROM nginx
COPY provisioning/nginx/nginx.conf /etc/nginx/nginx.conf
COPY provisioning/nginx/redirects.map /etc/nginx/redirects.map
COPY --from=builder /app/build/ /usr/share/nginx/html

EXPOSE 80

Tip

This allocates 4gb (4096mb) of memory to Node. Ensure you have sufficient available system memory before proceeding.

Clone this wiki locally