Skip to content

Deployment troubleshooting

Jump to bottom
August edited this page Nov 6, 2025 · 5 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

Rerun GitHub Action

The GitHub Action that runs when a PR is merged in the signalwire-docs-internal repo is a common point of failure.

To re-run it, open the Actions tab, click on the one corresponding to the changes that aren't showing up in prod, and re-run the whole thing.

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

Install Docker

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

  • Install the Docker Desktop GUI application and open the application.
  • Install Docker via Homebrew with brew install docker
    • This installs the CLI version of Docker, which does not come with a VM. (brew install --cask docker-desktop if you want Docker Desktop instead.)
    • Install the Colima VM with brew install colima
    • Start the VM with colima start -m 4. This allocates 4gb of RAM for Colima, instead of the default of 2. Stop Colima with colima stop and restart with more memory as needed.

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 allocate more memory:

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

Seen in context here:

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

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

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 8gb (8192mb) of memory to Node. Ensure you have sufficient available system memory before proceeding.

Clone this wiki locally