Skip to content
Klutch.sh Docs

Deploying a Papercups App

Introduction

Papercups is an open-source live chat and customer messaging platform built with Elixir/Phoenix and a React front end. Deploying Papercups with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for uploads and logs—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Papercups code and Dockerfile (GitHub is the only supported git source)
  • PostgreSQL database (deploy as a Klutch.sh TCP app on port 8000 and connect on 5432)
  • Optional: SMTP credentials for email notifications and S3-compatible storage for attachments
  • Domain and TLS for secure access

For onboarding, see the Quick Start.

Architecture and ports

  • Papercups serves HTTP on internal port 4000 (Phoenix); choose HTTP traffic.
  • Persistent storage is recommended for uploads and logs.

Repository layout

papercups/
├── Dockerfile              # Must be at repo root for auto-detection
├── mix.exs
├── mix.lock
├── assets/                 # Frontend
└── config/                 # Phoenix config

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
mix deps.get
cd assets && npm install && cd ..
mix compile
MIX_ENV=prod mix phx.digest
MIX_ENV=prod mix ecto.migrate
MIX_ENV=prod PORT=4000 mix phx.server

Dockerfile for Papercups (production-ready)

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

FROM hexpm/elixir:1.15.7-erlang-26.0.2-alpine-3.18 AS build


ENV LANG=C.UTF-8 MIX_ENV=prod
WORKDIR /app


RUN apk add --no-cache build-base git nodejs npm python3


COPY mix.exs mix.lock ./
RUN mix deps.get --only prod


COPY assets assets
RUN cd assets && npm install && npm run deploy


COPY . .
RUN mix compile
RUN mix phx.digest
RUN MIX_ENV=prod mix release


FROM alpine:3.18 AS app


RUN apk add --no-cache openssl ncurses-libs libstdc++


ENV LANG=C.UTF-8 \
    MIX_ENV=prod \
    PORT=4000 \
    SHELL=/bin/sh


WORKDIR /app
COPY --from=build /app/_build/prod/rel/papercups ./


EXPOSE 4000
CMD ["bin/papercups", "start"]

Notes:

  • Pin Elixir/Erlang/alpine versions for stability.
  • Add OS deps if your extensions require them.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • PORT=4000
  • DATABASE_URL=postgres://<user>:<password>@<db-host>:5432/<db>
  • SECRET_KEY_BASE=<secure-random>
  • MIX_ENV=prod
  • Optional S3: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, S3_BUCKET, S3_REGION
  • Optional SMTP: SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_SSL=true|false, SMTP_RETRIES

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_ELIXIR_VERSION=1.15.7
  • NIXPACKS_ERLANG_VERSION=26.0.2
  • NIXPACKS_BUILD_CMD=mix deps.get --only prod && cd assets && npm install && npm run deploy && cd .. && mix compile && mix phx.digest && MIX_ENV=prod mix release
  • NIXPACKS_START_CMD=./bin/papercups start

Attach persistent volumes

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

  • /app/uploads — file uploads/attachments (if stored locally).
  • /app/log — optional logs if written to disk.

Ensure these paths are writable.

Deploy Papercups 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 4000.
  4. Add the environment variables above, including database, secrets, and optional S3/SMTP settings.
  5. Attach persistent volumes for /app/uploads (and /app/log if used) sized for your uploads and logs.
  6. Deploy. Run migrations via a one-off task if not already run during build: MIX_ENV=prod ./bin/papercups eval \"Papercups.Release.migrate\".

Sample API usage

List conversations (replace token with your JWT or API token):

Terminal window
curl -X GET "https://example-app.klutch.sh/api/conversations" \
  -H "Authorization: Bearer <token>"

Create a message:

Terminal window
curl -X POST "https://example-app.klutch.sh/api/messages" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id":"<conversation_id>","body":"Hello from Papercups on Klutch.sh"}'

Health checks and production tips

  • Add an HTTP probe to / or a simple health endpoint if exposed.
  • Enforce HTTPS at the edge; forward internally to port 4000.
  • Keep SECRET_KEY_BASE, DB creds, and S3/SMTP keys in Klutch.sh secrets; rotate regularly.
  • Monitor storage usage for /app/uploads; resize before it fills or offload to S3.
  • Pin image versions and test upgrades in staging; back up DB and uploads before updates.

Papercups 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 4000 configured, and Postgres connected, you can deliver real-time customer messaging without extra YAML or workflow overhead.