Skip to content

zorgch/zorg-code

Repository files navigation

Übersicht

zorg Code standalone lokal einrichten

Voraussetzungen

Docker Container

Rundum sorglos Paket: siehe separates zorg on Docker how-to im /Docker-dir.

Apache-PHP-MySQL Stack

Was auch geht ist lokal mittels einem Apache-Webserver mit PHP sowie MySQL. Am effizientesten direkt mittels MAMP (macOS), WAMP (Windows) und LAMP (Linux).

PHP

MySQL

Um die MySQL-Datenbank lokal zu konfigurieren & verwalten am besten ein MySQL-Manager verwenden z.B. für macOS mit Sequel Ace.

GitHub-Account erstellen

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.

Git einrichten (optional)

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).

  1. Optional kann Git lokal installiert werden wie hier beschrieben
  2. 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!

Clone des zorg Codes

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...

  1. Das Terminal-Shell (macOS/Linux) resp. Git Bash (Windows) starten
  2. 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/

  1. 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!*

Verzeichnisstruktur

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!

Berechtigungen richtig setzen

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 $(find /zorg-code/www/ -type d) $ chmod 644 $(find /zorg-code/www/ -type f)

/data/files/-Verzeichnis und Files

$ chmod 777 $(find /zorg-code/data/files/ -type d) $ chmod 644 $(find /zorg-code/data/files/ -type f)

/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

Apache Virtual Host konfigurieren

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:

  1. Im lokalen Apache-Verzeichnis die Konfigurationsdatei "httpd.conf" in einem Editor öffnen
  2. Sicherstellen, dass die Zeile NameVirtualHost *:80 aktiviert ist (ggf. "#" am Anfang der Zeile entfernen!)
  3. Folgenden VirtualHost in der "httpd.conf" Datei für den zorg www-Ordner festlegen:
  ServerAdmin [email protected]
  DocumentRoot "/pfad/zum/lokalen/apache/webroot/zorg-code/www/"
  ServerName localhost
  ServerAlias zorg.local *.zorg.local

Hosts-Eintrag

Nun 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

zorg Datenbank

Kontaktiere kassiopaia, [z]keep3r oder IneX für einen aktuellen zorg DB-Dump

Details siehe MySQL database export, import and setup

  1. 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
  2. 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:

  1. unter /zorg-code/www/includes/ erstelle eine Datei mit Bezeichnung mysql_login.inc.local.php
  2. 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/

Am zorg Coding mitwirken

BEVOR du Änderungen am Code vornimmst bzw. einchecken willst, immer zuerst den aktuellsten Code Stand mittels git pull ziehen!

Applikationssettings lokal überschreiben

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/.

Code Dokumentation

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)

Preview

Und so sieht unsere zorg Code Doku damit dann aus:

Doku lokal generieren

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

Inline Kommentare

/** Kurzbeschreibung einer einfachen Abfrage, Variable, usw. */

Offene Arbeiten markieren

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 @...

Notwendige Fixes / mögliche Fehlerquellen markieren

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 @...

Links zu relevanten Webpages einfügen

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
* ...
*/

Referenzierungen auf andere Codestellen

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
* ...
*/

Nicht mehr benötigte / veraltete Stellen markieren

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)
{
  ...

Files dokumentieren

<?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
*/
...

File includes dokumentieren

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');
...

Konstanten dokumentieren

/**
* 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);
...

Klassen dokumentieren

/**
* 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
{
  ...
}

Variablen in Klassen dokumentieren

/**
* Beschreibung der ersten Variable mit Angabe des Typs
* @var array $meinevar1 Beschreibung...
*/
...
/**
* Beschreibung der zweiten Variable mit Angabe des Typs
* @var string $meinevar2 Beschreibung...
*/
...

Funktionen dokumentieren

/**
* 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';
}

Alleinstehende Funktionen (Klassen-unabhängig)

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.ä.)

Neusten Codestand deployen

Pull-Request mit Code-Änderungen erstellen

Direkt auf GitHub lassen sich einfach Pull-Requests auf den master-Branch erzeugen, um alle neuen Codeänderungen zusammenzuführen:

Deployments

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.

Initiales Setup: Repo EINMALIG auf den Server runterladen

Git installieren

$ apt-get update $ apt-get install git

apache2 konfigurieren

Jetzt noch apache2 konfigurieren mit den notwendigen Konfigurationsdateien:

That's it - zorg.ch sollte nun laufen & ausgeliefert werden.

Services- und API Integrationen

API Keys

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.

Google APIs

Google reCaptcha

Das Google reCaptcha wird in der User Registration benötigt, um Bots am Erstellen von Fake Usern abzuhalten.

Google Maps

z.B. für Google Maps API Abfragen

NASA API

Die NASA API wird benötigt um folgende Daten zu aggregieren:

Demo

{"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"}

Telegram Bot API

Dank der Telegram Bot API - und einem custom Bot - lassen sich diverse Messages an Telegram User oder Gruppen pushen.

Twitter API

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.