Deploying Antragsgruen (motion.tools)

Introduction

Antragsgruen (also known as motion.tools) is a digital motion management system designed for political parties, NGOs, and democratic organizations to manage motions, amendments, and voting processes during assemblies and conventions. Originally developed for the German Green Party, it has been adopted by organizations worldwide for transparent, collaborative decision-making.

The platform enables delegates to submit motions, propose amendments, and participate in structured discussions. Administrators can manage the entire lifecycle of proposals from submission through voting, with comprehensive tools for merging amendments and generating final documents.

Key highlights of Antragsgruen:

Motion Management: Submit, categorize, and track motions through their entire lifecycle
Amendment Tracking: Propose inline amendments with clear diff visualization
Collaborative Editing: Merge amendments with conflict resolution tools
Voting System: Integrated voting for motions and amendments
User Management: Flexible authentication with support for organizations and delegates
PDF Generation: Automatic creation of motion books and voting documents
Multi-Site Support: Host multiple consultations on a single instance
Responsive Design: Works on desktop and mobile devices
OpenSlides Integration: Import and export compatibility with OpenSlides
Customizable Workflows: Adapt the submission and approval process to your needs
Multi-Language: Available in German, English, French, and more
Open Source: Licensed under AGPL-3.0

This guide walks through deploying Antragsgruen on Klutch.sh using Docker, configuring the database, and setting up your first consultation.

Why Deploy Antragsgruen on Klutch.sh

Deploying Antragsgruen on Klutch.sh provides several advantages for democratic organizations:

Event-Ready Availability: Your motion system remains accessible before, during, and after assemblies without infrastructure concerns.

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Antragsgruen without complex server configuration.

Persistent Storage: Attach persistent volumes for your database, uploaded documents, and generated PDFs.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure voting and user authentication.

GitHub Integration: Connect your configuration repository for automatic redeployments when you update settings.

Scalable Resources: Scale up during large assemblies and scale down during quiet periods.

Custom Domains: Assign a custom domain for professional branding during events.

Prerequisites

Before deploying Antragsgruen 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 MySQL/MariaDB database (can be deployed on Klutch.sh)
(Optional) A custom domain for your Antragsgruen instance

Understanding Antragsgruen Architecture

Antragsgruen is built on the Yii2 PHP framework with several key components:

PHP Application: The core Yii2 application handling motion management, user authentication, and workflow processing.

MySQL Database: Stores all consultations, motions, amendments, users, and voting data.

LaTeX/PDF Engine: Generates professional PDF documents for motion books and voting sheets.

Asset Pipeline: Manages JavaScript and CSS for the responsive web interface.

Preparing Your Repository

Create a GitHub repository with your Antragsgruen configuration.

Repository Structure

antragsgruen-deploy/
├── Dockerfile
├── config.php
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in your repository root:

FROM php:8.2-apache

# Install dependencies
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libzip-dev \
    libicu-dev \
    git \
    unzip \
    texlive-latex-base \
    texlive-fonts-recommended \
    texlive-latex-extra \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd zip intl pdo pdo_mysql \
    && rm -rf /var/lib/apt/lists/*

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Set working directory
WORKDIR /var/www/html

# Clone Antragsgruen
RUN git clone https://github.com/CatoTH/antragsgruen.git . \
    && composer install --no-dev --optimize-autoloader

# Set environment variables
ENV DB_HOST=${DB_HOST}
ENV DB_NAME=${DB_NAME}
ENV DB_USER=${DB_USER}
ENV DB_PASSWORD=${DB_PASSWORD}
ENV ANTRAGSGRUEN_SALT=${ANTRAGSGRUEN_SALT}

# Copy configuration
COPY config.php /var/www/html/config/config.php

# Set permissions
RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html

# Enable Apache mod_rewrite
RUN a2enmod rewrite

# Expose port
EXPOSE 80

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

Creating the Configuration File

Create config.php:

<?php

$config = [
    'dbConnection' => [
        'class' => 'yii\db\Connection',
        'dsn' => 'mysql:host=' . getenv('DB_HOST') . ';dbname=' . getenv('DB_NAME'),
        'username' => getenv('DB_USER'),
        'password' => getenv('DB_PASSWORD'),
        'charset' => 'utf8mb4',
    ],
    'siteSubdomain' => null,
    'salt' => getenv('ANTRAGSGRUEN_SALT'),
    'prettyUrl' => true,
    'multisiteMode' => false,
    'domainPlain' => getenv('DOMAIN_PLAIN') ?: 'https://your-app.klutch.sh',
    'domainSubdomain' => null,
    'confirmEmailAddresses' => true,
    'mailFromEmail' => getenv('MAIL_FROM') ?: 'noreply@your-domain.com',
    'mailFromName' => 'Antragsgruen',
];

return $config;

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
tests/

Environment Variables Reference

Variable	Required	Default	Description
`DB_HOST`	Yes	-	MySQL database hostname
`DB_NAME`	Yes	-	Database name
`DB_USER`	Yes	-	Database username
`DB_PASSWORD`	Yes	-	Database password
`ANTRAGSGRUEN_SALT`	Yes	-	Random salt for security (generate with openssl rand -hex 32)
`DOMAIN_PLAIN`	No	-	Your instance’s public URL
`MAIL_FROM`	No	-	Email sender address

Deploying Antragsgruen on Klutch.sh

Generate Security Salt

Generate a random salt for security:

openssl rand -hex 32

Save this value for the environment variables configuration.

Set Up a Database

Provision a MySQL or MariaDB database. You can use Klutch.sh’s database services or an external provider.

Push Your Repository to GitHub

Initialize and push your repository with the Dockerfile and configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project called “antragsgruen”.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 80

Set Environment Variables

Configure the following environment variables:

Variable	Value
`DB_HOST`	Your database hostname
`DB_NAME`	`antragsgruen`
`DB_USER`	Your database username
`DB_PASSWORD`	Your database password
`ANTRAGSGRUEN_SALT`	Your generated salt
`DOMAIN_PLAIN`	`https://your-app-name.klutch.sh`

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/var/www/html/runtime`	5 GB	Runtime files and cache
`/var/www/html/web/assets`	2 GB	Compiled assets
`/var/www/html/web/uploads`	10 GB	Uploaded documents

Deploy Your Application

Click Deploy to start the build process.

Run Database Migrations

After deployment, access the container and run migrations to set up the database schema.

Access Antragsgruen

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

Initial Configuration

Creating Your First Consultation

Access your Antragsgruen instance
The installation wizard will guide you through initial setup
Create an administrator account
Set up your first consultation (conference/assembly)

Configuring Motion Types

Define the types of motions your organization uses:

Resolutions: Standard motions for voting
Amendments: Changes to existing motions
Applications: Candidate applications or proposals
Statutes: Constitutional or bylaw changes

Setting Up User Authentication

Antragsgruen supports multiple authentication methods:

Local user accounts with email verification
Organization-based registration
SAML/SSO integration for enterprise environments

Defining Workflows

Configure the motion lifecycle:

Submission Phase: Accept new motions and amendments
Review Phase: Screen and categorize submissions
Discussion Phase: Allow comments and modifications
Voting Phase: Conduct formal voting
Resolution Phase: Finalize adopted motions

Managing an Assembly

Before the Event

Set submission deadlines
Configure automatic numbering
Generate draft motion books
Test voting functionality

During the Event

Monitor live submissions
Process amendments in real-time
Conduct electronic voting
Display results on projectors

After the Event

Generate final motion books
Export adopted resolutions
Archive the consultation
Generate participation reports

PDF Generation

Motion Books

Antragsgruen automatically generates professional PDF documents:

Complete motion books with all submissions
Amendment comparisons with diffs
Voting sheets for paper ballots
Resolution summaries

Customizing Templates

Customize PDF output with your organization’s branding through the admin interface.

Troubleshooting

Database Connection Errors

Verify database credentials in environment variables
Ensure the database server is accessible
Check that the database exists and migrations have run

PDF Generation Failing

Verify LaTeX packages are installed
Check file permissions in the runtime directory
Review error logs for specific issues

Email Not Sending

Configure SMTP settings in the admin panel
Verify the mail server is accessible
Check spam filters for outgoing mail

Performance Issues

Enable caching for large consultations
Optimize database queries
Consider upgrading Klutch.sh resources during events

Additional Resources

Conclusion

Deploying Antragsgruen on Klutch.sh gives democratic organizations a powerful platform for managing motions, amendments, and voting during assemblies. With automatic HTTPS, persistent storage, and scalable resources, you can confidently host large conventions without infrastructure concerns.

The combination of structured workflows, collaborative editing, and professional PDF generation makes Antragsgruen an invaluable tool for transparent decision-making. Whether you’re running a small committee meeting or a large party convention, Antragsgruen on Klutch.sh provides the foundation for democratic participation.