Managing motions and amendments for political conventions
PHP Java JavaScript CSS TypeScript HTML
Clone or download
Latest commit 00e64f5 Jul 17, 2018
Permalink
Failed to load latest commit information.
assets Add .htaccess files for installations that do not set the document ro… Jul 1, 2018
commands Add .htaccess files for installations that do not set the document ro… Jul 1, 2018
components Set the visibility in search engines Jul 11, 2018
config v4.0.0rc5 Jul 13, 2018
controllers User events; confirm sites after account confirmation Jul 14, 2018
docs Update package Jul 8, 2018
messages Updates, message strings Jul 17, 2018
migrations Add .htaccess files using build script Jul 1, 2018
models User events; confirm sites after account confirmation Jul 14, 2018
plugins Adapt textes for discuss.green Jul 14, 2018
runtime Separate motion list from settings page Apr 10, 2016
tests Add .htaccess files for installations that do not set the document ro… Jul 1, 2018
views Bugfix: creating a motion type when no other one existed before Jul 13, 2018
web Layout-Tweaks Jul 13, 2018
.gitignore Update FPDI-PDF, support the commercial plugin Jun 12, 2018
.htaccess More work on subdirectory deployment Sep 4, 2015
AUTHORS French translation strings by Antoine Jun 5, 2017
History.md Set the visibility in search engines Jul 11, 2018
LICENCE LICENCE / AUTHORS Oct 29, 2015
README.md v4.0.0rc5 Jul 13, 2018
codeception.yml Use selenium / chromedriver for testing Apr 18, 2017
composer.json Library updates Jun 28, 2018
composer.lock Updates, message strings Jul 17, 2018
gulpfile.js Maximize agenda field, improve scss-watcher Jun 21, 2018
index.php More work on subdirectory deployment Sep 4, 2015
package-lock.json Refactoring content editing Jun 9, 2018
package.json Refactoring content editing Jun 9, 2018
tsconfig.json Begin migration to Typescript, remove Babel Dec 18, 2016
yii Initial Commit v3 Jan 25, 2015

README.md

Antragsgrün

The Online Motion Administration/Facilitator for Associations Conventions, General Assemblies and Party Conventions.

Antragsgrün offers a clear and efficient tool for the effective administration of motions, amendments and candidacies: from submission to administration and print template.

A number of organisations are already using the tool successfully such as the federal association of the German Green Party or the German Federal Youth Council. It can be easily adapted to a variety of scenarios.

Core functions:

  • Submit motions, proposals and discussion papers online
  • Clear amendment
  • Submitted amendments are displayed directly in the relevant text section.
  • Discuss motions
  • Sophisticated administration tools
  • Diverse export options
  • Great flexibility - it adapts to a lot of different use cases
  • Technically mature, data privacy-friendly

Using the hosted version / testing it

Installation

Using the pre-bundled package

Requirements:

  • A MySQL-database
  • PHP >= 5.6. Recommended: 7.2. Required packages for Debian Linux:
# Using PHP7-packages from [deb.sury.org](https://deb.sury.org/):
apt-get install php7.2 php7.2-cli php7.2-fpm php7.2-intl php7.2-json php7.2-gd \
                php7.2-mysql php7.2-opcache php7.2-curl php7.2-xml php7.2-mbstring php7.2-zip
  • Apache or nginx. Example files are provided here:
    • Example configuration for nginx
    • Example configuration for apache

Installation:

  • Download the latest package of Antragsgrün: antragsgruen-4.0.0rc5.tar.bz2
  • Extract the contents into your web folder
  • Access the "antragsgruen/"-folder of your web server, e.g. if you extracted the package into the web root of your host named www.example.org/, then access www.example.org/antragsgruen/
  • Use the web-based installer to configure the database and further settings

From the sources

Install the sources and dependencies from the repository:

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.4"
./composer.phar install --prefer-dist
npm install
npm run build

If you want to use the web-based installer (recommended):

touch config/INSTALLING

If you don't want to use the web-based installer:

cp config/config.template.json config/config.json
vi config/config.json # you're on your own now :-)

Set the permissions (example for Debian Linux):

sudo chown -R www-data:www-data web/assets
sudo chown -R www-data:www-data runtime
sudo chown -R www-data:www-data config #Can be skipped if you don't use the Installer

Using Docker

A Dockerfile to compile and run the latest development version of Antragsgrün is provided by Jugendpresse Deutschland e.V. at this repository:

https://github.com/jugendpresse/docker-antragsgruen

Updating

Using the web-based updater

Site administrators of an installation will see a Update-Box at the right side of the administration page of a consultation. The box indicates if an update is available. If so, you can switch the whole installation into Update mode. While the update mode is active, the whole site will not be available to other users.

Once the update mode is active, the /update.php script will be available to the site administrator. Here, the update can be performed in two to three steps:

  • Download the update file
  • Install the new files
  • Apply database updates (this is usually only necessary when upgrading to a new minor version, e.g. from 3.9 to 3.10.)

Before using the updater, it is generally a good idea to back up all files and especially the database.

If you encounter any problem using the web-based updater, please consult the Update Troubleshooting FAQ.

Using the pre-bundled package

  • Download the latest package of Antragsgrün (see "Installation")
  • Extract the files to your web folder, overwriting all existing files. The configuration (in config/config.json) will not be affected by this.
  • Remove the config/INSTALLING file
  • If you have shell access to your server: execute ./yii migrate on the command line to apply database changes
  • If you don't have shell access to your server: please refer to UPGRADING.md on how to upgrade your database

Deployment techniques

LaTeX/XeTeX-based PDF-rendering:

Necessary packets on Linux (Debian):

apt-get install texlive-lang-german texlive-latex-base texlive-latex-recommended \
                texlive-latex-extra texlive-humanities texlive-fonts-recommended \
                texlive-xetex poppler-utils

Necessary packets on Mac OS X:

Add the following settings to your config.json (and adapt them to your needs):

{
    "xelatexPath": "/usr/bin/xelatex",
    "xdvipdfmx": "/usr/bin/xdvipdfmx",
    "pdfunitePath": "/usr/bin/pdfunite"
}

FPDI-PDF

If you run into the error "This PDF document probably uses a compression technique which is not supported by the free parser shipped with FPDI. (See https://www.setasign.com/fpdi-pdf-parser for more details)" and decide to use the commercial plugin, you can install the package using the following steps:

  • Extract the content of the package into the directory components/fpdi, so there exists a sub-directory src.
  • Run the command ./composer.phar dump-autoload

After that, newer PDF files should be able to be parsed as well.

Multisite-Mode

There are two ways to deploy multiple sites using one codebase, each site allowing multiple consultations. However, both of them are non-trivial.

Using a completely separate configuration and database

If you want to use two completely different databases, or a different set of active plugins, you can create a separate config.json for each installation and name them like config.db1.json, config.db2.json, etc. Which one is used on a request depends on the environment variable ANTRAGSGRUEN_CONFIGthat is provided to the PHP process. For example, to use config.db1.json on the hostname db1.antragsgruen.local on Apache, you can use the following line in the Apache configuration:

SetEnvIf Host "db1.antragsgruen.local" ANTRAGSGRUEN_CONFIG=/var/www/antragsgruen/config/config.db1.json

For command line commands, you can set this variable like this:

ANTRAGSGRUEN_CONFIG=/var/www/antragsgruen/config/config.db1.json ./yii database/migrate

Using the same database, plugin configuration and a site manager

Antragsgruen.de uses a site manager module on the home page that allows users to create their own sites using a web form. This is done using the multisideMode and a plugin for the site manager. Relevant entries in the config.json for this are:

{
    "multisiteMode": true,
    "siteSubdomain": null,
    "domainPlain": "https://antragsgruen.de/",
    "domainSubdomain": "https://<subdomain:[\\w_-]+>.antragsgruen.de/",
    "plugins": ["antragsgruen_sites"]
}

Instead of "antragsgruen_sites", a custom plugin managing the authentication and authorization process and providing the custom home page is necessary for this use case. The default manager antragsgruen_sites can be used as an example for this

Using Redis

Install the Yii2-Redis-package:

./composer.phar require composer require yiisoft/yii2-redis

Add the following settings to your config.json (and adapt them to your needs):

{
    "redis": {
        "hostname": "localhost",
        "port": 6379,
        "database": 0
    }
}

Command Line Commands

Force a new password for an user:

./yii admin/set-user-password user@example.org mynewpassword

Developing

You can enable debug mode by creating an empty file config/DEBUG.

To compile the JavaScript- and CSS-Files, you need to install Gulp:

npm install # Installs all required packages

npm run build # Compiles the regular JS/CSS-files
npm run watch # Listens for changes in JS/CSS-files and compiles them immediatelly

After updating the source code from git, do:

./composer.phar install
./yii migrate
gulp

Creating custom language variants

Every single message in the user interface can be modified using the web-based translation tool. Just log in as admin and go to Settings / Einstellungen -> Edit the language / Sprache anpassen.

In multi-site-instances, there might be a need to share language variante between different sites. In that case, file-based modifications are necessary:

  • Create a directory messages/en-variant
  • Copy the contents of the base language (messages/en, in this case) to this directory and edit the translated strings. If a string is missing, the messages of the directory named by the first part before the dash will be used as fallback ("en", in this case).
  • Add a localMessages-configuration to your config/config.json as shown below.
  • Now this language variant is selectable in the "Edit the language"-settings-page.
{
    "localMessages": {
        "en": {
            "en-variant": "My new language variant"
        }
    }
}

Plugins

The plugin system is still under heavy development.

  • The plugin system is based on Yii2's module system and asset bundles.
  • Each plugins has a directory under plugins/. It requires at least a Module.php which inherits from ModuleBase.php.
  • Custom URLs can be defined in the Modules.php, the corresponding controllers are in the controller-subdirectory, the views in views, custom commands need to be in a commands-directory. A rather complex exmple containing a bit of everything can be seen in memberPetitions.
  • Each plugin has a unique ID that is equivalent to the name of the directory. To activate a plugin, the ID has to be added to the plugins-list in the config.json:
{
    "plugins": [
        "mylayoutPlugin",
        "someExtraBehavior"
    ]
}

Custom themes as plugin

The most frequent use case for plugins are custom themes / layouts. You can develop a custom theme using SASS/SCSS for Antragsgrün using the following steps:

  • Create a directory for the plugin with a Module.php and Assets.php. If your directory / plugin ID is mylayout, the namespace of these classes needs to be app\plugins\mylayout.
  • The Module.php needs the static method getProvidedLayout that returns the asset bundle. See the gruen_ci or neos for examples.
  • Create a file plugins/mylayout/assets/mylayout.scss. Again, use the existing plugins as an example to get the imports right.
  • Adapt the SCSS variables and add custom styles
  • Run gulp to compile the SCSS into CSS
  • Activate the plugin as said above.
  • Now, you can choose your new theme in the consultation settings

A hint regarding the AGPL license and themes: custom stylesheets and images and changes to the standard stylesheets of Antragsgrün do not have to be redistributed under an AGPL license like other changes to the Antragsgrün codebase.

Testing

Installation

  • Create a separate (MySQL-)database for testing
  • Set up the configuration file: cp config/config_tests.template.json config/config_tests.json && vi config/config_tests.json
  • Download ChromeDriver and move the binary into the PATH (e.g. /usr/local/bin/)
  • Download the Selenium Standalone Server
  • For the automatical HTML validation, Java needs to be installed and the vnu.jar file from the Nu Html Checker located at /usr/local/bin/vnu.jar.
  • For the automatical accessibility validation, Pa11y needs to be installed. (is done by npm install)
  • The host name antragsgruen-test.local must point to localhost (by adding an entry to /etc/hosts) and a VirtualHost in your Apache/Nginx-Configuration pointing to the web/-directory of this installation has to be configured. If another host name is to be used, it has to be changed in the config/TEST_DOMAIN and tests/acceptance.suite.yml.

Running

  • Start Selenium: java -jar selenium-server-standalone-3.13.0.jar
  • Run all acceptance tests: run run test:acceptance
  • Run all unit tests: run run test:unit
  • Run a single acceptence-test: npm run test:acceptance MotionCreateCept

Reporting security issues

If you found a security problem with Antragsgrün, please report it to: tobias@hoessl.eu. If you want to encrypt the mail, you can use this PGP-Key.

Yii2