Skip to content
Klutch.sh Docs

Deploying a Tei App

Introduction

Tei is an open-source tool for collaborative data and task management. Deploying Tei with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage—all configured from klutch.sh/app. This guide covers installation, Dockerfile setup, environment variables, storage, Nixpacks overrides, and sample checks to confirm your deployment.

Prerequisites

  • Klutch.sh account (sign up)
  • GitHub repository containing your Tei Dockerfile (GitHub is the only supported git source)
  • External PostgreSQL database
  • Optional: object storage if you offload attachments

Architecture and ports

  • Tei serves HTTP on internal port 8000. Choose HTTP traffic and set the internal port to 8000.
  • Persistent storage is recommended for uploads and cached assets; primary data lives in Postgres.

Repository layout

tei/
├── 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

Build and run locally (ensure Postgres is reachable):

Terminal window
docker build -t tei-local .
docker run -p 8000:8000 \
  -e DATABASE_URL=postgres://user:pass@localhost:5432/tei \
  -e JWT_SECRET=$(openssl rand -hex 32) \
  tei-local

Dockerfile for Tei (production-ready)

Place this at the repo root; Klutch.sh auto-detects Dockerfiles.

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build


FROM node:18-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=8000
COPY --from=builder /app ./
RUN npm ci --omit=dev
EXPOSE 8000
CMD ["npm", "run", "start"]

Notes:

  • Pin Node to the version Tei supports; adjust if upstream changes.
  • Keep the Dockerfile at the repo root; Docker selection is automatic in Klutch.sh.

Environment variables (Klutch.sh)

Set these before deploying:

  • PORT=8000
  • DATABASE_URL=postgres://<user>:<password>@<host>:5432/<db>
  • JWT_SECRET=<secure-random-hex>
  • Optional: NEXTAUTH_SECRET=<secure-random-hex> if the app uses NextAuth
  • Optional object storage: S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_NODE_VERSION=18
  • NIXPACKS_START_CMD=npm run start

Attach persistent volumes

If you store uploads or cache locally, add storage in Klutch.sh (path and size only):

  • /app/storage — uploads/cache.

Ensure the path matches your Tei configuration and is writable.

Deploy Tei 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 8000.
  4. Add the environment variables above (database URL, JWT secret, optional storage keys).
  5. Attach a volume at /app/storage if you want local persistence, sized for your attachments/cache.
  6. Deploy. Your app will be reachable at https://example-app.klutch.sh; complete any in-app setup.

Sample checks

Landing page:

Terminal window
curl -I https://example-app.klutch.sh

Health endpoint (replace if the app exposes a specific route):

Terminal window
curl -I https://example-app.klutch.sh/api/health

Health checks and production tips

  • Add an HTTP readiness probe to / or your health endpoint.
  • Keep DB credentials, JWT secrets, and any storage keys in Klutch.sh secrets; rotate regularly.
  • Pin image/Node versions and test upgrades in staging before production rollout.
  • Monitor /app/storage volume usage; resize proactively or move to object storage for larger attachments.

Tei on Klutch.sh delivers reproducible Docker builds, managed secrets, and optional storage—without extra YAML or CI steps. Configure ports, env vars, and storage, then launch your collaborative platform.