Skip to main content

Docusaurus Storage Optimization Report

Scope​

  • Site: brain.id86.net
  • Host path: /opt/docker-data/apps/docusaurus/site
  • Runtime: Docker container docusaurus (node:lts)
  • Objective: identify storage bloat root cause, apply safe remediation, and automate prevention.

Executive Summary​

The storage bloat was caused primarily by persistent frontend build caches, not by the static site output itself.

  • node_modules was large mostly because cache directories lived inside it.
  • Final site output (build) remained moderate in size.
  • Safe cleanup of cache directories reclaimed significant disk space with no content loss.
  • A weekly cron job now removes only safe cache paths to prevent recurrence.

Findings (Measured)​

Initial state​

/opt/docker-data/apps/docusaurus/site/node_modules            ~4.5G
/opt/docker-data/apps/docusaurus/site/node_modules/.cache     ~3.9G
/opt/docker-data/apps/docusaurus/site/build                   ~202M

Largest cache contributors:

node_modules/.cache/webpack                                   ~3.4G
  - client-development-en                                     ~692M
  - client-production-en                                      ~1.2G
  - server-production-en                                      ~1.5G

node_modules/.cache/rspack                                    ~572M

Build performance check​

Successful build run inside container:

sudo docker exec docusaurus sh -lc "cd /app && npm run build"

Observed compilation timings:

  • Server compile: 23.17s
  • Client compile: 25.53s
  • Estimated wall time (start to finish): ~28-35s

Root Cause​

  1. Persistent cache storage: Docker bind mount (./site:/app) keeps Webpack/Rspack caches on host disk across restarts.
  2. Multiple cache targets: separate cache artifacts for client/server and dev/prod profiles.
  3. Modern JS toolchain footprint: Docusaurus + search plugin + mermaid + bundler transforms produce large cache graphs.
  4. No scheduled cleanup previously: cache growth accumulated over time.

Actions Taken​

1) Build blocker removed​

A non-doc file was moved out of docs tree:

FROM: /opt/docker-data/apps/docusaurus/site/docs/server/linux-server/11-automation-task-execution/rezriz.code-workspace
TO:   /opt/docker-data/apps/docusaurus/backups/rezriz.code-workspace.2026-03-03

2) Safe storage cleanup executed​

Removed only safe cache paths:

sudo rm -rf /opt/docker-data/apps/docusaurus/site/node_modules/.cache/webpack
sudo rm -rf /opt/docker-data/apps/docusaurus/site/node_modules/.cache/rspack

3) Recurrence prevention automated​

Created script:

/opt/docker-data/apps/docusaurus/backup-scripts/cleanup-docusaurus-cache-weekly.sh

Script behavior:

  • validates site path exists
  • logs timestamp + before/after cache size
  • removes only Webpack/Rspack cache folders
  • skips safely if folders do not exist

Cron schedule added:

17 3 * * 0 /opt/docker-data/apps/docusaurus/backup-scripts/cleanup-docusaurus-cache-weekly.sh >> /home/rezriz/logs/docusaurus-cache-cleanup.log 2>&1

Results​

After cleanup:

/opt/docker-data/apps/docusaurus/site/node_modules            ~598M
/opt/docker-data/apps/docusaurus/site/build                   ~202M

Approximate reclaimed storage from Docusaurus cache cleanup:

  • ~3.9G

Risk and Safety Notes​

  • Cleanup targets are rebuildable caches, not source content.
  • No docs, database data, backups, or final static output were deleted.
  • First build after cleanup may be slightly slower due to cold cache; subsequent usage remains normal.

Operations Runbook​

Manual safe cleanup (on demand)​

sudo rm -rf /opt/docker-data/apps/docusaurus/site/node_modules/.cache/webpack \
            /opt/docker-data/apps/docusaurus/site/node_modules/.cache/rspack

Quick verification​

sudo du -sh /opt/docker-data/apps/docusaurus/site/node_modules \
           /opt/docker-data/apps/docusaurus/site/build

sudo docker exec docusaurus sh -lc "cd /app && npm run build"

Weekly job log check​

tail -n 50 /home/rezriz/logs/docusaurus-cache-cleanup.log

Recommendation​

  • Keep a single Docusaurus site for now.
  • Continue weekly cache cleanup automation.
  • Re-evaluate architecture split only if build time and search performance degrade substantially over sustained growth.