Skip to content
Klutch.sh Docs

Deploying a Penpot App

Introduction

Penpot is an open-source design and prototyping platform for teams. Deploying Penpot with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for projects and assets—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Penpot Dockerfile (GitHub is the only supported git source)
  • PostgreSQL database (deploy as a Klutch.sh TCP app on port 8000 and connect on 5432)
  • Redis instance (deploy as a Klutch.sh TCP app on port 8000 and connect on 6379)
  • Storage sizing for assets, exports, and logs

For onboarding, see the Quick Start.

Architecture and ports

  • Penpot serves HTTP on internal port 9001; choose HTTP traffic and set the internal port to 9001.
  • Persistent storage is required for assets, exports, and logs.

Repository layout

penpot/
├── 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 penpot-local .
docker run -p 9001:9001 penpot-local

Dockerfile for Penpot (production-ready)

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

FROM penpotapp/penpot:latest


ENV PORT=9001


EXPOSE 9001
CMD ["bash", "-lc", "export PENPOT_PUBLIC_URI=${PENPOT_PUBLIC_URI:-http://localhost:${PORT}} && export PENPOT_PORT=${PORT} && /entrypoint.sh"]

Notes:

  • Pin the image tag (e.g., penpotapp/penpot:2.0.x) for stability; update intentionally.
  • The entrypoint uses environment variables for DB/Redis and storage; set them below.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PORT=9001
  • PENPOT_PUBLIC_URI=https://example-app.klutch.sh
  • PENPOT_DATABASE_URI=postgres://<user>:<password>@<db-host>:5432/<db>
  • PENPOT_REDIS_URI=redis://:<password>@<redis-host>:6379/0
  • PENPOT_SECRET_KEY=<secure-random>
  • Optional: PENPOT_TELEMETRY_ENABLED=false, email SMTP settings, and object storage options if you offload assets.

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_START_CMD=/entrypoint.sh
  • NIXPACKS_NODE_VERSION=18

Attach persistent volumes

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

  • /opt/data/assets — design assets.
  • /opt/data/exports — exported files.
  • /opt/data/logs — application logs (optional).

Ensure these paths are writable inside the container.

Deploy Penpot 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 9001.
  4. Add the environment variables above, including DB/Redis URIs, public URL, and secret key.
  5. Attach persistent volumes for /opt/data/assets, /opt/data/exports, and /opt/data/logs sized for your assets and logs.
  6. Deploy. Your Penpot instance will be reachable at https://example-app.klutch.sh; attach a custom domain if desired.

Sample usage

Check reachability:

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

After setup, create a team and projects via the web UI; API endpoints are primarily for internal services, so most workflows use the UI.

Health checks and production tips

  • Add an HTTP probe to / or a lightweight status page if you expose one.
  • Enforce HTTPS at the edge; forward internally to port 9001.
  • Keep PENPOT_SECRET_KEY, DB, and Redis credentials in Klutch.sh secrets; rotate regularly.
  • Monitor storage usage on /opt/data/assets and /opt/data/exports; resize before they fill.
  • Pin image versions and test upgrades in staging; back up DB and volumes before updates.

Penpot 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 9001 configured, and Postgres/Redis connected, you can deliver a secure, collaborative design platform without extra YAML or workflow overhead.