Skip to content
Klutch.sh Docs

Deploying a Lemmy App

Introduction

Lemmy is an open-source, federated link aggregator and forum platform built with Rust and Elixir. Deploying Lemmy with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for media and database data—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production best practices.

Prerequisites

  • A Klutch.sh account (create one)
  • A GitHub repository containing your Lemmy code/config (GitHub is the only supported git source)
  • Docker familiarity and Rust/Elixir basics
  • PostgreSQL credentials
  • Storage for media uploads, thumbnails, and logs

For onboarding, see the Quick Start.

Architecture and ports

  • Lemmy serves HTTP on port 8536 by default; set the internal container port to 8536. -(If you deploy Pictrs for media, run it as a separate app on port 127.0.0.1:8537 internally; on Klutch.sh use a separate app with HTTP or TCP as needed.)
  • PostgreSQL should run as a separate Klutch.sh TCP app, exposed on port 8000, connected internally on 5432.
  • Persistent storage is required for media and recommended for logs.

Repository layout

lemmy/
├── config/                 # Lemmy configuration files
├── Dockerfile              # Must be at repo root for auto-detection
├── media/                  # Media uploads (mount as volume)
├── pictrs/                 # Optional pictrs media service configs
├── README.md
└── .env.example            # Template only; no secrets

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

Installation (local) and starter commands

Test locally before pushing to GitHub:

Terminal window
docker run --rm -p 8536:8536 \
  -e LEMMY_DATABASE_URL=postgres://lemmy:password@localhost:5432/lemmy \
  dessalines/lemmy:latest

Optional helper start.sh for portability and Nixpacks fallback:

#!/usr/bin/env bash
set -euo pipefail
exec ./lemmy_server

Make it executable with chmod +x start.sh.

Dockerfile for Lemmy (production-ready)

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

FROM dessalines/lemmy:latest


WORKDIR /app


# Copy custom configs if needed
COPY config /app/config


EXPOSE 8536
CMD ["./lemmy_server"]

Notes:

  • Pin the image tag (e.g., :0.19.4) for reproducible builds.
  • If you run pictrs separately, deploy it as its own app with port settings appropriate to your setup.

Environment variables (Klutch.sh)

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

  • PORT=8536
  • LEMMY_DATABASE_URL=postgres://<user>:<password>@<host>:<port>/<db>
  • LEMMY_HOSTNAME=example-app.klutch.sh
  • LEMMY_UI_REDIRECT=https://example-app.klutch.sh
  • RUST_LOG=info
  • PICRTS__URL (if using an external pictrs media service)

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_BUILD_CMD="echo Lemmy uses prebuilt image"
  • NIXPACKS_START_CMD=./lemmy_server
  • NIXPACKS_RUST_VERSION=1.72
  • NIXPACKS_ELIXIR_VERSION=1.15

These keep Lemmy 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/media — media uploads and thumbnails.
  • /app/logs — optional logs if you keep them on disk.

Ensure these paths are writable inside the container.

Deploy Lemmy 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 Lemmy.
  3. Set the internal port to 8536.
  4. Add the environment variables above (database URL, hostname, pictrs URL if used, and any NIXPACKS_* overrides if you temporarily deploy without the Dockerfile).
  5. Attach persistent volumes for /app/media (and /app/logs if used), selecting sizes that fit your content and logging needs.
  6. Deploy. Your Lemmy instance 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 LEMMY_DATABASE_URL to that endpoint (internal port 5432).

Sample API call

Fetch site info to verify deployment:

Terminal window
curl -X GET "https://example-app.klutch.sh/api/v3/site" \
  -H "Content-Type: application/json"

Health checks and production tips

  • Add a reverse proxy health check to /api/v3/site or a lightweight status route.
  • Enforce HTTPS at the edge; forward HTTP to port 8536 internally.
  • Pin image tags and upgrade intentionally with DB backups.
  • Monitor disk usage on /app/media and /app/logs; resize volumes before they fill.
  • Back up PostgreSQL and media regularly; do not rely on container filesystems for durability.

Lemmy on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage for media, and flexible HTTP/TCP routing. With the Dockerfile at the repo root and port 8536 configured, you can run a federated link aggregator without extra YAML or workflow overhead.