Skip to content
Klutch.sh Docs

Deploying Listaway

Introduction

Listaway is a self-hosted newsletter and mailing list management platform that gives you complete control over your email marketing efforts. Whether you’re running a personal blog newsletter, a business announcement list, or community updates, Listaway provides the tools to manage subscribers, create campaigns, and track engagement.

With a focus on simplicity and privacy, Listaway offers an alternative to commercial email marketing services while keeping your subscriber data under your control. The application handles the complexities of email delivery, subscription management, and analytics.

Key highlights of Listaway:

  • Subscriber Management: Import, export, and organize subscribers
  • Campaign Creation: Compose and schedule email campaigns
  • List Segmentation: Target specific subscriber groups
  • Analytics: Track opens, clicks, and engagement
  • Template System: Create reusable email templates
  • Subscription Forms: Embeddable signup forms
  • Double Opt-In: GDPR-compliant subscription confirmation
  • Unsubscribe Handling: Automatic unsubscribe management
  • Bounce Processing: Handle bounced emails
  • API Access: Integrate with other applications
  • Multi-List Support: Manage multiple lists independently

This guide walks through deploying Listaway on Klutch.sh using Docker.

Why Deploy Listaway on Klutch.sh

Deploying Listaway on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds Listaway from your Dockerfile. Push to GitHub, and your newsletter platform deploys.

Persistent Storage: Attach persistent volumes for your subscriber database and templates.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure subscription forms.

GitHub Integration: Connect your repository for automatic redeployments.

Scalable Resources: Allocate resources based on your subscriber count.

Environment Variable Management: Configure SMTP and settings securely.

Custom Domains: Use your own domain for sending emails.

Always-On Availability: Your newsletter platform remains accessible 24/7.

Prerequisites

Before deploying Listaway on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your configuration
  • Basic familiarity with Docker and containerization concepts
  • An SMTP server or email service (SendGrid, Mailgun, etc.)
  • A database (PostgreSQL or MySQL)
  • (Optional) A custom domain with proper DNS records

Understanding Listaway Architecture

Listaway uses standard web application components:

Web Application: Handles the admin interface and subscription forms.

Database: Stores subscribers, campaigns, and analytics.

Email Sender: Connects to SMTP for sending campaigns.

Queue Worker: Processes email sending in background.

Preparing Your Repository

Repository Structure

listaway-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

FROM node:18-alpine


# Install dependencies
RUN apk add --no-cache curl


# Set working directory
WORKDIR /app


# Environment configuration
ENV PORT=3000
ENV DATABASE_URL=${DATABASE_URL}
ENV SMTP_HOST=${SMTP_HOST}
ENV SMTP_PORT=${SMTP_PORT:-587}
ENV SMTP_USER=${SMTP_USER}
ENV SMTP_PASSWORD=${SMTP_PASSWORD}
ENV FROM_EMAIL=${FROM_EMAIL}
ENV FROM_NAME=${FROM_NAME:-Newsletter}


# Create data directory
RUN mkdir -p /app/data


# Expose port
EXPOSE 3000


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1


CMD ["node", "server.js"]

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local
node_modules/

Environment Variables Reference

VariableRequiredDefaultDescription
DATABASE_URLYes-Database connection string
SMTP_HOSTYes-SMTP server hostname
SMTP_PORTNo587SMTP server port
SMTP_USERYes-SMTP username
SMTP_PASSWORDYes-SMTP password
FROM_EMAILYes-Sender email address
FROM_NAMENoNewsletterSender display name

Deploying Listaway on Klutch.sh

    Set Up Database

    Deploy PostgreSQL and create a database for Listaway.

    Configure SMTP

    Set up an email sending service:

    • Use a transactional email provider (SendGrid, Mailgun, Postmark)
    • Or configure your own SMTP server
    • Ensure proper SPF/DKIM records for deliverability

    Push Your Repository to GitHub

    Terminal window
    git init
    git add Dockerfile .dockerignore README.md
    git commit -m "Initial Listaway deployment configuration"
    git remote add origin https://github.com/yourusername/listaway-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project named “listaway” or “newsletter”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your Listaway repository.

    Configure HTTP Traffic

    In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 3000

    Set Environment Variables

    Add the following:

    VariableValue
    DATABASE_URLYour database connection string
    SMTP_HOSTYour SMTP hostname
    SMTP_PORT587
    SMTP_USERYour SMTP username
    SMTP_PASSWORDYour SMTP password
    FROM_EMAILYour sender email
    FROM_NAMEYour sender name

    Attach Persistent Volumes

    Mount PathRecommended SizePurpose
    /app/data5 GBTemplates and uploads

    Deploy Your Application

    Click Deploy to start the build process.

    Complete Setup

    Access Listaway and configure your first mailing list.

Initial Configuration

Creating Lists

Set up your mailing lists:

  1. Create a new list
  2. Configure list settings
  3. Set up subscription preferences
  4. Create welcome email template

Subscription Forms

Enable subscriber signups:

  1. Generate embed code for forms
  2. Add forms to your website
  3. Configure confirmation emails
  4. Test subscription flow

Email Templates

Create reusable designs:

  1. Build base templates
  2. Add dynamic content placeholders
  3. Test across email clients
  4. Save for campaign use

Managing Campaigns

Creating Campaigns

Send newsletters:

  1. Compose campaign content
  2. Select target lists
  3. Preview and test
  4. Schedule or send immediately

Tracking Engagement

Monitor performance:

  1. View open rates
  2. Track link clicks
  3. Monitor bounces
  4. Analyze trends

Production Best Practices

Email Deliverability

  • Configure SPF, DKIM, and DMARC
  • Use a reputable sending domain
  • Warm up new sending addresses
  • Monitor reputation metrics

Security Recommendations

  • Use strong admin passwords
  • Secure SMTP credentials
  • Enable double opt-in
  • Handle unsubscribes promptly

Backup Strategy

  1. Back up database regularly
  2. Export subscriber lists
  3. Save email templates

Troubleshooting

Emails Not Sending

  • Verify SMTP credentials
  • Check sender reputation
  • Review queue status
  • Test with different recipients

Low Open Rates

  • Check spam folder placement
  • Improve subject lines
  • Verify sender authentication
  • Clean inactive subscribers

Subscription Issues

  • Test signup forms
  • Verify confirmation emails
  • Check double opt-in flow

Additional Resources

Conclusion

Deploying Listaway on Klutch.sh gives you a self-hosted newsletter platform with complete control over your subscriber data. Unlike commercial services with usage limits and fees, Listaway lets you grow your audience without restrictions.

With proper email configuration and regular maintenance, you can build and engage your community through effective email communication.