Deploying Libervia

Introduction

Libervia (formerly known as Salut a Toi) is a comprehensive communication ecosystem built on the XMPP protocol, offering much more than traditional instant messaging. It combines real-time chat, blogging, file sharing, event management, forums, and social networking into a single federated platform that respects user privacy and promotes decentralization.

Written in Python, Libervia provides multiple frontends for different use cases: a web interface, desktop applications, command-line tools, and mobile apps. Its architecture leverages XMPP’s extensive extension protocol (XEP) ecosystem to deliver features like end-to-end encryption, group messaging, and content publishing.

Key highlights of Libervia:

• XMPP Foundation: Built on the battle-tested XMPP protocol for reliable, federated communication
• Multi-Frontend: Web, desktop, CLI, and mobile interfaces available
• Blogging Platform: Publish articles and micro-posts with federation support
• File Sharing: Share files securely with contacts or publicly
• Event Management: Create and manage events with RSVP functionality
• Forums: Discussion boards integrated with the XMPP network
• Photo Albums: Share galleries with access controls
• End-to-End Encryption: OMEMO support for private conversations
• Federation: Connect with any XMPP server worldwide
• ActivityPub Bridge: Interact with Mastodon and other ActivityPub networks

This guide walks through deploying Libervia on Klutch.sh using Docker, configuring XMPP services, and setting up the full communication platform.

Why Deploy Libervia on Klutch.sh

Deploying Libervia on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Libervia without complex configuration. Push to GitHub, and your platform deploys automatically.

Persistent Storage: Attach persistent volumes for user data, media files, and configuration. Your communications survive restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to all Libervia frontends.

GitHub Integration: Connect your repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your user base and activity levels.

Environment Variable Management: Securely store configuration without exposing sensitive data.

Custom Domains: Assign a custom domain for your Libervia instance, essential for XMPP federation.

Always-On Availability: Your communication platform remains available 24/7.

Prerequisites

Before deploying Libervia 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
• A custom domain for XMPP federation
• Understanding of XMPP protocol basics
• (Optional) DNS configuration access for SRV records

Understanding Libervia Architecture

Libervia consists of several components:

Backend (sat): The Python-based XMPP daemon handling all protocol operations.

Libervia Web: Django-based web frontend for browser access.

jp (CLI): Command-line interface for scripting and automation.

Cagou: Desktop/mobile frontend built with Kivy.

Database: SQLite or PostgreSQL for storing user data and content.

XMPP Server: Works with any XMPP server (Prosody, ejabberd, etc.).

Preparing Your Repository

Repository Structure

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

Creating the Dockerfile

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    libffi-dev \
    libxml2-dev \
    libxslt1-dev \
    libjpeg-dev \
    zlib1g-dev \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Libervia
RUN pip install libervia-backend libervia-web

# Create directories
RUN mkdir -p /var/lib/libervia /var/log/libervia

# Environment configuration
ENV LIBERVIA_DATA_DIR=/var/lib/libervia
ENV LIBERVIA_LOG_DIR=/var/log/libervia

# Expose ports
EXPOSE 8080 5222 5269

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

# Start Libervia
CMD ["libervia", "start"]

Creating the .dockerignore File

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

Environment Variables Reference

Variable	Required	Default	Description
LIBERVIA_DATA_DIR	No	/var/lib/libervia	Data storage directory
LIBERVIA_LOG_DIR	No	/var/log/libervia	Log file directory
LIBERVIA_XMPP_DOMAIN	Yes	-	Your XMPP domain
LIBERVIA_ADMIN_JID	No	-	Administrator JID

Deploying Libervia on Klutch.sh

Configure Your Domain

Set up DNS records for your domain:

• A record pointing to your server
• SRV records for XMPP federation (optional but recommended)

Push Your Repository to GitHub

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Libervia deployment configuration"
git remote add origin https://github.com/yourusername/libervia-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 “libervia” or “xmpp-platform”.

Create a New App

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

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080 (Libervia web interface)

Set Environment Variables

Add the following:

Variable	Value
LIBERVIA_XMPP_DOMAIN	Your domain (e.g., chat.example.com)
LIBERVIA_DATA_DIR	/var/lib/libervia

Attach Persistent Volumes

Mount Path	Recommended Size	Purpose
/var/lib/libervia	20 GB	User data, media, and configuration
/var/log/libervia	2 GB	Application logs

Deploy Your Application

Click Deploy to start the build process.

Configure XMPP Server

After deployment, configure an XMPP server (Prosody or ejabberd) to work with Libervia, or use Libervia’s built-in components.

Initial Configuration

Setting Up XMPP

Configure your XMPP domain:

1. Edit the Libervia configuration to match your domain
2. Set up TLS certificates for secure connections
3. Configure federation if connecting to other XMPP servers

Creating Admin Account

Set up administrator access:

1. Create the first user account via CLI
2. Grant administrative privileges
3. Configure moderation settings

Enabling Features

Activate Libervia modules:

1. Enable blogging for content publishing
2. Configure file sharing limits and storage
3. Set up event management features
4. Enable forums for community discussions

Using Libervia Features

Instant Messaging

Send encrypted messages:

1. Add contacts by their JID (user@domain)
2. Enable OMEMO encryption for privacy
3. Create group chats for team communication

Blogging

Publish content:

1. Access the blog interface
2. Create posts with rich media
3. Posts federate to followers on other XMPP servers

File Sharing

Share files securely:

1. Upload files through the web interface
2. Set access permissions (public, contacts, specific users)
3. Generate sharing links

Events

Manage events:

1. Create events with date, time, and location
2. Send invitations to contacts
3. Track RSVPs

Production Best Practices

Security Recommendations

• Enable end-to-end encryption (OMEMO) by default
• Configure proper TLS for all connections
• Regularly update Libervia and dependencies
• Monitor for spam and abuse

Performance Optimization

• Use PostgreSQL for larger deployments
• Configure caching for frequently accessed content
• Optimize media storage with compression
• Scale resources based on user activity

Backup Strategy

1. Back up the Libervia data directory
2. Export user accounts and configurations
3. Store database backups separately

Troubleshooting

Federation Issues

• Verify SRV DNS records are correct
• Check TLS certificate validity
• Ensure ports 5222 and 5269 are accessible
• Test with online XMPP federation testers

Login Problems

• Verify XMPP server is running
• Check user credentials
• Review authentication logs

Media Upload Failures

• Check storage permissions
• Verify disk space availability
• Review file size limits

Additional Resources

• Official Libervia Website
• Libervia Documentation
• Libervia Source Code
• XMPP Standards Foundation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Libervia on Klutch.sh gives you a comprehensive, federated communication platform with messaging, blogging, file sharing, and more. Built on XMPP, it interoperates with millions of users worldwide while keeping your data under your control.

With end-to-end encryption, multiple frontends, and extensive features, Libervia provides a privacy-respecting alternative to centralized communication services.