Vorbereitende Maßnahmen

PHP-Version auf der CLI prüfen

Mit bspw. putty per SSH auf den Webspace verbinden.

PS.: Nachfolgend wird immer von putty die Rede sein. Wenn du ein anderes Programm bevorzugst, arbeitest du natürlich mit deinem Lieblingswerkzeug.

In der Shell/CLI eingeben:

php-v

Bei Neos wird einiges mit Flow auf der CLI (Shell) gemacht. Das Flow, das mit Neos 3.1 kommt, braucht min. PHP 7.

Im obigen Screenshot steht PHP 7.0.x, nicht PHP 7.1.x. Das ist ein Unterschied. Diese Info werden wir später brauchen, wenn wir die Domain anlegen/einrichten.

Bei all-inkl, Stand Mitte 2017: Wenn PHP 5 angezeigt wird, dann all-inkl eine Mail schreiben. Die ziehen dein Webspacepaket dann auf einen Server um, bei dem PHP 7 als Default eingestellt ist. Ging bei mir immer recht flott, ohne große Komplikationen und ohne Extrakosten, weder für Umzug, noch Betrieb danach.

Webspace vorbereiten

Gehe ins "Werkzeug": FTP-Programm, Web-FTP deines Hosters, bei all-inkl evtl. mit der WebDisk, usw.

Verzeichnis anlegen, worauf wir dann die (Sub-)Domain zeigen lassen werden:

/example.com/cmsroot/

Auf der Hauptebene erstellen wir das Verzeichnis "example.com".

Hauptebene ist beim Hoster idR. das Wurzelverzeichnis für die KundenNr. Daheim auf dem Testserver das "Webroot" des lokalen Webservers. Etc.

Dort hinein dann das Verzeichnis "cmsroot".

[TODO: Vorteile dieses Vorgehens/Workflows mit eigener Anleitung/Essay veranschaulichen (.htaccess auf Ebene über dem CMS, mehrere Roots möglich, staticroot, wwwroot, neosroot, wordpressroot, etc.)]

Domain einrichten

Gehe ins "Werkzeug": Verwaltungsoberfläche deines Hosters, bei all-inkl heißt sie bspw. KAS.

Die Domain, Subdomain oder mehrere Domains, falls Multidomainsetup geplant, etc., auf das eingerichtete Verzeichnis zeigen lassen.

Beim Einrichten darauf achten, daß die richtige PHP-Version eingestellt ist. Im ersten Schritt oben "PHP-Version auf der CLI prüfen" hast du herausgefunden, welche PHP-Version bei dir läuft.

Stand Mitte 2017, mit Neos 3.1, bei all-inkl → PHP 7.0 (als CGI/FPM)

Bei all-inkl Stand Mitte 2017 muß ich die Variante "als CGI/FPM" nehmen. Mit der Variante "als Apache-Modul" hagelts Fehler beim Setup. Darauf kommen wir später nochmal kurz zurück.

Da wir dafür beim Provider bereits eingelogged sind: gleich ein Let's Encrypt-Zertifikat mit einbinden.

Datenbank erstellen/einrichten

Gehe ins "Werkzeug": Verwaltungsoberfläche deines Hosters, bei all-inkl heißt sie bspw. KAS → bist schon drin, brauchst das Werkzeug nicht wechseln.

Die Neos 3.1 Tabellen fangen mit "neos_" und in einem Fall mit "flow_" an. Daß man einen eigenen Präfix bestimmen kann, um mehrere Installationen in einer gemeinsamen Datenbank zu haben, scheint nicht standardmäßig vorgesehen zu sein. Zumnidest nicht mit dem Neos Setup Tool. Ich könnte mir vorstellen, daß man das in einer config Datei vor dem Aufruf des Setup einstellen kann. Habs aber nie versucht. Wenn du nicht unter extremem Datenbankanzahlmangel leidest, so erstelle für jedes Neos Projekt eine eigene Datenbank.

Notiere dir folgende Angaben, wirst du später brauchen: Datenbankname, User, Passwort. Host wird normalerweise "localhost" bzw. "127.0.01" sein. Außer dein Provider hat hier eine andere Vorgehensweise. In der FAQ deines Providers wirst du finden, was als Host angegeben wird.

Was du nach dem Erstellen der Datenbank noch einstellen mußt: "Kollation" auf "utf8_unicode_ci" setzen.

Bei den meisten Providern wirst du eine Art Adminoberfläche haben, bspw. um phpMyAdmin aufzurufen. Gehe zu phpMyAdmin für diese Datenbank, selektiere die Datenbank, dann das Register Operationen, bei Kollation utf8_unicode_ci auswählen, speichern/OK.

Genaues Vorgehen hängt vom Provider und der aktuellen phpMyAdmin Version ab. Es wird aber sehr häufig in dieser Art bzw. dem recht ähnlich sein.

Composer installieren

Gehe ins "Werkzeug": putty, Shell/CLI.

Falls du Neos auf diesem Webspace schonmal für ein anderes Projekt/Domain/etc. installiert hast, wirst du Composer schon installiert haben. Prüfe das mal. putty müßtest du noch offen haben. Gebe dort ein:

composer

Wenn der Standard-Hilfe-Text von Composer angezeigt wird, hast du Composer bereits installiert. Du brauchst es nicht nochmal zu installieren, überspringe den Composer-Installieren-Schritt.

Anleitung für all-inkl siehe hier:

https://all-inkl.com/wichtig/anleitungen/skripte/sonstiges/composer/installation_494.html

Dein Stand ist danach:

• Du hast ein Verzeichnis "bin" in deiner obersten Verzeichnisebene.
• In diesem Verzeichnis "bin" befindet sich nun der Composer
• Du hast den Alias (das Shortcut) eingerichtet, damit du Composer unkompliziert aufrufen kannst, unabhängig davon, in welchem Verzeichnis du dich gerade befindest.
  

Du kannst das ganze sicherheitshalber auch nochmal testen.

Trenne in putty deine SSH-Sitzung.
Verbinde dich neu mit putty.
Tippe "composer" ein.

Ausgabe müßte der Standard-Hilfe-Text von Composer sein.

Neos installieren

Siehe auch die offizielle Doku vom Neos-Team. Beachte: mein Tutorial habe ich August 2017 mit der Version Neos 3.1.4 begonnen, evtl. beschreiben die dort eine neuere Version.

http://neos.readthedocs.io/en/stable/GettingStarted/Installation.html

Gehe ins "Werkzeug": putty, Shell/CLI.

Wir bleiben in der CLI – dh. im putty-Fenster, unserer SSH-Sitzung zum Webspace/Server/etc.

Gehe ins Verzeichnis, das wir im vorhergehenden Punkt "Domain einrichten" für die Domain erstellt haben.

Wiederhole "cd .." so lange, bis du im Hauptverzeichnis bist.
Wechsle ins angesprochene Verzeichnis:

cd example.com
cd cmsroot

Nun Neos dorthin installieren:

composer create-project neos/neos-base-distribution Neos

Note: bei all-inkl brauchts das php am Anfang nicht. (Mglw. durch den Alias?)

Andere Aufrufe wären, für andere Serverinstallationsvarianten:

php composer create-project neos/neos-base-distribution Neos

sudo php composer create-project neos/neos-base-distribution Neos

Und Kombinationen daraus. Dh. evtl. mal mit mal ohne php am Anfang. Manche könnten ein sudo brauchen. Etc.

Wenn die installation erfolgreich verlaufen war, hast du nun im Verzeichnis ".../example.com/cmsroot/" ein Verzeichnis "Neos". Dort befindet sich die Neos-Installation. Im Verzeichnis "Neos" findest du ein Verzeichnis "Web". Das Verzeichnis "Web" ist das Verzeichnis, das von außen erreichbar sein soll. Die anderen sollen es nicht sein. Dh. wir lassen unsere Domain auf das Verzeichnis "Web" zeigen.

Domain auf das Neos-Web-Verzeichnis zeigen lassen

Gehe ins "Werkzeug": Verwaltungsoberfläche deines Hosters.

PS.: Durch die Arbeit oben ist ein wenig Zeit vergangen, seit wir unsere Domain angelegt haben. Mittlerweile sollte die Domain beim Provider eingerichtet sein, so daß Änderungen nun zügig "aktiv" werden und das Let's Encrypt-Zertifikat sollte auch schon aktiv sein.

Beim Hoster anmelden, falls du es nicht noch bist.

Zu den Einstellungen für deine Domain wechseln.

Die Domain zeigen lassen auf:

/example.com/cmsroot/Neos/Web/

Neos Setup

Requirements

Gehe ins "Werkzeug": Browser.

Gehe im Browser zur Seite:

https://example.com/setup

Mögliche Fehlermeldungen.

Fehler: The specified path to your PHP binary (see Configurations/Settings.yaml) points to a PHP binary with the version "...". This is not compatible to the version that is currently running ("...").

Du hast beim Einrichten der Domain auf deinem Webspace versehentlich 7.1 anstatt 7.0 als PHP-Version für diese Domain eingestellt.

Gehe nochmal zur Verwaltungsoberfläche bei deinem Provider und stelle die PHP-Version für die Domain um. Im ersten Schritt oben "PHP-Version auf der CLI prüfen" hast du herausgefunden, welche PHP-Version du für deine Domain einstellen mußt.

Fehler: Flow requires the PHP function "exec" to be available.

Den habe ich, wenn ich bei meinem Provider "PHP x.y (als Apache-Modul)" für die Domain eingestellt habe. Das geändert in "PHP x.y (als CGI/FPM)" und Neos freut sich.

Wenn alles nichts hilft ... werden wir für Flow wohl doch den Pfad zu PHP spezifizieren müssen.

Wir werden dazu eine Textdatei auf deinem Webspace anlegen und mit etwas Text füllen.

Nutze deinen Dateibrowser – FTP, WebFTP deines Providers, per VPN bei all-inkl, Linuxpros werden vrmtl. auf der Shel bleiben, etc.

Gehe zum Pfad:

<rootpfad>/example.com/cmsroot/Neos/Configuration

<rootpfad> ist das Verzeichnis, auf das du deine Domain eingestellt hast. In unserem Beispiel ist das: /example.com/cmsroot/

Dort müßte es in der Art aussehen:

Erstelle hier eine neue Datei:

Settings.yaml

Wenn die Settings.yaml schon existiert, hat die Neos evtl. doch schon angelegt. Nutze dann diese vorhandene. Achte bei deinen Änderungen darauf, daß du nichts bereits vorhandenes rauswirfst.

Mglw. ist es nicht zwingend erforderlich, aber ich achte bei "Neos-Dateien" immer darauf, daß die Datei UTF-8 ist mit Unix-Lineendings. Ich arbeite mit dem Editor Notepad++. Mit Notepad++ kannst du das leicht und bequem sicherstellen/einstellen.

Füge folgenden Inhalt ein. Bzw. füge ihn hinzu, wenn die Settings.yaml schon vorhanden war.

Neos:
  Flow:
    core:
      phpBinaryPathAndFilename: /usr/bin/php

Das "/usr/bin/php" wirst du gegebenenfalls anpassen müssen. Suche in der Hilfe deines Providers bzgl. des PHP-Pfades.

Weitere Beispiele:

/user/local/bin/php
/usr/bin/php70
/usr/bin/php71

TODO: mit oder ohne Hochkommata? Evtl. machts keinen Unterschied?

Gehe wieder zum Browser. Aktualisiere - dh. meistens F5 bzw. rufe "https://example.com/setup" neu auf. Wenn alle "Requirements" erfüllt sind, gehts mit folgender Meldung weiter:

Danach wirst du automatisch zum Login weitergeleitet.

Neos hat ein Setup-Login-Passwort generiert und zeigt dir auch an, wo du es findest. Unten im Punkt "Neos Setup" gehe ich gleich am Anfang inkl. Screenshot nochmal genau darauf ein. Wenn du den Login angezeigt bekommst, gehe gleich zum Punkt "Neos Setup" und überspringe "Setup-Tool Probleme".

Setup-Tool Probleme

Mir ist es schon vorgekommen, daß ich alle Requirements erfüllt und die Requirement-Prüfung durchlaufen habe, dann aber beim "Login" zum Setup-Tool Fehlermeldungen kamen.

Neos fehlen die Angaben für die Datenbank. Die sollen doch aber erst mit dem Setup-Tool eingetragen werden ... ???

Mglw. hats nur an meiner Konstellation gelegen: fürs Tutorial mehrere Testinstallationen gemacht, Varianten ausgetestet, nebenher Notizen gemacht, dh. mich ablenken lassen, etc. ... Diesen Datenbank acces denied Fehler hatte ich erstaunlicherweise erst, als ich nach vielen Tests/Tutorialschritten das erste "echte" Projekt installiert/eingerichtet habe. Wie dem auch sei, Lösung war:

Mit dem Dateibrowser, gehe zum Verzeichnis

<rootpfad>/example.com/cmsroot/Neos/Configuration

Öffne die Datei

Settings.yaml

Falls sie noch nicht existiert, erstelle sie neu, als normale Textdatei. Es gilt das selbe, wie oben beschrieben, bei Requirements für die PHP Version – dh. UTF-8, Unix-Lineendings, vorsichtig sein, wenn sie schon vorhanden ist und etwas drin steht, etc.

Hier eine Beispiel-"Settings.yaml" nach erfolgreichem Durchlaufen des Setup.

Bei dbname, user und password setzt du deine Datenbankangaben ein.

Vorsicht. An diesem Punkt habe ich einige Tests gemacht. Die Angaben in der Settings.yaml geändert, auch die Settings.yaml im Verzeichnis "Testing", usw. Sehr regelmäßig scheint mir Neos Caching dabei Streiche zu spielen und die Settings.yaml wieder auf die "alten" Werte zurückzustellen. Bin aber auch hinundwieder zurück ins Setup-Tool, um Screenshots zu machen. Dh. mglw. ist es nicht das Caching, sondern das Setup hat was überschrieben. Nun, letztlich bin ich dazu übergegangen, es mir "leichter" zu machen. Anstatt mich mit dem Caching auseinander zu setzen, Caches zu leeren, etc., lösche ich alles und installiere neu. Noch ist nicht viel geschehen und wenn ich bis hierhin gekommen bin, weiß ich daß alle grundsätzlichen Voraussetzungen (Requirements) erfüllt sind und ich die Einstellungen und Werte kenne, mit denen es auf diesem Server/Webspace grundsätzlich läuft. Auch die ganzen Neos-unabhängigen Vorbereitungen – Domain beim Provider einrichten, Datenbank anlegen, etc. – bleiben  erhalten, muß ich nicht nochmal machen.

Anmerkung.

Wenn du nicht alles gelöscht bekommst, oder allgemein lieber auf der Shell arbeitest, der Linux-Befehl zum löschen: rm.

Wechsle mit den entspr. cd Befehlen ins Verzeichins der Domain, dh. da wo sich das "Neos"-Verzeichnis befindet.

rm -r Neos

Das löscht den Ordner Neos und alles was sich darunter befindet.

Falls du für ein paar Dateien access denied fürs Löschen bekommst:

all-inkl: siehe das mit dem Ändern der Besitzrechte:

https://all-inkl.com/wichtig/anleitungen/kas/tools/administrative-werkzeuge/besitzrechte-aendern-chown-auf-php-user-www-data_109.html

oder

https://all-inkl.com/wichtig/anleitungen/programme/ftp/all-inkl.com-webftp/besitzrechte-aendern-chown_380.html

Ende Anmerkung.

"Restart" heißt:

• das Verzeichnis "Neos" mitsamt Inhalt löschen
• falls sich etwas nicht löschen läßt, evtl. Besitzrechte ändern, siehe Anmerkung oben
• das Wurzelverzeichnis für unsere Domain ist dann wieder leer, dh. /example.com/cmsroot/ ist natürlich weiter vorhanden, hat aber keinen Inhalt mehr
• mit putty mit der Shell verbinden
• cd example.com
• cd cmsroot
• bzw. die cd-Befehle daß du in dein entspr. Verzeichnis kommst
• neu installieren, dh.: composer create-project neos/neos-base-distribution Neos

Domain ist bereits eingerichtet, Webspacestruktur, Datenbank auch, usw. Es geht letzlich also nur darum, alle Neos-Dateien zu löschen und den composer nochmal neu installieren zu lassen. Danach gehst du wieder zu:

https://example.com/setup

Bzw. das http ohne s, falls du kein SSL (Let's Encrypt, usw.) eingerichtet hast.

Falls du wieder auf Requirement-Fehler stößt, erinnere dich, wie du sie beim Durchlaufen der Anleitung oben gelöst hast.

Falls du wieder auf den Datenbankfehler "Access Denied for user @localhost" stößt, mußt du wohl doch die Datenbankangaben wie oben beschrieben von Hand eintippen.

Wenn du den initial login screen siehst, bist du durch und kannst zum nächsten Schritt übergehen.

Neos Setup

Siehe unten den Hinweis im blauen Kasten. Neos hat ein anfängliches Passwort generiert. Hier siehst du wo du es findest:

<rootpfad>/example.com/cmsroot/Neos/Data/SetupPassword.txt

Beachte: notiere dir das Setuppasswort. Sobald du dich eingelogged hast, wird die Textdatei mit dem Passwort nämlich gleich wieder gelöscht. In 99,9 % aller Fälle wird das Setuppasswort nur kurz gebraucht. Denn während einem der nächsten Schritte wird der Administrator-Account erstellt – mit anderem, eigenem Passwort. Aber frei nach Murphys Law: jemanden trifft das eine 0,1 %. Telefon klingelt oder man wird anderweitig abgelenkt, muß kurz weg, usw. Rechner wird ausgeschaltet und wenn man wieder kommt kann man sich nicht mehr frisch einloggen, weil man das Passwort nicht parat hat.

Schritt 1: Requirements Check

Nichts zu tun. Klicke: Next.

Schritt 2: Datenbank

Trage hier die Daten deiner Datenbank ein. Hast du oben die Settings.yaml bereits mit der Datenbank anpassen müssen, sind die Felder bereits mit diesen Daten vorbelegt.

Im oberen Bild, der untere orangene Kasten: Du hast vergessen die Kollation bei der Datenbank auf "utf8_general_ci" umzustellen. Hole das nach – siehe oben im Punkt bzgl. Erstellen der Datenbank. Danach entweder hier ein Refresh/Neuladen der Seite oder einmal die Buttons Back (Grau) und wieder Next (Blau), um erneut hierher zu gelangen.

Klicke Next.

Schritt 3: Admin Account erstellen

Fülle die Felder aus. Dann: Next.

Schritt 4: Unsere (neue) Site "kickstarten"

Das überspringen wir: klicke Skip.

Achtung: diesmal _nicht_ Next, sondern Skip. Wir müssen erst noch "säubern". Neos installiert auch eine Demo. Die stört uns jedoch, kann uns (angeblich) sogar evtl. dazwischenfunken und bei manchen Einstellungen stören. Später im Anschluß werden wir den ganzen ungenutzten Kram löschen und erst danach unser neues Projekt in Neos anlegen.

Also: Skip.

Du bist auch ausgelogged worden. Du loggst dich zukünftig (ins Neos Backend) nun mit deinem einen Schritt vorher erstellten Adminaccount ein.

Wir sind aber noch nicht ganz fertig. Wir wollen noch die Demodaten löschen.

Wechsle zu putty. Verbinde dich mit dem Webspace, falls du nicht mehr verbunden bist.

Wechsle ins Neos-Verzeichnis:

cd <rootpfad>/example.com/cmsroot/Neos

Gib folgende Befehle ein:

./flow site:prune
./flow package:delete Neos.Demo
composer remove neos/demo

Die eigentliche Installation, im engeren Sinne, könnte nun abgeschlossen sein.

Lasse das putty-Fenster noch offen. Du wirst es gleich wieder brauchen.

Gehe im Browser zu:

https://example.com

Du bekommst erwartungsgemäß ein "Missing Homepage". Wir haben noch nichts angelegt.

Gehe ins Backend:

https://example.com/neos

Logge dich mal testweise ein.

Zur Erinnerung: im Neos Setup Schritt 3 hattest du deinen Adminaccount angelegt. Da sind deine Logindaten.

Oops, Fehler. Neos meckert "Page Not Found", es würde keine Site finden.

"Initial"-/Startbedingung schaffen

Gehe nochmal in die Shell. Du hast das putty-Fenster noch offen gelassen.

Ich erkläre dir nachfolgend erstmal die Befehle. Tippe sie noch nicht in die Shell. Lese erst die folgenden Absätze.

./flow kickstart:site VendorName.SitePackage SiteName
./flow site:import VendorName.SitePackage

VendorName ist so etwas wie dein Firmenname. Das ist etwas recht übergordnetes, das man normalerweise nicht mehr ändert. Auch bei zukünftigen Projekten bleibt der Firmenname normalerweise immer gleich. Wähle hier also gut.

SitePackage kannst du dir als Projektnamen vorstellen. Unter dem SitePackage faßt du alle Sites, dh. Einzelteile des Projekts zusammen.

SiteName ist ein in sich geschlossener einzelner Teil des Projekts. Wenn du bspw. dein Projekt mehrsprachig erstellen wirst, dafür aber nicht die Content Dimensions von Neos nutzen willst, da nicht jede deutsche Seite auch eine entspr. englische und französische Seite haben wird. Manche Teile gibts nur auf deutsch, andere nur auf englisch und auch die gemeinsamen sind nicht eins zu eins auf URls verteilt, usw. Dann hast du eine Site examplede, eine Site examplecom, eine examplefr etc. Oder du hast mehrere Bereiche die zwar zum Gesamtprojekt gehören aber voneinander völlig verschieden sind. Das muß nicht nur das layout, Design, etc. sein. Du willst mehrere Einheiten haben, die du unterschiedlich konfigurieren kannst.

Hinweis. SiteName kannst du auch nachträglich im Neos Backend jederzeit ändern; es einfach umbennenen. In den meisten Anwendungsfällen wirst du den SiteName in Skripten, Templates, usw. nicht nutzen. VendorName und SitePackage wähle sorgfältig.

Die erste Zeile (kickstart:site) erstellt alles, einschl. Struktur, usw. Neos zeigt dann aber noch keine Seite an, da es nicht weiß wie und was es anzeigen soll. Die zweite Zeile (site:import) dient dann eigentlich lediglich nur noch dazu, daß die beim kickstarten erstellten Dinge (Default.html usw.) mit einem Wurzelknoten verknüpft/integriert werden. Erst dadurch bekommt Neos "echten" Html-Code den es anzeigen kann.

Für unser Neos Tutorial wählen wir bspw.

./flow kickstart:site SuebenIT.NeosTutorial SuebenIT
./flow site:import SuebenIT.NeosTutorial

Insgesamt: du bist völlig frei wie du die Namen wählst. Obige Beschreibung dient nur als Erklärung, mit welchem konzeptuellen Hintergrund die Neos-Entwickler gearbeitet haben und warum sie es gerade so aufgeteilt haben.

TODO: Evtl. gibts Einschränkungen bei den erlaubten Zeichen. Bspw.: Darf SiteName Punkte enthalten? Etc.

Gehe im Browser erneut zu

https://example.com

Ergebnis: Jetzt wird eine Seite angezeigt. Auch wenn sie ganz weiß (leer) ist, ist das kein Fehler. Die standardmäßig angelegte Seite von Neos ist so minimal wie möglich gehalten.

Einen Screenshot sparen wir uns. Du bekommst keine Fehlermeldung, nur eine leere weiße Seite.

Der Gang ins Backend ...

https://example.com/neos

Logge dich ein.

Die Installation ist damit abgeschlossen. Weiter gehts mit Teil 2 "Einführung in Neos".