Keila

Keila installieren

Keila ist eine Software zum erstellen und verwalten von Newslettern. Es werden mehrere (E-Mail)Sender, sowie Instanzweite geteilte Sender und viele praktische Einstellmöglichkeiten unterstützt. Zwar gibt es (noch) kein SSO, es werden allerdings mehrere Nutzer unterstützt. Seit Keila v0.12.9 ist auch Double-Opt-In implementiert.

Die Software ist in Erlang/Elixir geschrieben und stellt keine fertigen Binaries bereit, daher müssen wir von Hand bauen:

Keila herunterladen

Wir clonen den aktuellen Release-branch mit Git.

git clone https://github.com/pentacent/keila -b v$releasenummer

Paketmanager für Abhängigkeiten

asdf installieren

Keila erwartet ganz bestimmte Paketversionen. Um diese bereitzustellen, installieren wir als erstes einen lokalen Paketmanager. Der Einfachheit halber ua. wegen Versionierung ein Verweis:
=> https://asdf-vm.com/guide/getting-started.html

nötige asdf Plugins installieren

asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
asdf plugin add elixir https://github.com/asdf-vm/asdf-elixir.git

Abhängigkeiten installieren

Wichtig! Abhängigkeiten in keila/.tool-versions überprüfen und unten ersetzen!

asdf install erlang 26.0
asdf install elixir 1.15.6

Keila bauen

Ehe wir beginnen, müssen wir für das Hostsharing Mailsystem noch eine Kleinigkeit anpassen, damit nicht versucht wird über den via MX erkannten mailin, sondern den mailout Server zu senden.

FIXME dies konnte nicht weiter über eine Konfigurationsdatei angepasst werden und ist nun als Workaround des Workaround "direkt" im Code. Das soll so eigentlich nicht sein.

diff --git a/lib/keila/mailings/sender_adapters/smtp.ex b/lib/keila/mailings/sender_adapters/smtp.ex
index ab4a37f..6b61b91 100644
--- a/lib/keila/mailings/sender_adapters/smtp.ex
+++ b/lib/keila/mailings/sender_adapters/smtp.ex
@@ -32,7 +32,8 @@ defmodule Keila.Mailings.SenderAdapters.SMTP do
       username: config.smtp_username,
       password: config.smtp_password,
       auth: :always,
-      port: config.smtp_port
+      port: config.smtp_port,
+      no_mx_lookups: true
     ]
     |> maybe_put_tls_opts(config)
   end

Außerdem sollte Keila nicht auf Port 0.0.0.0 lauschen. Hier passen wir die config/prod.exs an.

diff --git a/config/prod.exs b/config/prod.exs
index 7272be4..cb7fb3b 100644
--- a/config/prod.exs
+++ b/config/prod.exs
@@ -11,7 +11,7 @@ import Config
 # before starting your production server.
 config :keila, KeilaWeb.Endpoint,
   url: [host: "localhost"],
-  http: [port: 4000],
+  http: [ip: {127, 0, 0, 1}, port: 4000],
   cache_static_manifest: "priv/static/cache_manifest.json",
   server: true

Okey, weiter:

# Es kann hier schon ein Updatescript bereitgelegt und ggf angepasst werden:
# https://dev.hostsharing.net/hostsharing/hs.scripts/src/branch/main/updates/keila.sh

export MIX_ENV=prod

mix local.hex --force
mix local.rebar --force
mix deps.get
mix deps.compile

npm ci --prefix ./assets

mix deps.clean mime --build
mix assets.deploy
mix release

# falls Fehlermeldung beim letzten Befehl, nochmal das Folgende getrennt ausführen:
mix assets.deploy && mix release

Keila sollte im Anschluss wiefolgt startbar sein: ./_build/prod/rel/keila/bin/keila start

Der Ordnung halber wird die Binary in einen ~/bin Ordner verlinkt oder kopiert:
ln -s $HOME/var/keila/_build/prod/rel/keila/bin/keila $HOME/bin/

In Betrieb nehmen

Das Projekt erwartet mit Docker gestartet zu werden ua. daher kann Vieles über Environment Variablen konfiguriert werden. Eine Orientierung bietet die Keila Dokumentation. In unserem Beispiel wird die lokale Datei ~/etc/keila.env angelegt und unten über systemd eingebunden:

Hinweis: bitte Hostmaster kontaktieren für freien Port

MIX_ENV=prod

DB_URL=postgres://xyz00_newsletter:sicheresDatenbankPasswort@localhost/xyz00_newsletter_db

KEILA_USER=email@adresse
KEILA_PASSWORD=sicheresPasswort

URL_HOST=newsletter.meine.domain
URL_SCHEMA=https

PORT=34000

# Wichtig: mindestens 64 Zeichen erforderlich!
SECRET_KEY_BASE=langerrandomstringmindestens64zeichen

USER_CONTENT_DIR=/home/storage/xyz00/users/newsletter/keila_uploads

# keine leeren Passwörter unterstützt
MAILER_SMTP_HOST=xyz00.hostsharing.net # auch das anpassen!
MAILER_SMTP_USER=xyz00_newsletter
MAILER_SMTP_PORT=587
MAILER_SMTP_PASSWORD=sicheresUser/MailboxPasswort

# diese Option ist zum Registrieren
# und eg. Eintragungen erforderlich
CAPTCHA_PROVIDER=hcaptcha # hcaptcha ist default, friendly_captcha als Option möglich
CAPTCHA_SITE_KEY=
CAPTCHA_SECRET_KEY=
#CAPTCHA_URL=wird auch automatisch gesetzt

systemd

Verzeichnis mkdir -p .config/systemd/user/ anlegen und keila.service erstellen:

[Unit]
Description=Keila

[Service]
Type=simple
Restart=on-abort
WorkingDirectory=/home/pacs/xyz00/users/newsletter
EnvironmentFile=-/home/pacs/xyz00/users/newsletter/etc/keila.env

ExecStart=/home/pacs/xyz00/users/newsletter/bin/keila start

[Install]
# Achtung: multiuser.target würde hier zu Problemen führen
WantedBy=default.target

• eventuell setzen einer Variabel nötig: export XDG_RUNTIME_DIR=/run/user/$UID
• starten+Autostart: systemctl enable --now --user keila

Webserver

Editieren von ~/doms/newsletter.meine.domain/htdocs-ssl/.htaccess

DirectoryIndex disabled
RewriteEngine On

# ohne Websocket Upgrade funktionieren beispielsweise Editoren nicht 
RewriteCond %{HTTP:Connection} Upgrade [NC]
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteRule ^(.*) ws://127.0.0.1:4000/$1 [P,L]

RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RequestHeader set X-Forwarded-Proto "https"
RewriteRule ^(.*) http://127.0.0.1:4000/$1 [P,L]

Keila updaten

• Repo aktualisieren

cd ~/var/keila
git fetch
git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
# prüfen ob auch wirklich release und nicht release candidate

• jetzt den Instruktionen zum Bauen oben folgen!
• systemctl restart --user keila
  • bei systemd Fehler sicherstellen das die nötige Variabel gesetzt ist (siehe oben, systemd)

Alternativ: hier ein praktisches Script mit dem Keila aktualisiert, oder bei Bedarf erneut installiert werden kann.

Anpassungen

Keila bietet unter "Templates" an einfache Anpassungen an dem Layout vorzunehmen. Hier können beispielsweise Farben und Schriftarten angepasst werden. Campagnen können außerdem dupliziert werden um doppelte Arbeit zu vermeiden. Wenn der Texteditor genutzt wird, können außerdem HTML und CSS, sowie die Templatesprache Liquid genutzt werden.

tiefgreifendere Anpassungen

Wenn das oben nicht ausreicht, muss aktuell leider der Code angepasst oder erweitert werden. Nach der Veränderung müssen die Assets, bzw. muss Keila neu gebaut werden. Im Folgenden werden hierzu Erkenntnisse festgehalten:

Block Editor

Header 4 ergänzen

diff --git a/assets/js/campaign-editors/block/index.js b/assets/js/campaign-editors/block/index.js
index af562cd..03faa4c 100644
--- a/assets/js/campaign-editors/block/index.js
+++ b/assets/js/campaign-editors/block/index.js
@@ -18,7 +18,7 @@ export default class BlockEditor {
         header: {
           class: Header,
           config: {
-            levels: [1, 2, 3]
+            levels: [1, 2, 3, 4]
           }
         },
         layout: {
@@ -28,7 +28,7 @@ export default class BlockEditor {
               header: {
                 class: Header,
                 config: {
-                  levels: [1, 2, 3]
+                  levels: [1, 2, 3, 4]
                 }
               },
               button: Button,

Dies ergänzt einen neuen Heading 4 Button. Die CSS scheint hier ohne weitere Anpassungen zu passen, allerdings wird dies erst in der Preview – nicht aber im Editor – ersichtlich.

Markdown Editor

Header 4 ergänzen

diff --git a/assets/js/campaign-editors/markdown/input-rules.js b/assets/js/campaign-editors/markdown/input-rules.js
index 2120fbb..7341337 100644
--- a/assets/js/campaign-editors/markdown/input-rules.js
+++ b/assets/js/campaign-editors/markdown/input-rules.js
@@ -12,7 +12,8 @@ const rules = inputRules({
     wrappingInputRule(/^\s*(-|\*|\+)\s$/, schema.nodes.bullet_list),
     textblockTypeInputRule(/^\s*\#\s$/, schema.nodes.heading, { level: 1 }),
     textblockTypeInputRule(/^\s*\#\#\s$/, schema.nodes.heading, { level: 2 }),
-    textblockTypeInputRule(/^\s*\#\#\#\s$/, schema.nodes.heading, { level: 3 })
+    textblockTypeInputRule(/^\s*\#\#\#\s$/, schema.nodes.heading, { level: 3 }),
+    textblockTypeInputRule(/^\s*\#\#\#\#\s$/, schema.nodes.heading, { level: 4 })
   ]
 })

Dies ergänzt keinen extra Button, aber wenn eine neue Zeile mit #### begonnen wird, wird automatisch ein h4 interpretiert. Die CSS scheint hier ohne weitere Anpassungen zu passen.

Troubleshooting

Loglevel konfigurieren

Um das Loglevel hochzusetzen kann die prod.exs manipuliert werden. Keila muss im Anschluss allerdings erneut gebaut werden:

diff --git a/config/prod.exs b/config/prod.exs
index 7272be4..a5c5aa2 100644
--- a/config/prod.exs
+++ b/config/prod.exs
@@ -16,7 +16,7 @@ config :keila, KeilaWeb.Endpoint,
   server: true

 # Do not print debug messages in production
-config :logger, level: :info
+config :logger, level: :debug

 config :keila, Keila.Repo, []

Links

• Keila Dokumentation
• Keila Homepage
• Installationsanleitung (Dockerfile)
• Release Übersicht