Skip to content
Klutch.sh Docs

Deploying Loomio

Introduction

Loomio is a collaborative decision-making platform that helps groups work together to make better decisions. Originally developed by a worker-owned cooperative in New Zealand, Loomio provides tools for structured discussions, proposals, and various voting methods that enable inclusive participation from all group members, regardless of their location or schedule.

Unlike traditional meetings where the loudest voices dominate, Loomio creates space for everyone to contribute thoughtfully. The platform supports asynchronous participation, meaning team members can engage with discussions and vote on proposals at times that work for them, making it ideal for distributed teams, community organizations, and democratic governance.

Key highlights of Loomio:

  • Structured Discussions: Threaded conversations with context and clarity
  • Multiple Decision Types: Proposals, polls, time polls, ranked choices, and more
  • Inclusive Participation: Asynchronous engagement for diverse schedules
  • Reply by Email: Participate without logging into the platform
  • Subgroups: Organize large groups into manageable units
  • Privacy Options: Public, secret, or closed group settings
  • Integration Ready: Webhooks and API for workflow automation
  • Mobile Friendly: Full-featured mobile experience
  • Accessibility: Designed for inclusive access
  • Open Source: AGPL licensed with active development

This guide walks through deploying Loomio on Klutch.sh using Docker, configuring the platform, and setting up for collaborative decision-making.

Why Deploy Loomio on Klutch.sh

Deploying Loomio on Klutch.sh provides several advantages:

Complete Control: Self-hosting ensures your discussions and decisions remain private within your infrastructure.

Persistent Storage: Attach persistent volumes for your database and files. Decision history and documents survive restarts.

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

GitHub Integration: Connect your configuration repository directly from GitHub for automatic deployments.

Custom Domains: Use your own domain for a professional, branded experience.

Scalable Resources: Allocate CPU and memory based on your group size and activity level.

Email Integration: Configure SMTP for notifications and reply-by-email functionality.

Always Available: Your decision-making platform remains accessible 24/7.

Prerequisites

Before deploying Loomio 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
  • SMTP credentials for email notifications
  • A domain name with DNS access for email configuration
  • (Optional) MX record configuration for reply-by-email

Understanding Loomio Architecture

Loomio uses a Ruby on Rails architecture with multiple components:

Rails Application: The core application handles discussions, proposals, voting, and user management.

PostgreSQL Database: Stores all group data, discussions, decisions, and user information.

Redis: Manages background job queues and caching for performance.

Worker Processes: Handle background tasks like sending emails and processing notifications.

Live Update Server: Provides real-time updates for discussions using WebSockets.

Preparing Your Repository

To deploy Loomio on Klutch.sh, use the official loomio-deploy repository as a base.

Repository Structure

loomio-deploy/
├── docker-compose.yml
├── Dockerfile
├── env.example
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM loomio/loomio:latest


# Set environment variables
ENV RAILS_ENV=production
ENV RAILS_LOG_TO_STDOUT=true


# Expose the web interface port
EXPOSE 3000


# The base image includes the default entrypoint

Creating Docker Compose Configuration

Create a docker-compose.yml for reference:

version: '3.8'


services:
  loomio:
    image: loomio/loomio:latest
    container_name: loomio
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
      - CANONICAL_HOST=${CANONICAL_HOST}
      - SMTP_SERVER=${SMTP_SERVER}
      - SMTP_PORT=${SMTP_PORT}
      - SMTP_USERNAME=${SMTP_USERNAME}
      - SMTP_PASSWORD=${SMTP_PASSWORD}
      - SMTP_DOMAIN=${SMTP_DOMAIN}
      - REPLY_HOSTNAME=${REPLY_HOSTNAME}
    volumes:
      - loomio_uploads:/loomio/public/system
      - loomio_files:/loomio/public/files
    depends_on:
      - db
      - redis


  db:
    image: postgres:15
    container_name: loomio_db
    restart: unless-stopped
    environment:
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=loomio_production
    volumes:
      - loomio_pgdata:/var/lib/postgresql/data


  redis:
    image: redis:7
    container_name: loomio_redis
    restart: unless-stopped


  worker:
    image: loomio/loomio:latest
    container_name: loomio_worker
    restart: unless-stopped
    command: bundle exec rake jobs:work
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - SECRET_KEY_BASE=${SECRET_KEY_BASE}
    depends_on:
      - db
      - redis


volumes:
  loomio_uploads:
  loomio_files:
  loomio_pgdata:

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Loomio requires extensive configuration:

VariableRequiredDescription
SECRET_KEY_BASEYesRails secret key (generate with openssl rand -hex 64)
DATABASE_URLYesPostgreSQL connection string
CANONICAL_HOSTYesPublic hostname for your Loomio instance
SMTP_SERVERYesSMTP server hostname
SMTP_PORTYesSMTP port (typically 587)
SMTP_USERNAMEYesSMTP authentication username
SMTP_PASSWORDYesSMTP authentication password
SMTP_DOMAINYesDomain for SMTP HELO
REPLY_HOSTNAMENoHostname for reply-by-email
REDIS_URLNoRedis connection URL
RAILS_ENVNoRails environment (production)

Deploying Loomio on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

    Generate Security Keys

    Generate required secrets:

    Terminal window
    # Secret key base
    openssl rand -hex 64
    

    # Database password
    openssl rand -base64 24

    Save these securely for environment variables configuration.

    Set Up Database

    Loomio requires PostgreSQL. You can:

    • Use Klutch.sh’s database services
    • Deploy PostgreSQL alongside Loomio
    • Use an external managed PostgreSQL service

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile docker-compose.yml .dockerignore
    git commit -m "Initial Loomio deployment configuration"
    git remote add origin https://github.com/yourusername/loomio-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. Give it a descriptive name like “loomio” or “decisions”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Loomio configuration.

    Configure HTTP Traffic

    In the deployment settings:

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

    Set Environment Variables

    In the environment variables section, add:

    VariableValue
    SECRET_KEY_BASEYour generated 128-character hex string
    DATABASE_URLpostgresql://user:password@host:5432/loomio_production
    CANONICAL_HOSTyour-loomio.klutch.sh
    SMTP_SERVERYour SMTP server
    SMTP_PORT587
    SMTP_USERNAMEYour SMTP username
    SMTP_PASSWORDYour SMTP password
    SMTP_DOMAINYour domain

    Attach Persistent Volumes

    Add persistent storage:

    Mount PathRecommended SizePurpose
    /loomio/public/system10 GBUploaded files and attachments
    /loomio/public/files10 GBDocument exports and downloads

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will:

    • Detect your Dockerfile automatically
    • Build the container image
    • Attach the persistent volumes
    • Start the Loomio container
    • Provision an HTTPS certificate

    Run Database Migrations

    After first deployment, run migrations (check Klutch.sh’s console access):

    Terminal window
    bundle exec rake db:setup

    Access Loomio

    Once deployment completes, access your Loomio instance at https://your-app-name.klutch.sh.

Initial Setup

Creating Your First Group

After accessing Loomio:

  1. Sign Up: Create your admin account
  2. Create Group: Click Start a group
  3. Name and Describe: Give your group a meaningful name and description
  4. Set Privacy: Choose between open, closed, or secret
  5. Invite Members: Add initial members via email

Group Settings

Configure your group:

  1. Navigate to Group settings
  2. Set the group handle (URL slug)
  3. Configure member permissions
  4. Set up subgroups if needed
  5. Customize the group cover image

Decision-Making Features

Starting a Discussion

Create focused discussions:

  1. Click New thread
  2. Add a clear title
  3. Provide context in the description
  4. Tag relevant members
  5. Attach files if needed

Creating Proposals

Make decisions with proposals:

  1. Within a thread, click Start a proposal
  2. Choose the proposal type:
    • Proposal: Yes/No/Abstain voting
    • Poll: Multiple choice options
    • Time poll: Find meeting times
    • Ranked choice: Prioritize options
    • Score poll: Rate options numerically
  3. Set the closing time
  4. Add a clear proposal statement
  5. Notify relevant members

Voting and Positions

Members can participate by:

  • Voting: Select their position
  • Stating reasons: Explain their choice
  • Changing votes: Update positions as discussion evolves
  • Abstaining: Explicitly choose not to decide

Outcomes

Document decisions:

  1. After voting closes, click Set outcome
  2. Summarize the decision
  3. List action items
  4. Assign responsible parties
  5. The outcome appears in the thread

Reply by Email

Configuring Email Reply

Enable participation without logging in:

  1. Set up MX records for a reply subdomain
  2. Configure REPLY_HOSTNAME environment variable
  3. Ensure SMTP is properly configured
  4. Test with a sample discussion

How It Works

  • Members receive email notifications
  • They can reply directly to the email
  • Their response appears in the discussion
  • Votes can be cast via email commands

Subgroups and Organization

Creating Subgroups

Organize large organizations:

  1. Navigate to your main group
  2. Click New subgroup
  3. Name and configure the subgroup
  4. Set membership (inherit or separate)
  5. Invite subgroup members

Subgroup Use Cases

  • Departments: Engineering, Marketing, Finance
  • Projects: Specific initiatives
  • Committees: Governance bodies
  • Regions: Geographic divisions

Integrations

Webhook Integration

Connect to external services:

  1. Navigate to Group settings → Webhooks
  2. Add webhook URL
  3. Select events to trigger:
    • New discussions
    • Proposals started
    • Votes cast
    • Outcomes set

Slack Integration

Connect Loomio to Slack:

  1. Configure Slack webhook URL
  2. Map groups to Slack channels
  3. Receive notifications in Slack
  4. Start discussions from Slack

API Access

Programmatic access:

Terminal window
# Get discussions
curl -H "Authorization: Bearer TOKEN" \
  https://your-loomio.klutch.sh/api/v1/discussions


# Create a discussion
curl -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"discussion": {"title": "New Topic", "group_id": 1}}' \
  https://your-loomio.klutch.sh/api/v1/discussions

Production Best Practices

Security Recommendations

  • Strong Secrets: Use complex values for SECRET_KEY_BASE
  • Database Security: Secure PostgreSQL access
  • Email Security: Use TLS for SMTP connections
  • Access Control: Configure appropriate group permissions

Performance Optimization

  • Redis Caching: Ensure Redis is properly configured
  • Background Workers: Scale workers for email volume
  • Database Indexes: Keep PostgreSQL optimized
  • CDN: Consider CDN for static assets

Backup Strategy

Protect your decision history:

  1. Database Backups: Regular PostgreSQL backups
  2. File Backups: Back up uploaded files
  3. Configuration: Export group settings
  4. Automated Schedule: Daily backup routine

Troubleshooting Common Issues

Emails Not Sending

Symptoms: Users don’t receive notifications.

Solutions:

  • Verify SMTP credentials
  • Check SMTP server connectivity
  • Review mail logs
  • Test SMTP connection directly

Database Connection Issues

Symptoms: Application errors about database.

Solutions:

  • Verify DATABASE_URL format
  • Check PostgreSQL is running
  • Review connection limits
  • Test direct database connection

Live Updates Not Working

Symptoms: Need to refresh for new content.

Solutions:

  • Check WebSocket configuration
  • Review nginx/proxy settings
  • Verify channels server is running
  • Test WebSocket connection

Additional Resources

Conclusion

Deploying Loomio on Klutch.sh gives you a powerful platform for collaborative decision-making with complete control over your data. The combination of structured discussions, multiple voting methods, and asynchronous participation makes it ideal for distributed teams and democratic organizations.

With email integration, webhook support, and comprehensive API access, Loomio integrates seamlessly into existing workflows. The self-hosted approach ensures sensitive discussions and decisions remain within your infrastructure.

Whether you’re governing a cooperative, running a community organization, or making team decisions, Loomio on Klutch.sh provides the tools needed for inclusive, transparent decision-making.