Deploying Gancio

Introduction

Gancio is a shared agenda for local communities that emphasizes decentralization, privacy, and federation. This open-source platform allows communities to create and share events while integrating with the fediverse through ActivityPub support. Gancio offers multiple export options including RSS feeds, ICS calendars, iframes, and web components for seamless event sharing across platforms.

Built with Node.js and designed for simplicity, Gancio provides a clean interface for event management without requiring user accounts for event submission. The platform supports multiple languages and can be configured to work with various database backends including SQLite, PostgreSQL, and MariaDB.

Key highlights of Gancio:

ActivityPub Federation: Connect with the fediverse to share events across Mastodon, Pleroma, and other federated platforms
Anonymous Event Submission: Allow community members to submit events without requiring registration
Multiple Export Formats: RSS, ICS, iframes, and web components for flexible integration
Multi-language Support: Interface available in multiple languages for diverse communities
Flexible Database Options: Choose between SQLite, PostgreSQL, or MariaDB based on your needs
Calendar Integration: Export events to calendar applications via ICS feeds
Moderation Tools: Admin approval workflows and content moderation features
Privacy-Focused: No tracking, no analytics, respects user privacy
Open Source: Licensed under AGPL-3.0

This guide walks through deploying Gancio on Klutch.sh using Docker, configuring persistent storage, and setting up federation for your community event platform.

Why Deploy Gancio on Klutch.sh

Deploying Gancio on Klutch.sh provides several advantages for managing your community event calendar:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Gancio without complex orchestration or manual server configuration. Push to GitHub, and your community agenda deploys automatically.

Persistent Storage: Attach persistent volumes for your database, uploads, and configuration. Your events and media survive container restarts and redeployments without data loss.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your event platform and proper ActivityPub federation from anywhere without manual certificate management.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments, keeping your deployment in sync with your repository.

Scalable Resources: Allocate CPU and memory based on your community size and expected traffic. Start small and scale up as your event platform grows.

Environment Variable Management: Securely store sensitive configuration like database credentials and secret keys through Klutch.sh’s environment variable system without exposing credentials in your repository.

Custom Domains: Assign a custom domain to your Gancio instance for a professional, community-branded experience.

Always-On Availability: Your community agenda remains accessible 24/7 without managing your own hardware or dealing with home network configuration.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Gancio configuration
Basic familiarity with Docker and containerization concepts
A PostgreSQL database (see PostgreSQL deployment guide)
(Optional) A custom domain for your Gancio instance

Understanding Gancio Architecture

Gancio is built on a straightforward architecture designed for community event management:

Node.js Backend: The core application runs on Node.js, providing a lightweight and efficient server for handling event data and federation.

Database Storage: Gancio supports SQLite for simple deployments or PostgreSQL/MariaDB for production use. The database stores events, users, and configuration.

File Storage: Uploaded images and attachments are stored in a configurable directory, typically /gancio/uploads.

ActivityPub Integration: Gancio implements the ActivityPub protocol for federation, allowing events to be shared across the fediverse.

Configuration File: Settings are managed through a config.json file that controls database connections, federation settings, and site customization.

Preparing Your Repository

To deploy Gancio on Klutch.sh, create a GitHub repository containing your Dockerfile and any custom configuration.

Repository Structure

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

Creating the Dockerfile

Create a Dockerfile in the root of your repository. This example uses the official Gancio image:

FROM cisti/gancio:latest

# Set environment variables
ENV NODE_ENV=production

# Expose the web interface port
EXPOSE 13120

# The base image includes the default entrypoint

Advanced Dockerfile with Custom Configuration

For more control over your deployment, use this extended Dockerfile:

FROM cisti/gancio:latest

# Set production environment
ENV NODE_ENV=production

# Set timezone
ENV TZ=${TZ:-UTC}

# Create necessary directories
RUN mkdir -p /gancio/uploads /gancio/config

# Health check to verify application is running
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:13120 || exit 1

# Expose the application port
EXPOSE 13120

Creating the .dockerignore File

Create a .dockerignore file to exclude unnecessary files from the build:

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

Environment Variables Reference

Gancio uses environment variables and a configuration file for settings:

Variable	Required	Default	Description
`NODE_ENV`	No	development	Set to `production` for production deployments
`TZ`	No	UTC	Timezone for the container
`DB_DIALECT`	Yes	-	Database type: `sqlite`, `postgres`, or `mariadb`
`DB_HOST`	Conditional	-	Database host (required for postgres/mariadb)
`DB_PORT`	Conditional	-	Database port (5432 for postgres, 3306 for mariadb)
`DB_NAME`	Conditional	-	Database name
`DB_USER`	Conditional	-	Database username
`DB_PASSWORD`	Conditional	-	Database password
`BASE_URL`	Yes	-	Public URL of your Gancio instance
`SECRET`	Yes	-	Secret key for session encryption

Deploying Gancio on Klutch.sh

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

Set Up PostgreSQL Database

Gancio works best with PostgreSQL for production deployments. Deploy a PostgreSQL instance on Klutch.sh following the PostgreSQL deployment guide. Note your database credentials for the next steps.

Generate Your Secret Key

Before deployment, generate a secure secret key for Gancio:

openssl rand -hex 32

Save this key securely—you’ll need it for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

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

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 Gancio Dockerfile.

Configure HTTP Traffic

Gancio serves its web interface over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 13120 (Gancio’s default port)

Set Environment Variables

In the environment variables section, add the following:

Variable	Value
`NODE_ENV`	`production`
`DB_DIALECT`	`postgres`
`DB_HOST`	Your PostgreSQL host
`DB_PORT`	`5432`
`DB_NAME`	`gancio`
`DB_USER`	Your database username
`DB_PASSWORD`	Your database password
`BASE_URL`	`https://your-app-name.klutch.sh`
`SECRET`	Your generated secret key
`TZ`	Your timezone (e.g., `America/New_York`)

Attach Persistent Volumes

Persistent storage is essential for Gancio. Add the following volumes:

Mount Path	Recommended Size	Purpose
`/gancio/uploads`	10 GB	Event images and media uploads
`/gancio/config`	1 GB	Configuration files

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 Gancio container
Provision an HTTPS certificate

Access Gancio

Once deployment completes, access your Gancio instance at https://your-app-name.klutch.sh. The first-time setup wizard will guide you through initial configuration.

Initial Setup and Configuration

First-Time Setup Wizard

When you first access your Gancio instance, you’ll be guided through the initial setup:

Admin Account: Create your administrator account with a secure password
Site Information: Configure your community name and description
Timezone Settings: Set the default timezone for events
Federation Options: Enable or disable ActivityPub federation

Configuring Site Settings

After initial setup, access the admin panel to customize your instance:

Log in with your admin credentials
Navigate to Settings in the admin menu
Configure:
- Site title and description
- Default event visibility
- Moderation settings
- Federation preferences

ActivityPub Federation

To enable federation with the fediverse:

Go to Settings → Federation
Enable ActivityPub support
Configure your instance’s federated identity
Your events can now be followed from Mastodon and other ActivityPub-compatible platforms

Event Management

Creating Events

Events can be created through the web interface:

Click Add Event on the main page
Fill in event details:
- Title and description
- Date, time, and duration
- Location (physical or online)
- Category/tags
- Event image
Submit for approval (if moderation is enabled) or publish directly

Moderation Workflow

Configure moderation settings for submitted events:

Setting	Description
No Moderation	Events are published immediately
Admin Approval	Events require admin approval before publishing
Trusted Users	Registered users bypass moderation

Calendar Integration

Export your events to calendar applications:

Access the ICS feed URL from the calendar icon
Subscribe in your calendar application
Events sync automatically

User Management

User Roles

Gancio supports different user types:

Role	Permissions
Anonymous	Submit events (subject to moderation)
User	Submit events, manage own events
Admin	Full access, moderation, settings

Creating User Accounts

Administrators can manage users:

Go to Admin → Users
Create new users or manage existing ones
Assign appropriate roles

Customization

Theming

Customize the appearance of your Gancio instance:

Navigate to Settings → Appearance
Configure colors and branding
Add custom CSS if needed

Embedding Events

Embed your event calendar on other websites:

<iframe src="https://your-app-name.klutch.sh/embed"
        width="100%"
        height="600"
        frameborder="0">
</iframe>

Production Best Practices

Security Recommendations

Secret Key: Use a strong, unique secret key and never commit it to version control
HTTPS: Always use HTTPS for production (provided automatically by Klutch.sh)
Admin Password: Use a strong administrator password
Regular Updates: Keep your Gancio image updated for security patches

Backup Strategy

Protect your event data:

Database Backups: Regularly back up your PostgreSQL database
Media Backups: Back up the /gancio/uploads directory
Configuration: Back up your configuration files

Performance Optimization

Database: Use PostgreSQL for better performance with many events
Caching: Gancio includes built-in caching for federation
Resources: Allocate sufficient CPU and memory for your expected traffic

Troubleshooting Common Issues

Application Won’t Start

Symptoms: Container exits immediately or fails health checks.

Solutions:

Verify database connection settings are correct
Check that the SECRET environment variable is set
Ensure BASE_URL matches your deployment URL
Review startup logs for specific error messages

Federation Not Working

Symptoms: Events not appearing on federated platforms.

Solutions:

Verify HTTPS is properly configured
Check that BASE_URL is publicly accessible
Ensure federation is enabled in settings
Review ActivityPub logs for errors

Events Not Displaying

Symptoms: Events created but not visible.

Solutions:

Check moderation queue for pending events
Verify event dates are correct
Clear browser cache
Check event visibility settings

Additional Resources

Conclusion

Deploying Gancio on Klutch.sh gives you a powerful, privacy-focused community event platform with automatic builds, persistent storage, and secure HTTPS access. The combination of Gancio’s federation capabilities and Klutch.sh’s deployment simplicity means you can focus on building your community rather than managing infrastructure.

With ActivityPub support, your events can reach audiences across the fediverse, while the flexible moderation tools help maintain a quality event calendar. Whether you’re organizing local meetups, community gatherings, or city-wide events, Gancio on Klutch.sh provides the foundation for a reliable, always-available event platform that respects user privacy.