Skip to content
Klutch.sh Docs

Deploying a NodeBB App

Introduction

NodeBB is an open-source, real-time forum platform built on Node.js with Redis/MongoDB for persistence. Deploying NodeBB with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for uploads and logs—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your NodeBB Dockerfile (GitHub is the only supported git source)
  • Redis or MongoDB deployed as a Klutch.sh TCP app (port 8000, connecting on 6379 or 27017)
  • Domain and TLS for your forum

For onboarding, see the Quick Start.

Architecture and ports

  • NodeBB serves HTTP on internal port 4567; choose HTTP traffic.
  • Requires Redis or MongoDB backend; connect via TCP.
  • Persistent storage is recommended for uploads and logs.

Repository layout

nodebb/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t nodebb-local .
docker run -p 4567:4567 \
  -e database=redis \
  -e redis__host=localhost \
  nodebb-local

Dockerfile for NodeBB (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM nodebb/docker:latest


ENV PORT=4567 \
    URL=https://example-app.klutch.sh


EXPOSE 4567
CMD ["./nodebb", "start"]

Notes:

  • Pin the image tag (e.g., nodebb/docker:3.7.x) for stability and upgrade intentionally.
  • If you add plugins/themes, COPY them in and run ./nodebb rebuild during build.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PORT=4567
  • URL=https://example-app.klutch.sh
  • Choose a database:
    • Redis: database=redis, redis__host=<redis-host>, redis__port=6379, redis__password=<password>
    • MongoDB: database=mongo, mongo__host=<mongo-host>, mongo__port=27017, mongo__username=<user>, mongo__password=<password>, mongo__database=<db>
  • Optional: ADMIN_USER, ADMIN_EMAIL, ADMIN_PASS for initial admin creation

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=./nodebb build
  • NIXPACKS_START_CMD=./nodebb start
  • NIXPACKS_NODE_VERSION=18

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /usr/src/app/public/uploads — user uploads and assets.
  • /usr/src/app/logs — optional logs if stored on disk.

Ensure these paths are writable.

Deploy NodeBB on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 4567.
  4. Add the environment variables above, including database credentials and admin bootstrap values.
  5. Attach persistent volumes for /usr/src/app/public/uploads (and /usr/src/app/logs if used) sized for your media and logs.
  6. Deploy. Your NodeBB forum will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample API usage

Get categories (replace token with an API key):

Terminal window
curl -X GET "https://example-app.klutch.sh/api/categories" \
  -H "Authorization: Bearer <token>"

Create a topic:

Terminal window
curl -X POST "https://example-app.klutch.sh/api/v3/topics" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"cid":1,"title":"Hello from NodeBB on Klutch.sh","content":"Welcome!"}'

Health checks and production tips

  • Add an HTTP probe to /api/config or / for readiness.
  • Enforce HTTPS at the edge; forward internally to port 4567.
  • Keep DB and admin credentials in Klutch.sh secrets; rotate them regularly.
  • Monitor storage usage on uploads/logs; resize before it fills.
  • Pin image versions and test upgrades in staging; rebuild after plugin/theme changes.

NodeBB on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 4567 configured, and Redis/Mongo connected, you can deliver a real-time forum without extra YAML or workflow overhead.