Skip to main content

​
Overview

This template provides a production‑ready Papercups instance as a Monk runnable. You can:
  • Run it directly to host your own customer messaging platform
  • Inherit it in your own infrastructure for customer support and live chat
Papercups is an open-source alternative to Intercom. It provides live chat, customer messaging, and support tools that integrate seamlessly with your website or application. Built with Elixir/Phoenix and React, it’s designed for developers who want full control over their customer communication.

​
What this template manages

  • Papercups web application (Elixir/Phoenix)
  • PostgreSQL database
  • Real-time WebSocket connections
  • Chat widget and admin dashboard
  • Email notifications
  • Web UI on port 4000

​
Quick start (run directly)

  1. Load templates
monk load MANIFEST
  1. Run Papercups stack
monk run papercups/stack
  1. Access and configure
Once started, access the Admin Dashboard at http://localhost:4000 and create your admin account on first visit.

​
Configuration

Key variables you can customize in this template: 
variables:
  papercups-image-tag: "latest"           # Papercups image tag
  http-port: "4000"                       # HTTP port
  backend-url: "http://localhost:4000"    # Backend URL
  database-url: "postgresql://postgres:postgres@db:5432/papercups"
  secret-key-base: "..."                  # Phoenix secret key (generate with openssl)
  mailgun-api-key: "..."                  # Mailgun API key (optional)
  from-email: "noreply@papercups.io"      # Sender email address
  react-app-file-uploads-enabled: "true"  # Enable file uploads
Data is persisted under ${monk-volume-path}/papercups and ${monk-volume-path}/postgres on the host. Inherit the Papercups stack in your infrastructure for customer support. Example: 
namespace: mycompany
support:
  defines: runnable
  inherits: papercups/stack
  variables:
    backend-url: "https://support.mycompany.com"
    secret-key-base: <- secret("papercups-secret")
    mailgun-api-key: <- secret("mailgun-key")
    from-email: "support@mycompany.com"
Generate a secure secret key: 
openssl rand -base64 64
Then set the secrets and run: 
monk secrets add -g papercups-secret="YOUR_GENERATED_SECRET"
monk secrets add -g mailgun-key="YOUR_MAILGUN_API_KEY"
monk run mycompany/support

​
Ports and connectivity

  • Web UI: TCP port 4000
  • WebSocket: Same port as HTTP (for real-time chat)

​
Persistence and volumes

  • PostgreSQL data: ${monk-volume-path}/postgres:/var/lib/postgresql/data
  • Papercups uploads: ${monk-volume-path}/papercups/uploads:/app/uploads
  • Papercups data: ${monk-volume-path}/papercups:/app/data

​
Features

  • Live Chat Widget: Embeddable chat widget for websites
  • Customer Inbox: Unified inbox for all conversations
  • Team Collaboration: Assign conversations to team members
  • Slack Integration: Get notifications and reply from Slack
  • Email Notifications: Alert team members of new messages
  • Customer Profiles: View customer history and details
  • File Sharing: Send and receive files in chat
  • Typing Indicators: Real-time typing status
  • Custom Branding: Customize widget colors and appearance
  • React/JavaScript SDK: Easy integration

​
Widget Installation

Add to your website: 
<script>
  window.Papercups = {
    config: {
      accountId: 'YOUR_ACCOUNT_ID',
      title: 'Welcome!',
      subtitle: 'How can we help?',
      primaryColor: '#1890ff',
      baseUrl: 'http://localhost:4000'
    }
  };
</script>
<script
  type="text/javascript"
  async
  defer
  src="http://localhost:4000/widget.js"
></script>

​
React Integration

import React from 'react';
import {ChatWidget} from '@papercups-io/chat-widget';

const MyApp = () => {
  return (
    <ChatWidget
      accountId="YOUR_ACCOUNT_ID"
      title="Welcome!"
      subtitle="How can we help?"
      primaryColor="#1890ff"
      baseUrl="http://localhost:4000"
    />
  );
};

​
Slack Integration

  1. Go to Settings → Integrations
  2. Click “Add to Slack”
  3. Authorize Papercups
  4. Choose Slack channel for notifications
  5. Reply to customers directly from Slack

​
Use cases

Papercups excels at:
  • Website live chat support
  • Customer service and helpdesk
  • Sales and lead qualification
  • Product feedback collection
  • In-app messaging
  • Multi-channel customer support

​
Team Management

  • Create team members in Settings → Team
  • Assign conversations to specific agents
  • Set availability status
  • View team performance metrics

​
Customization

Customize the chat widget:
  • Branding: Logo, colors, greeting message
  • Behavior: Auto-open, show/hide on certain pages
  • Fields: Collect custom user information
  • Position: Bottom right/left placement
  • Monitoring: see the prometheus-grafana/ template in this repository for observability and metrics
  • Database backup: see postgres-backup/ for automated PostgreSQL backups

​
Troubleshooting

  • Initial setup: Access the admin dashboard at http://localhost:4000 and create your first account. Get your Account ID from Settings → Account.
  • Widget not loading: Verify that baseUrl in the widget configuration matches your backend URL.
  • Slack integration: If Slack notifications fail, re-authorize the app in Settings → Integrations.
  • Email issues: Verify your Mailgun API key and domain configuration are correct.
  • WebSocket issues: Ensure WebSocket connections are not blocked by firewalls or proxies.
  • Database migrations: If the app fails to start due to migration issues, run:
docker exec papercups mix ecto.migrate
  • Check logs:
monk logs -l 500 -f papercups/papercups