Inhaltsverzeichnis

Installation der Middleware

This installs the middleware and the frontend. You also need to install the logger (vzlogger).

Voraussetzungen

Es eignen sich hier Debian oder Ubuntu, sowie für den Raspberry Pi: Raspbian oder Raspbian Light.(„Bullseye“-Version mit PHP 7.4 oder „Bookworm“ mit PHP 8.2)
Die Abhängigkeiten lassen sich schnell mit folgendem Befehl installieren:

sudo apt-get install git php-cli php-mysql php-apcu mariadb-server mariadb-client php-xml php-mbstring php-opcache php-common ca-certificates zip unzip php-zip apt-transport-https php-curl apache2

Für die manuelle Installation wird zudem „curl“ benötigt.

Vollautomatisiert mit Ansible und DebOps

Siehe hierzu debops-contrib.volkszaehler.

Install-Skript (empfohlene Methode)

wget https://raw.github.com/volkszaehler/volkszaehler.org/master/bin/install.sh
bash install.sh

Das sollte dann ablaufen: [Bitte unbedingt ein Passwort für den vz-admin-User vergeben!]

pi@raspberrypi:~ $ bash install.sh
volkszaehler.org installation script

checking prerequisites: php: /usr/bin/php
 mysql: /usr/bin/mysql
 awk: /usr/bin/awk
 sed: /bin/sed
 grep: /bin/grep
 wget: /usr/bin/wget
 mktemp: /bin/mktemp
 mkdir: /bin/mkdir
 git: /usr/bin/git

checking php version: 7.3.3-1 >= 7.1, ok

volkszaehler setup...
volkszaehler path? [/home/pi/volkszaehler.org]
git clone volkszaehler.org into /home/pi/volkszaehler.org
Cloning into '/home/pi/volkszaehler.org'...
remote: Enumerating objects: 4, done.
remote: Counting objects: 100% (4/4), done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 11981 (delta 0), reused 0 (delta 0), pack-reused 11977
Receiving objects: 100% (11981/11981), 7.51 MiB | 752.00 KiB/s, done.
Resolving deltas: 100% (6760/6760), done.
link from webserver to volkszaehler directory? [/var/www/volkszaehler.org]
linking /var/www/volkszaehler.org to /home/pi/volkszaehler.org

checking composer...
composer: /usr/local/bin/composer

installing dependencies...
~/volkszaehler.org ~
Loading composer repositories with package information
Updating dependencies
Package operations: 52 installs, 0 updates, 0 removals
  - Installing symfony/routing (v4.2.4): Downloading (100%)
  - Installing symfony/polyfill-mbstring (v1.11.0): Downloading (100%)
  - Installing symfony/http-foundation (v4.2.4): Downloading (100%)
  - Installing ralouphie/getallheaders (2.0.5): Downloading (100%)
  - Installing psr/http-message (1.0.1): Downloading (100%)
  - Installing guzzlehttp/psr7 (1.5.2): Downloading (100%)
  - Installing react/promise (v2.7.1): Downloading (100%)
  - Installing react/event-loop (v1.1.0): Downloading (100%)
  - Installing react/promise-timer (v1.5.0): Downloading (100%)
  - Installing evenement/evenement (v3.0.1): Downloading (100%)
  - Installing react/stream (v1.1.0): Downloading (100%)
  - Installing react/cache (v0.5.0): Downloading (100%)
  - Installing react/dns (v0.4.16): Downloading (100%)
  - Installing react/socket (v1.2.0): Downloading (100%)
  - Installing ratchet/rfc6455 (0.2.4): Downloading (100%)
  - Installing cboden/ratchet (v0.4.1): Downloading (100%)
  - Installing symfony/contracts (v1.0.2): Downloading (100%)
  - Installing symfony/console (v4.2.4): Downloading (100%)
  - Installing doctrine/instantiator (1.2.0): Downloading (100%)
  - Installing doctrine/event-manager (v1.0.0): Downloading (100%)
  - Installing doctrine/cache (v1.8.0): Downloading (100%)
  - Installing doctrine/dbal (v2.9.2): Downloading (100%)
  - Installing doctrine/lexer (v1.0.1): Downloading (100%)
  - Installing doctrine/annotations (v1.6.0): Downloading (100%)
  - Installing doctrine/reflection (v1.0.0): Downloading (100%)
  - Installing doctrine/collections (v1.6.0): Downloading (100%)
  - Installing doctrine/persistence (v1.1.0): Downloading (100%)
  - Installing doctrine/inflector (v1.3.0): Downloading (100%)
  - Installing doctrine/common (v2.10.0): Downloading (100%)
  - Installing doctrine/orm (v2.6.3): Downloading (100%)
  - Installing symfony/polyfill-ctype (v1.11.0): Downloading (100%)
  - Installing symfony/yaml (v4.2.4): Downloading (100%)
  - Installing guzzlehttp/promises (v1.3.1): Downloading (100%)
  - Installing guzzlehttp/guzzle (6.3.3): Downloading (100%)
  - Installing influxdb/influxdb-php (1.14.7): Downloading (100%)
  - Installing symfony/event-dispatcher (v4.2.4): Downloading (100%)
  - Installing andig/dbcopy (1.3): Downloading (100%)
  - Installing andig/php-shunting-yard (1.0.2): Downloading (100%)
  - Installing react/promise-stream (v1.1.1): Downloading (100%)
  - Installing ringcentral/psr7 (1.2.2): Downloading (100%)
  - Installing react/http (v0.8.4): Downloading (100%)
  - Installing http-interop/http-middleware (0.5.0): Downloading (100%)
  - Installing psr/log (1.1.0): Downloading (100%)
  - Installing symfony/debug (v4.2.4): Downloading (100%)
  - Installing symfony/http-kernel (v4.2.4): Downloading (100%)
  - Installing paragonie/random_compat (v9.99.99): Downloading (100%)
  - Installing monolog/monolog (1.24.0): Downloading (100%)
  - Installing react/child-process (v0.5.2): Downloading (100%)
  - Installing symfony/process (v4.2.4): Downloading (100%)
  - Installing php-pm/php-pm (1.0.5): Downloading (100%)
  - Installing php-pm/httpkernel-adapter (1.0.6): Downloading (100%)
  - Installing webpatser/laravel-uuid (3.0.2): Downloading (100%)
Package http-interop/http-middleware is abandoned, you should avoid using it. Use http-interop/http-server-middleware instead.
Writing lock file
Generating autoload files
~

volkszaehler.org is not configured yet. creating new config from sample config file.
mysql root user? [root]
mysql root password? [] raspberry
mysql database? [volkszaehler]
mysql admin to volkszaehler database? [vz-admin]
mysql admin password? [] secure
mysql user? [vz]
mysql password? [demo]

create volkszaehler.org database and admin user? [y]
creating database volkszaehler...
Enter password: {root password (raspberry)}
creating db user vz-admin...
Enter password: {root password (raspberry)}
creating database schema...
~/volkszaehler.org ~

 !
 ! [CAUTION] This operation should not be executed in a production environment!
 !

 Creating database schema...


 [OK] Database schema created successfully!



 Processing entity "Volkszaehler\Model\Aggregate"
 Processing entity "Volkszaehler\Model\Entity"
 Processing entity "Volkszaehler\Model\Channel"
 Processing entity "Volkszaehler\Model\Property"
 Processing entity "Volkszaehler\Model\Aggregator"
 Processing entity "Volkszaehler\Model\Data"

 Proxy classes generated to "/home/pi/volkszaehler.org/lib/Model/Proxy"
~

create volkszaehler.org database user? [y]
creating db user vz with proper rights...

allow channel deletion? [n] y
granting db user vz delete rights...

insert demo data in to database? [n]

Das Script fragt, was es wohin installieren soll.

Webserver einrichten

Im Folgenden sind 3 mögliche Serverkonfigurationen beschrieben. Für Kompatibiltät mit alten Scripts und Konfigurationen empfehlen wir bei PPM zusätzlich einen Proxy einzurichten.

PPM als Server (empfohlene Methode)

Der PPM-Webserver auf Basis von PHP läuft wesentlich Performanter als Apache2 und ist gerade auf schwacher Hardware wie RaspberryPi zu empfehlen. In Standardkonfiguration bedient er Anfragen auf Port 8080.

  1. Systemd Service einrichten sudo nano /etc/systemd/system/middleware.service
    [Unit]
    Description=Volkszaehler.org Middleware
    After=syslog.target network.target mysql.service
    Requires=
    
    [Service]
    ExecStart=/usr/bin/php /var/www/volkszaehler.org/vendor/bin/ppm start -c /var/www/volkszaehler.org/etc/middleware.json --cgi-path=/usr/bin/php
    ExecReload=/bin/kill -HUP $MAINPID
    StandardOutput=journal
    Restart=always
    
    [Install]
    WantedBy=multi-user.target 
  2. Server Konfiguration anpassen
    1. nano ~/volkszaehler.org/etc/middleware.json
    2. ändern: „static-directory“: „/var/www/volkszaehler.org/htdocs“,
  3. Middleware Weiterleitung url anpassen nano ~/volkszaehler.org/htdocs/js/options.js
    title: 'Local (default)',
    url: ''
    //live: 8082
  4. Systemd Service bei boot aktiveren sudo systemctl enable middleware
  5. Systemd Service starten sudo systemctl start middleware
Wird kein Proxy installiert, wie in den nächsten Sektionen empfohlen, gibt es den Pfad http://localhost/middleware.php nicht, der in vielen Beispielkonfigurationen auf dieser Webseite verwendet wird! Stattdessen muss http://localhost/ verwendet werden.

Apache als Proxy (empfohlene Methode)

Dazu Apache auf die Weiterleitung zum PPM reduzieren.

  1. Module aktivieren
    sudo a2enmod proxy
    sudo a2enmod proxy_http
    sudo a2enmod rewrite
  2. Rewrite-Proxy aktivieren, nano ~/volkszaehler.org/htdocs/.htaccess. Die Kommentarzeichen vor den Zeilen entfernen und Zeile 16 hinzufügen:
    <IfModule mod_proxy.c>
    	RewriteEngine On
    	RewriteRule ^middleware(.php)?(/.*)? http://localhost:8080$2 [P]
    	RewriteRule ^api(/.*)? http://localhost:8080$1 [P]
            RewriteRule (.*) http://localhost:8080/$1 [P]
    </IfModule>
  3. Default VirtualHost bearbeiten: sudo nano /etc/apache2/sites-enabled/000-default.conf. Dort < DocumentRoot > suchen und ändern:
            DocumentRoot /var/www/volkszaehler.org/htdocs/
  4. Apache Config bearbeiten um Rewrite in .htaccess zu erlauben: sudo nano /etc/apache2/apache2.conf In der Datei den Abschnitt suchen:
    <Directory /var/www/>
            Options Indexes FollowSymLinks
            AllowOverride None
            Require all granted
    </Directory>

    AllowOverride None in AllowOverride All AuthConfig ändern.

  5. Dann den Apache nur noch neu starten sudo systemctl restart apache2

Alternativ: nginx als Proxy

Nginx ist ein schlanker Webserver/Proxy dessen Konfiguration sehr zentral erfolgt, was der Performance zu gute kommt. Er ist als Proxy für den Betrieb eines Volkszählers nicht zwingend nötig (PPM kann das gut alleine), bietet aber Abwärtskompatibilität für bestehende Scripte und Anwendungen.

sudo apt install nginx
sudo rm /etc/nginx/sites-enabled/default
sudo nano /etc/nginx/sites-available/volkszaehler

In diese wird eingefügt:

# Volkszaehler

include /etc/nginx/proxy_params;

server {
  listen 80;
  listen [::]:80;
  server_name volkszaehler.org;

  location / {
    proxy_pass http://127.0.0.1:8080;
    include /etc/nginx/proxy_params;
  }

  location /middleware {
    rewrite ^/middleware(.php)?(/.*)? $2;
    proxy_pass http://127.0.0.1:8080/;
  }

  location /api {
    rewrite ^/api(/.*)? $1;
    proxy_pass http://127.0.0.1:8080/;
  }

  location /frontend {
    rewrite ^/frontend/(.*) $1;
    proxy_pass http://127.0.0.1:8080/;
  }

# Konfigurationsbeispiel für eigene PHP-Scripte,
# von nginx unter http://127.0.0.1/addapp/ bereitgestellt, lokal unter /var/www/html/ abgelegt.
#
#  location /addapp/ {
#    alias /var/www/html/;
#    index index.nginx-debian.html;
#      
#    location ~ \.php {
#      include snippets/fastcgi-php.conf;
#      fastcgi_param SCRIPT_FILENAME $request_filename;
#      fastcgi_pass unix:/var/run/php/php7.3-fpm.sock;
#    }
#  }
}
Möchte man eigene PHP-Scripte neben Volkszähler bereit stellen ist das das Paket php-fpm nötig.

Installieren mit sudo apt-get install php-fpm und darauf achten das in der nginx-Konfiguration bei /var/run/php/php7.3-fpm.sock auf die korrekte, vorhandene Datei verwiesen wird.

Damit der nginx die Config lädt:

sudo ln -s /etc/nginx/sites-available/volkszaehler /etc/nginx/sites-enabled/volkszaehler

Dann nur noch Starten und in Bootprozess einbinden:

sudo systemctl start nginx
sudo systemctl enable nginx

Alternativ: Apache als Server (unter Debian "Stretch")

Möchte man von PPM auf Apache als Server umstellen sind auch die Änderungen an der Middleware-Konfiguration für PPM zurück zu nehmen: url: 'api'

' In der Datei, neben < DocumentRoot > eintragen:

 /var/www/volkszaehler.org/htdocs/
<Directory /var/www/>
        Options Indexes FollowSymLinks
        AllowOverride None
        Require all granted
</Directory>

Nach dem editieren und abspeichern der Datei sudo systemctl restart apache2 ausführen.

Sollte es zu einem PHP Fehler beim Anlegen der Datenbank kommen versucht mal Doctrine per Hand zu Installieren.

Alternativ: nginx als Server

Möchte man von PPM auf nginx als Server umstellen sind auch die Änderungen an der Middleware-Konfiguration für PPM zurück zu nehmen: url: 'api' .
server {
        listen 80;
        listen [::]:80;
        server_name volkszaehler.org;

        root /var/www/volkszaehler.org/htdocs;

        index index.php index.html;

        location / {
                try_files $uri $uri/ =404;
        }
        location ~ \.php {
                include snippets/fastcgi-php.conf;
        #       # With php7-cgi alone:
        #       fastcgi_pass 127.0.0.1:9000;
                # With php7-fpm:
                fastcgi_pass unix:/var/run/php/php7.3-fpm.sock;
        }
}
Darauf achten das in der nginx-Konfiguration bei /var/run/php/php7.3-fpm.sock auf die korrekte, vorhandene Datei verwiesen wird.

Wichtig ist dass in der config in der Zeile „location ~ \.php {“ kein $-Zeichen hinter dem PHP steht. Siehe Mail Archiv

Alternativ: Lighttpd als Server

Notwendige Rewrite-Regeln:

    url.rewrite-if-not-file = (
        "^/(?:middleware|api)(/.*)?" => "/middleware.php$1",
	"^/frontend/(.*)" => "$1"
    )

Manuelle Installation

Download der volkszaehler.org Skripte

Download der Skripte aus dem git Repository:

git clone git://github.com/volkszaehler/volkszaehler.org.git ~/volkszaehler.org
sudo ln -sf ~/volkszaehler.org /var/www/volkszaehler.org
sudo chown -R www-data /var/www/volkszaehler.org

Installation der benötigten Module

Zunächst PHP Paketmanager Composer von getcomposer.org installieren
cd /tmp
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
sudo chmod +x /usr/local/bin/composer
Ahängigkeiten laden und installieren (v.a. Doctrine)
cd /var/www/volkszaehler.org/ # Anmerkung: ansonsten wird die Datei "composer.json" nicht gefunden; Fehlermeldung: "Composer could not find a composer.json file..."
composer install

Konfiguration der Middleware

cd /var/www/volkszaehler.org/etc/
cp config.dist.yaml config.yaml

edit config.yaml:

db:
  host: 127.0.0.1
  port: 3306
  user: vz
  password: demo
  dbname: volkszaehler

Alternativ wird die Installation in der Doctrine Dokumentation beschrieben. Falls du also Probleme bei der Installation haben solltest, kannst du dir hier noch ein paar Informationen holen.

Datenbank konfigurieren

mysql:
    CREATE DATABASE `volkszaehler`;
    
oder phpmyadmin:
    Home -> "Datenbank anlegen", Name: "volkszaehler" -> "Anlegen"  ​
mysql:
    GRANT ALL ON volkszaehler.* to 'vz_admin'@'localhost' IDENTIFIED BY '<shhhh!>' WITH GRANT OPTION;
    CREATE USER 'vz'@'localhost' IDENTIFIED BY '<shhhh!>';
    GRANT USAGE ON volkszaehler.* TO 'vz'@'localhost';
    GRANT SELECT, UPDATE, INSERT ON volkszaehler.* TO 'vz'@'localhost';
        
oder phpmyadmin:
    Home -> "Rechte" -> "Neuen Benutzer hinzufügen"
        Benutzername: vz_admin
        Host: localhost
        Passwort: <shhh!>
        Vollzugriff (Grant All) auf DB volkszaehler erlauben.
        -> ok
    Home -> "Rechte" -> "Neuen Benutzer hinzufügen"
        Benutzername: vz
        Host: localhost
        Passwort: <shhh!>
        keine globalen Rechte vergeben!
        -> ok

* Tabellen anlegen:

# cd /var/www/volkszaehler.org/
# php bin/doctrine orm:schema-tool:create
ATTENTION: This operation should not be executed in a production environment.

Creating database schema...
Database schema created successfully!
      Tabelle "entities" auswählen (unbedingt zuerst diese importieren!)
      "Importieren"; das Gleiche mit "properties" und "data"

oder:

      cd /var/www/volkszaehler.org/misc/sql
      cat entities.sql properties.sql data-demoset1.sql | mysql -uroot volkszaehler -p
Datenbank "mysql", Tabelle "tables_priv":
    "Einfügen": 
        Host: "localhost"
        Db: "volkszaehler"
        User: "vz"
        Table_name: "data" (anschließend das Gleiche mit "entities", "entities_in_aggregator", "properties", "tokens"
        Table_priv: "select", "update" und "insert"
        
oder:
        GRANT select, update, insert ON volkszaehler.* TO vz@localhost;
mysqladmin password -u root "<neues, gutes passwort>"
mysqladmin reload -p

Webserver

Wie bereits weiter oben beschrieben.

Aktualisierung der Middleware einschließlich des Frontends

Wenn nur die ./etc/config.yaml angepasst kann wieder das Installationsskript von oben verwendet werden. Da die Datenbank vermutlich nicht angetastet werden soll, die entsprechenden Fragen einfach verneinen.

Nachdem Volkszähler im Zuge der Installation eine Kopie des git Repositories erstellt, kann die Installation aber auch aus diesem Repository aktualisiert werden. Eine Beschreibung findet sich im Kapitel zu git. Beim Image ist dies der notwendige Weg weil da auch andere Dateien editiert wurden.

phpMyAdmin installieren

Statt phpMyAdmin empfehlen wir derzeit einen lokalen Client wie z.B. HeidiSQL
Für Vollzugriff auf die Volkszählerdatenbank über phpMyAdmin haben wir den User vz-admin. Standardpasswort: secure

MySQL-Superuser ist: root und das Standardpasswort: raspberry
phpMyAdmin-Superuser ist: phpmyadmin und das Standardpasswort: raspberry

Debian Stretch

sudo apt-get install phpmyadmin

Nach Installation der nötigen Pakete wird das Konfigurationsscript gestartet. Es konfiguriert Apache und fragt nach einem Passwort für den neu anzulegenden User phpmyadmin.

Wenn kein Passwort vergeben wird kann das Fehlfunktionen zur Folge haben

Auch Apache wird automatisch neu gestartet.

Unter Stretch kann man sich in MySQL nur als root anmelden wenn man lokal als root agiert (sudo).
Von und für phpMyAdmin ist deswegen der User phpmyadmin angelegt worden.

Um dem neuen User volle Adminrechte zu gewähren:

sudo mysql -uroot -praspberry --execute "grant all privileges on *.* to 'phpmyadmin'@'localhost' with grant option"