Skip to content
Klutch.sh Docs

Deploying a Joplin App

Introduction

Joplin Server powers sync and collaboration for the open-source Joplin note-taking apps. Deploying Joplin with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for attachments—all from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for reliable note sync.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Joplin Server code/config (GitHub is the only supported git source)
  • Docker familiarity and Node.js 18+ for local testing
  • PostgreSQL credentials
  • Storage capacity for file attachments and logs

For platform onboarding, review the Quick Start.

Architecture and ports

  • Joplin Server runs HTTP on port 22300 by default; set the internal container port to 22300.
  • PostgreSQL should run as a separate Klutch.sh TCP app. Expose it on port 8000 and connect internally on 5432.
  • Persistent storage is required for user data, attachments, and logs.

Repository layout

joplin-server/
├── packages/server/        # Joplin Server source
├── Dockerfile              # Must be at repo root for auto-detection
├── package.json
├── pnpm-lock.yaml          # or yarn.lock / package-lock.json
├── .env.example            # Template only; no secrets
└── README.md

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

Installation (local) and starter commands

Install dependencies and run locally before pushing to GitHub:

Terminal window
pnpm install
pnpm run build
pnpm start -- --port 22300

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
pnpm start -- --port 22300

Make it executable with chmod +x start.sh.

Dockerfile for Joplin (production-ready)

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

FROM node:18-alpine AS build
WORKDIR /app


COPY package.json pnpm-lock.yaml* yarn.lock* package-lock.json* ./
RUN corepack enable
RUN pnpm install --frozen-lockfile


COPY . .
RUN pnpm run build


FROM node:18-alpine
WORKDIR /app
ENV NODE_ENV=production PORT=22300


COPY --from=build /app /app
RUN corepack enable && pnpm install --prod --frozen-lockfile


EXPOSE 22300
CMD ["pnpm", "start", "--", "--port", "22300"]

Notes:

  • If you use native modules, add build tools in the build stage (apk add --no-cache python3 make g++).
  • Keep attachment storage paths writable and on a volume.

Environment variables (Klutch.sh)

Set these in the Klutch.sh app settings (Secrets tab) before deploying:

  • NODE_ENV=production
  • PORT=22300
  • APP_BASE_URL=https://example-app.klutch.sh
  • POSTGRES_PASSWORD=<db-password>
  • POSTGRES_DATABASE=<db-name>
  • POSTGRES_USER=<db-user>
  • POSTGRES_PORT=5432
  • POSTGRES_HOST=<db-host>
  • DB_CLIENT=pg
  • LOG_LEVEL=info

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=pnpm install --frozen-lockfile && pnpm run build
  • NIXPACKS_START_CMD=pnpm start -- --port 22300
  • NIXPACKS_NODE_VERSION=18

These keep Joplin compatible with Nixpacks defaults when a Dockerfile is absent.

Attach persistent volumes

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

  • /app/packages/server/logs — for server logs.
  • /app/packages/server/files — for attachments/uploads.

Ensure these paths are writable inside the container.

Deploy Joplin 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.
  1. Connect the GitHub repository; Klutch.sh automatically detects the Dockerfile.
  2. Choose HTTP traffic for Joplin.
  3. Set the internal port to 22300.
  4. Add the environment variables above (Postgres settings, base URL, log level, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /app/packages/server/logs and /app/packages/server/files, selecting sizes that match your retention needs.
  6. Deploy. Your Joplin Server will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

For PostgreSQL on Klutch.sh, create a separate TCP app, expose it on port 8000, and point POSTGRES_HOST to that endpoint (internal port 5432).

Health checks and production tips

  • Add a /ping or /health endpoint proxy for uptime monitoring.
  • Enforce HTTPS at the edge; forward HTTP to port 22300 internally.
  • Monitor disk usage on attachment and log volumes; resize before they fill.
  • Keep lockfiles committed and Node versions pinned for reproducible builds.
  • Back up PostgreSQL and attachments regularly; do not rely on container filesystems for durability.

Joplin on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage for attachments, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 22300 for the app (8000 externally for TCP databases), you can deliver reliable note syncing without extra YAML or workflow overhead.