---
name: antragsgruen-project
description: Antragsgrün (motion.tools) recipe for open-forge. Motion and amendment management for political/organisational assemblies. PHP + MySQL, package or source install. Based on upstream README at https://github.com/CatoTH/antragsgruen.
---

# Antragsgrün (motion.tools)

Web application for managing motions, amendments, and candidacies for political parties, councils, and organisations. Used by the German Green Party, German Federal Youth Council, Austrian NEOS, and others. PHP/Yii2, MySQL. AGPL-3.0. Upstream: https://github.com/CatoTH/antragsgruen. Hosted versions: https://antragsgruen.de (German), https://motion.tools (English).

## Compatible install methods

| Method | When to use |
|---|---|
| Pre-bundled package (zip/bzip2) | Recommended for production; no build tooling needed |
| Source install (Composer + npm) | Development or customisation |
| Docker (community image) | Containerised; via upstream `tobiashoessl/antragsgruen` or community `devopsansiblede/antragsgruen` |

## Inputs to collect

| Phase | Prompt | Format | Notes |
|---|---|---|---|
| preflight | "Package, source, or Docker install?" | Package / Source / Docker | Drives which section |
| database | "MySQL host / name / user / password?" | Four values | Required |
| config | "Base URL for the install?" | URL | e.g. https://motions.example.com/antragsgruen/ |
| config | "Admin email?" | email | Set during web installer |
| config | "Admin password?" | Free-text (sensitive) | Set during web installer |
| smtp | "SMTP config?" | host, port, user, pass | For notification emails |

## Software-layer concerns

| Concern | Detail |
|---|---|
| Language | PHP >= 8.2 (8.4+ recommended) |
| Database | MySQL 5.7+ or MariaDB 10.x |
| Web server | Apache or nginx |
| PHP extensions | php-intl, php-json, php-gd, php-mysql, php-opcache, php-curl, php-xml, php-mbstring, php-zip |
| Config file | config/config.json — generated by web installer |
| Writable dirs | runtime/, web/assets/ |
| Web-based updater | Built-in update mechanism in admin panel |

## Install: Pre-bundled package (recommended)

Source: https://github.com/CatoTH/antragsgruen/blob/master/README.md#using-the-pre-bundled-package

### 1. Install PHP dependencies

```bash
# Debian/Ubuntu
sudo apt-get install php8.4 php8.4-cli php8.4-fpm php8.4-intl php8.4-gd \
  php8.4-mysql php8.4-opcache php8.4-curl php8.4-xml php8.4-mbstring php8.4-zip php8.4-iconv
```

### 2. Download the latest release

Download the latest ZIP or BZIP2 package from https://github.com/CatoTH/antragsgruen/releases/latest

```bash
cd /var/www/html
wget https://github.com/CatoTH/antragsgruen/releases/download/v4.x.x/antragsgruen4.x.x.zip
unzip antragsgruen*.zip
mv antragsgruen-4.x.x antragsgruen
```

### 3. Set permissions

```bash
chown -R www-data:www-data /var/www/html/antragsgruen
chmod -R 755 /var/www/html/antragsgruen
chmod -R 775 /var/www/html/antragsgruen/runtime
chmod -R 775 /var/www/html/antragsgruen/web/assets
```

### 4. Web server config

nginx example (see https://github.com/CatoTH/antragsgruen/blob/master/docs/nginx.sample_single_site.conf):

```nginx
server {
    listen 80;
    server_name motions.example.com;
    root /var/www/html/antragsgruen/web;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.4-fpm.sock;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }
}
```

Apache sample: https://github.com/CatoTH/antragsgruen/blob/master/docs/apache.sample.conf

### 5. Web-based installer

Create the installer trigger file:
```bash
touch /var/www/html/antragsgruen/config/INSTALLING
```

Visit http://motions.example.com/ and follow the installer. It will:
- Verify PHP extensions
- Configure the database connection
- Set admin credentials
- Write config/config.json

### 6. Create MySQL database

```sql
CREATE DATABASE antragsgruen CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'antragsgruen'@'localhost' IDENTIFIED BY 'changeme';
GRANT ALL PRIVILEGES ON antragsgruen.* TO 'antragsgruen'@'localhost';
FLUSH PRIVILEGES;
```

## Install: Source

Source: https://github.com/CatoTH/antragsgruen/blob/master/README.md#from-the-sources

```bash
git clone https://github.com/CatoTH/antragsgruen.git
cd antragsgruen
curl -sS https://getcomposer.org/installer | php
./composer.phar global require "fxp/composer-asset-plugin:1.4.6"
./composer.phar install --prefer-dist
npm install
npm run build
touch config/INSTALLING
```

Visit the app to run the web installer.

## Install: Docker

Upstream-provided Docker image (`tobiashoessl/antragsgruen`); see the [docker-compose.yml](https://github.com/CatoTH/antragsgruen/blob/master/docker-compose.yml) in the main repo for usage.

```bash
# Clone the repo to get the docker-compose.yml
git clone https://github.com/CatoTH/antragsgruen.git
cd antragsgruen
docker compose start
docker exec antragsgruen-web-1 /root/enable-installer.sh   # enable installer
# Visit http://localhost:12380/ to complete installation
```

Alternative community image: `devopsansiblede/antragsgruen` ([devops-ansible/docker-antragsgruen](https://github.com/devops-ansible/docker-antragsgruen)) — rebuilt weekly, tracks upstream releases.

## Upgrade procedure

### Web-based updater (recommended)

1. Log in as site admin
2. Go to the administration page — an Update box shows if a new version is available
3. Enable Update Mode (site goes offline for other users)
4. Visit /update.php as admin and follow the steps:
   - Download update file
   - Install new files
   - Apply database updates (required when upgrading minor versions)

Always back up database and files before upgrading.

### Manual upgrade

```bash
# Download new package, extract
# Overwrite all files EXCEPT config/config.json
# Run database migrations via web updater or CLI
```

## Gotchas

- PHP extensions required: Missing php-intl or php-mbstring causes startup errors. Verify all extensions with `php -m`.
- config/INSTALLING must exist for installer: Without this file, visiting the app after a fresh install shows an error instead of the installer.
- runtime/ and web/assets/ must be writable: Yii2 uses these for caching and generated assets. Incorrect permissions cause 500 errors.
- Web updater puts site in maintenance mode: Inform users before starting an update; the site is unavailable during the update process.
- Multi-site support: A single Antragsgrün install can host multiple consultations under one domain. Configuration is done through the admin UI.

## Links

- GitHub: https://github.com/CatoTH/antragsgruen
- Releases: https://github.com/CatoTH/antragsgruen/releases/latest
- nginx sample config: https://github.com/CatoTH/antragsgruen/blob/master/docs/nginx.sample_single_site.conf
- Apache sample config: https://github.com/CatoTH/antragsgruen/blob/master/docs/apache.sample.conf
- Update troubleshooting: https://github.com/CatoTH/antragsgruen/blob/master/docs/update-troubleshooting.md
- Docker image (upstream): https://hub.docker.com/r/tobiashoessl/antragsgruen
- Docker image (community alt): https://github.com/devops-ansible/docker-antragsgruen
- Hosted (German): https://antragsgruen.de
- Hosted (English): https://motion.tools
