Skip to content
Klutch.sh Docs

Deploying a KeeWeb App

Introduction

KeeWeb is an open-source web and desktop client for KeePass databases. Deploying KeeWeb with a Dockerfile on Klutch.sh gives you reproducible builds, managed secrets, and persistent storage for hosted .kdbx files—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, and best practices for secure password vault access.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your KeeWeb build or custom configuration (GitHub is the only supported git source)
  • Docker familiarity and Node.js 18+ knowledge
  • Optional: Hosting of .kdbx files on persistent storage or S3-compatible object storage

For platform onboarding, see the Quick Start.

Architecture and ports

  • KeeWeb serves static assets over HTTP; set the internal container port to 8080.
  • If you store .kdbx vaults locally, attach a persistent volume; if remote, configure URLs via environment variables.
  • No databases are required for the static app, but you may add TCP apps for ancillary services if needed.

Repository layout

keeweb/
├── public/                 # Built static site
├── config/                 # Custom config.json or settings (optional)
├── 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

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

Installation (local) and starter commands

Build and run locally before pushing to GitHub:

Terminal window
pnpm install
pnpm build
pnpm serve -- --port 8080

Optional start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
pnpm serve -- --port 8080

Make it executable with chmod +x start.sh.

Dockerfile for KeeWeb (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 build


FROM nginx:alpine
WORKDIR /usr/share/nginx/html


COPY --from=build /app/public /usr/share/nginx/html


EXPOSE 8080
CMD ["nginx", "-g", "daemon off;"]

Notes:

  • Static files are served via Nginx for performance; adjust Nginx config if you need headers or caching tweaks.
  • If you host .kdbx files locally, mount them under /usr/share/nginx/html/vaults (or your preferred path).

Environment variables (Klutch.sh)

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

  • PORT=8080
  • KEEWEB_CONFIG_URL=/config/config.json (if you serve custom config)
  • VAULT_BASE_URL=https://example-app.klutch.sh/vaults (if hosting vaults locally)

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD=pnpm install --frozen-lockfile && pnpm build
  • NIXPACKS_START_CMD=pnpm serve -- --port 8080
  • NIXPACKS_NODE_VERSION=18

These keep KeeWeb 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):

  • /usr/share/nginx/html/vaults — for .kdbx files if you store them locally.
  • /usr/share/nginx/html/config — optional for a custom config.json.

Ensure these paths are writable inside the container if you update files at runtime.

Deploy KeeWeb 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 KeeWeb.
  3. Set the internal port to 8080.
  4. Add the environment variables above (config and vault URLs, plus any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /usr/share/nginx/html/vaults (and /usr/share/nginx/html/config if used), selecting sizes that fit your vaults and configs.
  6. Deploy. Your KeeWeb instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample config snippet

Example config/config.json served with the app:

{
  "settings": {
    "autoSave": true,
    "theme": "fb",
    "locale": "en"
  },
  "files": [
    {
      "name": "Personal Vault",
      "path": "/vaults/personal.kdbx"
    }
  ]
}

Health checks and production tips

  • Add a reverse proxy health endpoint (e.g., /) to verify static files serve correctly.
  • Enforce HTTPS at the edge; forward HTTP to port 8080 internally.
  • Keep lockfiles committed and Node versions pinned for reproducible builds.
  • Regularly rotate .kdbx master passwords and store them outside the container.
  • Monitor storage usage for vaults/configs and resize before they fill.

KeeWeb on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage for vaults, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and ports set to 8080 for the app (8000 externally for any TCP companions), you can serve secure KeePass vaults without extra YAML or workflow overhead.