sebbo.net

mäxle Installationsanleitung

Vor einiger Zeit veröffentlichte ich mäxle, eine einfache WebApp zum Steuern von Max!-Heizungssteuerungen. Hier will ich kurz für Interessierte festhalten, wie man mäxle installiert.

Unten könnt ihr zwischen zwei Betriebssystemen auswählen, auf dem ihr den mäxle-Server installieren wollt. Die Anleitung passt sich dann demensprechend an.


Damit mäxle funktioniert wird eine MySQL-Datenbank benötigt. Wie man einen MySQL-Server aufsetzt und konfiguriert wurde im Netz bereits duzende male getan, weshalb das hier nicht weiter behandelt wird.

git installieren

Für git auf dem Mac gibt es einen Installer, den du hier herunterladen kannst. Herunterladen, ausführen, installieren lassen, fertig.

Vielleicht musst du vor dem Installieren erst erlauben, dass unsignierte Installer ausgeführt werden dürfen. Das geht in der Systemsteuerung im Menü Sicherheit > Allgemein > Programme aus folgenden Quellen erlauben.

sudo apt-get update && \
sudo apt-get upgrade && \
sudo apt-get dist-upgrade && \
sudo apt-get install git

Im Normalfall wird apt-get Dich mehrmahls fragen, ob Du das jetzt auch wirklich installieren willst. Bestätige das jeweils mit einem beherzten Tastendruck auf die "Y"-Taste.

node.js installieren

Genauso einfach funktioniert auf dem Mac die node.js Installation. Diesmal kannst du den Installer hier herunterladen.

Alles weitere machen wir jetzt über den Terminal, den du unter Programme > Dienstprogramme findest.

sudo apt-get install python-software-properties python g++ make && \
sudo add-apt-repository ppa:chris-lea/node.js && \
sudo apt-get update && \
sudo apt-get install nodejs

Das Hinzufügen des apt-repositories muss vermutlich mit Enter bestätigt werden.

Repository klonen

Nun kann die eigentliche Installation von mäxle beginnen. Zuerst besorgen wir uns den aktuellen Stand von mäxle. Navigiere dazu mit cd in einen Ordner, in den Du mäxle installieren willst. Danach klonen wir das Repository:

git clone https://github.com/sebbo2002/maexle.git && cd maexle

Module installieren

mäxle benötigt einige Module, damit es funktionieren kann. Mit npm kannst Du diese ganz einfach herunterladen und installieren. Sudo ist deshalb notwendig, weil das Modul handlebars global installiert werden muss.

sudo npm install

Da wir hier das erste mal sudo verwenden, musst du den Befehl mit deinem Passwort bestätigen.

config.js erstellen

Alle Einstellungen von mäxle werden in der config.js eingetragen. Diese müssen wir als nächstes erstellen und mit einem Editor Deiner Wahl anpassen:

cp config.example.js config.js && nano config.js

port

Port, auf dem der mäxle-Server gestartet werden soll. Standard ist hier Port 3000, aber es kann natürlich auch ein anderer Port eingetragen werden.

url

Die URL zur mäxle. Wenn ihr mäxle z.B. auf einem Server installiert, der Anfragen von "maexle.sebbo.net" entgegennimmt, dann solltet ihr hier "http://maexle.sebbo.net" eintragen. Dieser Wert wird z.B. zum generieren der Aktivierungslinks in den E-Mails verwendet.

url_secure

Im Grunde kommt hier das gleiche rein wie in url. Der Grundgedanke beim Aufbau von mäxle war, dass z.B. der Connector nur über HTTPS verschlüsselt mit dem Server kommuniziert. Jedoch machte bei mir dann die JavaScript-Umgebung, in denen die API-Skripts laufen, Probleme.

environment

Umgebung, in dem mäxle läuft, z.B. development oder production. Wenn das Environment auf development gesetzt ist, kann man die Tabellen (neu-)anlegen, deshalb setzen wir hier auf jeden Fall den Wert development ein.

db.name

Datenbankname, z.B. "maexle".

db.user

Datenbank-Username, z.B. "maexle".

db.pass

Datenbank-Passwort. Bitte verwendet sichere Passwörter. Und nein, 1234 ist kein sicheres Passwort (kann nicht oft genug gesagt werden).

db.host

Datenbank-Host, wenn ein externer MySQL-Server verwendet wird muss hier die IP des Servers rein. Standard: "localhost".

db.post

Datenbank-Port, im Normalfall 3306 (Standardwert).

db.maxConcurrentQueries

Maximale Anzahl an Datenbankzugriffen, die gleichzeitig laufen dürfen. Standardwert ist 3, was im Normalfall ausreichen sollte.

db.maxConnections

Maximale Anzahl gleichzeitiger Verbindungen zur Datenbank; auch hier ist der voreingestellte Wert 3.

mail

Hier werden die Einstellungen hinterlegt, die zum Absenden einer E-Mail benötigt werden. Die Felder mail.type und mail.data sind wohl am besten in der nodemailer-Dokumentation dokumentiert – wenn ihr also etwas anderes als SMTP sprechen wollt, lest es dort nach.

Die letzten beiden Felder geben an, von welcher Adresse aus E-Mails gesendet werden sollen (mail.bot) und an wen Antworten an diese E-Mail-Adresse geschickt werden sollen (mail.replyTo).

GUI zusammenbauen (lassen)

Als nächstes fassen wir die Dateien für die Web-Oberfläche zu einem Build zusammen:

node build production

Das kann ein paar Sekunden dauern und gibt im Erfolgsfall nichts zurück. Falls ein Fehler kommt der "Cannot find module 'es5-ext'" oder "Cannot find module 'memoizee'" heißt: Installiert die Module von cli-color nochmal per Hand nach, da stimmt irgendetwas nicht so ganz:

cd node_modules/cli-color/ && npm install && cd ../../

Server starten

Nagut, dann starten wir mal den Server:

node server

Wenn alles gut geht bekommen wir ein paar "Worker online" und genauso viele "UNSAFE DEVELOPMENT MODE". Das ist ganz normal.

Tabellen in der Datenbank anlegen

Wenn ihr jetzt mit eurem Browser auf den Server geht, solltet ihr schonmal eine Startseite sehen. Die Anmeldung funktioniert allerdings noch nicht, weil die Tabellen in der Datenbank fehlen. Die könnt ihr recht einfach anlegen, indem ihr http://localhost:3000/reset aufruft (localhost muss natürlich angepasst werden, wenn der Server nicht lokal läuft).

Beim Reset werden komplett alle Daten gelöscht und die Tabellen neu angelegt. Deshalb solltet ihr in der config.js den Wert von environment wieder auf production ändern und den Server anschließend neu starten, damit kein Reset mehr möglich ist.

erste Anmeldung

Habt ihr die config.php wie oben beschrieben geändert und den Server neu gestartet? Dann könnt ihr unten im Feld "Mäxle Beta ausprobieren" eure E-Mail-Adresse eingeben und schon seid ihr registriert. Die weiteren Anmeldedaten bekommst Du per E-Mail zugesendet.