- zorg Code standalone lokal einrichten
- Am zorg Coding mitwirken
- Neusten Codestand deployen
- Initiales Server-Setup
- Services- und API Integrationen
Rundum sorglos Paket: siehe separates zorg on Docker how-to im /Docker-dir.
Was auch geht ist lokal mittels einem Apache-Webserver mit PHP sowie MySQL. Am effizientesten direkt mittels MAMP (macOS), WAMP (Windows) und LAMP (Linux).
- Current: PHP 7.4.x
- für <= zorg Code 4.0.1: PHP 5.6.37
- Current: MySQL 5.7.x
- für <= zorg Code 4.0.1: MySQL 5.6
Um die MySQL-Datenbank lokal zu konfigurieren & verwalten am besten ein MySQL-Manager verwenden z.B. für macOS mit Sequel Ace.
Ist ++nicht++ zwingend notwendig weil das zorg Code Repository bzw. der Code öffentlich verfügbar ist und daher von jedem heruntergeladen und gecloned werden kann.
Falls Du aktiv am Code mitarbeiten bzw. deine Changes comitten möchtest, benötigst Du einen GitHub-Account und musst zudem in der Kenner-Gruppe auf GitHub hinzugefügt werden. Um diese Berechtigungen zu kriegen nimm bitte Kontakt auf mit kassiopaia, [z]keep3r, IneX oder einem anderen Kenner.
Vorab auf GitHub einen Personal Access Token generieren: GitHub Developer Settings > Personal access tokens
Am einfachsten und mit eingebauten Git ist die Arbeit/Bezug des zorg Codes mit einem Git-Programm wie z.B. Fork zu handhaben (für Windows & macOS).
- Optional kann Git lokal installiert werden wie hier beschrieben
- Danach lokal den globalen Git-User* konfigurieren mittels Terminal/Git Bash (Git benutzt diese globale E-Mail Adresse für alle späteren Commits - aka Code-Einreichungen):
$ git config --global user.name "DEIN USERNAME" $ git config --global user.email "DEINE E-MAIL" $ git config --global user.password GITHUB-DEVELOPER-TOKEN
* Um in das zorg Code Repository comitten zu können muss Du mindestens die gleiche E-Mailadresse, wie verlinkt in deinem GitHub-Account, verwenden!
Am einfachsten klickst Du auf der GitHub Repository-Seite einfach oben rechts auf den grünen "Clone or download"-button – oder Du ziehst Dir den neusten Release von hier und verschiebst alle Files lokal in das gewünschte Webroot vom Apache.
Wenn du dafür zu fest Geek bist, dann...
- Das Terminal-Shell (macOS/Linux) resp. Git Bash (Windows) starten
- Folgenden Befehl ausführen, um das zorg Code Repository direkt von GitHub auf Deinen Computer herunterzuladen:
$ git clone https://github.com/zorgch/zorg-code.git /pfad/zum/lokalen/apache/webroot/
- Im Apache Web-Root (auch "htdocs/" oder "www/") befindet sich jetzt eine Kopie des zorg www-Verzeichnis mit sämtlichen Dateien von zorg.
Bevor zorg aber lokal angezeigt werden kann, musst Du zuerst noch einen Hosts-Eintrag und die Datenbank einrichten!*
Folgende Verzeichnisse brauchst du nach dem lokalen Clone des Git-Repositories.
Das /data/-Verzeichnis ist unverzichtbar für zorg.ch, aber unterliegt nicht der Git-Codeversionierung!
/zorg-code/ <-- Cloned Git-Repo
.env <-- von .env.example adaptieren
Docker/ <-- Cloned
www/ <-- Cloned
cron/ <-- Cloned
migration/ <-- Cloned
scripts/ <-- Cloned
.composer.json
.composer.lock
vendor/ <-- via composer install
data/ <-- Cloned > all Pathes can be configured/changed in .env
errlog/ <-- CREATE!
files/ <-- CREATE!
gallery/ <-- CREATE!
41/ <-- APOD Gallery ID
hz_maps/ <-- Cloned
smartylib/ <-- CREATE!
cache/ <-- CREATE!
templates_c/ <-- CREATE!
tauschboerse/ <-- CREATE!
temp/ <-- CREATE!
upload/ <-- CREATE!
new-galleries/ <-- CREATE!
userimages/ <-- CREATE!
Vergiss nicht die korrekte Ownership und Berechtigungen auf alle Verzeichnisse & Files zu setzen!
Ownership User & Group
(www-data muss mit apache2 User & Group korrespondieren)
chown www-data:www-data /zorg-code/www/* chown www-data:www-data /zorg-code/data/*
/www/-Verzeichnis
$ chmod 755
/data/files/-Verzeichnis und Files
$ chmod 777
/data/upload/-Verzeichnis
$ chmod 755 /zorg-code/data/upload/
/smartylib/-Verzeichnisse
(Smarty braucht 777)
$ chmod 777 /zorg-code/data/smartylib/templates_c $ chmod 777 /zorg-code/data/smartylib/cache
Es hat sich gezeigt, dass eine lokale zorg Installation nicht sauber funktioniert mit User Sessions (nach dem Login), solange kein virtueller Host im Apache Webserver definiert wurde. Deshalb machen wir das auch noch.
Du kannst dir entweder die zorg Apache Configs aus dem entsprechenden GitHub Repo ziehen und anwenden - oder Du gehst den Quick'n'dirty way:
- Im lokalen Apache-Verzeichnis die Konfigurationsdatei "httpd.conf" in einem Editor öffnen
- Sicherstellen, dass die Zeile
NameVirtualHost *:80aktiviert ist (ggf. "#" am Anfang der Zeile entfernen!) - Folgenden VirtualHost in der "httpd.conf" Datei für den zorg www-Ordner festlegen:
ServerAdmin admin@mail.com
DocumentRoot "/pfad/zum/lokalen/apache/webroot/zorg-code/www/"
ServerName localhost
ServerAlias zorg.local *.zorg.localNun musst Du lokal noch den Hostnamen "zorg.local" in die hosts-Datei schreiben: Unter macOS findet sich die Datei hier:
/private/etc/hosts
Die Datei mit folgender neuen Zeile ergänzen:
127.0.0.1 zorg.local
Kontaktiere kassiopaia, [z]keep3r oder IneX für einen aktuellen zorg DB-Dump
Details siehe MySQL database export, import and setup
- Auf dem lokalen MySQL-Server eine neue Datenbank - z.B.
zorg- anlegen und einen User mit sämtlichen Rechten (minimum aber Select, Insert, Update & Delete-Berechtigungen) dafür konfigurieren - Den zorg DB-Dump nun dort importieren
Damit zorg lokal mit dieser DB und dem gewählten User läuft, musst Du eine im zorg www eine MySQL-PHPdatei anlegen und konfigurieren:
- unter
/zorg-code/www/includes/erstelle eine Datei mit Bezeichnungmysql_login.inc.local.php - kopiere den folgenden Codes in die Datei und passe die Parameter entsprechend deiner Umgebung an:
<?php
/** MySQL database login information */
define('MYSQL_HOST', '127.0.0.1');
define('MYSQL_DBNAME', '...');
define('MYSQL_DBUSER', '...');
define('MYSQL_DBPASS', '...');Deine lokale zorg Kopie sollte jetzt über den Webbrowser erreichbar sein! Teste das mit http://zorg.local/
BEVOR du Änderungen am Code vornimmst bzw. einchecken willst, immer zuerst den aktuellsten Code Stand mittels
git pullziehen!
Gewisse Konfigurationen für zorg sind lokal für die Entwicklung anders, als die Live-Konfigurationen. Du kannst sämtliche Werte der config.inc.php sowie weitere speziellen Settings vor dem Laden aller weiteren Einstellungen "injecten".
Dazu benötigst du ein PHP-File names development.config.php unter dem Pfad: /zorg-code/www/includes/.
Dokumentation nicht vergessen! Damit auch anderen nachvollziehen können, was für Anpassungen am zorg Code Du vorgenommen hast und was die Intention dahinter ist, dokumentiere alles bitte entsprechend! (Fast) jeder Kommentar ist besser, als keiner... Um es Dir auch möglichst einfach zu machen, findest Du folgend entsprechende Schnipsel, die Du für die Dokumentation im Code adaptieren kannst.
Da wir dem phpDoc Standard folgen, können wir daraus nämlich auch laufend eine schöne Webseite der gesamten Dokumentation automatisch generieren lassen!
WICHTIG: Gross-/Kleinschreibung der phpDoc @tag ...-Tags bitte einhalten! (z.B. ist @deprecated ≠ @DEPRECATED)
Und so sieht unsere zorg Code Doku damit dann aus:
Am besten mit der phpDocumentor.phar, dann über die CLI mit folgendem Befehl:
$ php ./phpDocumentor.phar -c "/zorg-code/zorgcode_ghwiki.xml" --template="/path/to/phpDocumentor-Template-ghwiki" --cache-folder "./zorg-code-wiki-cache" --title "zorg Code Doku" --force/** Kurzbeschreibung einer einfachen Abfrage, Variable, usw. */
To-Dos in Codeblöcken können einfach im PHPDoc Block ergänzt werden mit folgendem Verweis:
/**
* ...
* @TODO Hier habe ich noch etwas zu erledigen, und zwar... (Von wem, Datum)
* ...
*/
/** @TODO Hier ein kurzes inline To-do, und zwar... (Von wem, Datum) */
// TODO Hier ein kurzes inline To-Do aber ohne @...To-Dos mit höherer Prio, also etwas das unbedingt gefixt oder optimiert werden sollte, können mit folgendem Verweis markiert werden:
/**
* ...
* @FIXME das hier muss refactored werden, weil es performance-intensiv ist (Von wem, Datum)
* ...
*/
/** @FIXME Hier ein kurzer Hinweis inline zum fixen, und zwar... (Von wem, Datum) */
// FIXME Hier ein kurzer Hinweis inline für einen notwendigen Fix aber ohne @...In Doc-Blocks können relevante Links explizit hinzugefügt werden.
Wenn auf Files im zorg Code referenziert werden kann es sinnvoll sein den Link aus dem zorg-code GitHub-Repo zu verwenden:
/**
* ...
* @link [URI] [description]
* @link https://github.com/zorgch/zorg-code/blob/master/README.md Dieses README enthält weitere Informationen
* ...
*/Nebst (externen) Links können in Doc-Blocks auch andere, relevante Codestellen direkt referenziert werden:
/**
* ...
* @see \Namespace\Klasse::funktion() Die Funktion aus der Klasse XY wird hier verwendet
* @see funktion() Diese Funktion wird hier auch verwendet
* ...
*/Wenn man allerdings den Tag @uses oder @used-by verwendet, wird in der Dokumentation eine Relation zwischen den genannten Elementen hergestellt:
/**
* ...
* @uses [file | "FQSEN"] [<description>]
* @uses README.md Dieses README enthält weitere Informationen
* ...
*/Wenn eine Codestelle oder -elemente, insbesondere Funktionen, Klassen, Konstanten,... - aber auch ganze Files - nicht mehr benötigt werden, bitte als @deprecated markieren:
/**
* Titel meiner Funktion
*
* ...
* @deprecated 2.0 Bis Version 2.0 wurde diese Funktion noch gebraucht
* ...
*/
function MeineAlteFunktion($params=null)
{
...<?php
/**
* Kurzbeschreibung des Files
*
* Lange Beschreibung wieso es diese
* _tolle_ File denn gibt. Ich kann dazu mehrere
* Zeilen verwenden, mit **markdown** formatierungen.
* Natürlich müssen nicht alle Parameter
* für die Doku verwendet werden.
*
* @package zorg[\subpackage] (z.B. "Addle", "Events", o.ä.)
* @author Ursprünglicher Autor
* @author Dein-Name
*/
...Quelle nur auf phpdoc.de gefunden.
<?php
/**
* Kurzbeschreibung einer eingebundenen Datei (oder mehreren).
* @include datei.inc.php Funktion: _include_ | Required: nein
* @include datei2.inc.php Funktion: _require_once_ | Required: ja
*/
include_once( dirname(__FILE__) . '/datei.inc.php');
require_once( dirname(__FILE__) . '/datei2.inc.php');
.../**
* Beschreibung der ersten Konstante
* @const WEBROOT Contains the absolute path to the Webroot directory
*/
if (!defined('WEBROOT')) define('WEBROOT', '/', true);
/**
* Beschreibung der zweiten Konstante
* @const SITEURL Contains the root URL of my website
*/
if (!defined('SITEURL')) define('SITEURL', 'zorg.ch', true);
.../**
* Titel meiner Klasse
*
* Lange Beschreibung meiner tollen
* Klasse. Hier kann ich auf mehreren
* Zeilen schreiben, mit _markdown_ formatierungen.
* Natürlich müssen nicht alle Parameter
* für die Doku verwendet werden.
*
* @package zorg[\subpackage] (z.B. "Events", "Bugtracker", "Games\HuntingZ", o.ä.)
* @author Ursprünglicher Autor
* @author Dein Name
* @version 1.0 (aktuelle Version der Klasse)
* @since 1.0 `23.05.2003` `author` Klasse hinzugefügt
* @since x.x `dd.mm.yyyy` `author` Klassenänderungen/Change-log der Klasse
*/
class MeineKlasse
{
...
}/**
* Beschreibung der ersten Variable mit Angabe des Typs
* @var array $meinevar1 Beschreibung...
*/
...
/**
* Beschreibung der zweiten Variable mit Angabe des Typs
* @var string $meinevar2 Beschreibung...
*/
.../**
* Titel meiner Funktion
*
* Lange Beschreibung meiner tollen
* Funktion. Hier kann ich auf mehreren
* Zeilen **beschreiben**, was ich will.
*
* @author Dein-Name
* @version 1.0 (aktuelle Version der Funktion)
* @since 1.0 `23.05.2003` `author` Funktion hinzugefügt
* @since x.x `dd.mm.yyyy` `author` Funktionsänderungen/Change-log der Funktion
*
* @param integer $user_id Eine User-ID muss der Funktion übergeben werden
* @param string|array $params Parameter als String oder Array für meine Funktion - default: null
* @global array Datenbank-Informationen in {$db}
* @global array User-Informationen in {$user}
* @return string/boolean/integer/array
*/
function MeineFunktion($user_id, $params=null)
{
global $db, $user;
$code = '...';
/** Kurzer inline Kommentar */
if ($code === '...') echo 'Yarak';
}Wenn eine Funktion AUSSERHALB einer Klasse geschrieben wird, bitte noch die Package-Informationen im phpDoc Block ergänzen (bei Funktionen innerhalb von Klassen ist dieser Kontext bereits gegeben):
- @package zorg[\subpackage] (z.B. "Layout", "Games\Addle", o.ä.)
Direkt auf GitHub lassen sich einfach Pull-Requests auf den master-Branch erzeugen, um alle neuen Codeänderungen zusammenzuführen:
Der zorg Code kann inzwischen bequem über ein Deployment-Interface ausgeliefert und aktualisiert werden. Falls Migrationsscripts (aus /migration/* notwendig sind, können diese ebenfalls dort ausgeführt werden).
Stelle auf jeden Fall sicher, dass deine Codeänderungen auf dem develop-Branch zwecks Testing eingecheckt sind. So können sie auf den zorg Construct (Test-Instanz) deployed und verifiziert werden.
Für produktive Auslieferung sollen die Changes via Pull Request auf den master-Branch übernommen worden sein.
Wende dich an kassiopaia oder IneX für ein Deployment auf Construct oder Live!
DONE - die Änderungen müssten jetzt auch auf zorg.ch aktiv sein.
$ apt-get update $ apt-get install git
Jetzt noch apache2 konfigurieren mit den notwendigen Konfigurationsdateien:
-
Testen der Konfiguration mittels:
$ apachectl configtest
That's it - zorg.ch sollte nun laufen & ausgeliefert werden.
Im .env können diverse API Keys verschiedener Services eingetragen werden, welche die zorg-code Plattform braucht um Daten zu aggregieren oder an externe APIs zu pushen.
Das Google reCaptcha wird in der User Registration benötigt, um Bots am Erstellen von Fake Usern abzuhalten.
z.B. für Google Maps API Abfragen
Die NASA API wird benötigt um folgende Daten zu aggregieren:
- APOD - Astronomy Picture of the Day
- Spaceweather APIs:
- Request: [https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY]
- Result
{"date":"2020-04-18","explanation":"It was just another day on aerosol Earth. For August 23, 2018, the identification and distribution of aerosols in the Earth's atmosphere is shown in this dramatic, planet-wide digital visualization. Produced in real time, the Goddard Earth Observing System Forward Processing (GEOS FP) model relies on a combination of Earth-observing satellite and ground-based data to calculate the presence of types of aerosols, tiny solid particles and liquid droplets, as they circulate above the entire planet. This August 23rd model shows black carbon particles in red from combustion processes, like smoke from the fires in the United States and Canada, spreading across large stretches of North America and Africa. Sea salt aerosols are in blue, swirling above threatening typhoons near South Korea and Japan, and the hurricane looming near Hawaii. Dust shown in purple hues is blowing over African and Asian deserts. The location of cities and towns can be found from the concentrations of lights based on satellite image data of the Earth at night. Celebrate: Earth Day at Home","hdurl":"https://apod.nasa.gov/apod/image/2004/atmosphere_geo5_2018235_eq2400.jpg","media_type":"image","service_version":"v1","title":"Just Another Day on Aerosol Earth","url":"https://apod.nasa.gov/apod/image/2004/atmosphere_geo5_2018235_eq1200.jpg"}
Dank der Telegram Bot API - und einem custom Bot - lassen sich diverse Messages an Telegram User oder Gruppen pushen.
Mit der Twitter API lassen sich Daten mittels eine Twitter App ID an einen Twitter-Account pushen oder aggregieren. z.B. Für das Absetzen von neuen Tweets.