Keila: Unterschied zwischen den Versionen

Aus Hostsharing Wiki
Zur Navigation springen Zur Suche springen
 
(9 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
= Keila installieren =
= 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. Viele benötigen Double-Opt-In – dieses Feature [https://fosstodon.org/@keila/111507595655463062 wird in Keila v0.12.9 erwartet].
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:
Die Software ist in Erlang/Elixir geschrieben und stellt keine fertigen Binaries bereit, daher müssen wir von Hand bauen:
Zeile 36: Zeile 36:
== Keila bauen ==
== Keila bauen ==


Ehe wir beginnen, müssen wir für das Hostsharing Mailsystem noch eine Kleinigkeit anpassen. In <code>config/runtime.exs</code> suchen wir den Block:
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.


<syntaxhighlight lang=elixir line>
'''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.''
[
 
adapter: Swoosh.Adapters.SMTP,
<syntaxhighlight lang=diff line>
relay: host,
diff --git a/lib/keila/mailings/sender_adapters/smtp.ex b/lib/keila/mailings/sender_adapters/smtp.ex
username: user,
index ab4a37f..6b61b91 100644
password: password,
--- a/lib/keila/mailings/sender_adapters/smtp.ex
from_email: from_email
+++ 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
</syntaxhighlight>
</syntaxhighlight>


Hier ergänzen wir ein Komma hinter <code>from_email</code> und ergänzen die Zeile <code>no_mx_lookups: true</code>. Das Ergebnis sieht dann so aus:
Außerdem sollte Keila nicht auf Port <code>0.0.0.0</code> lauschen. Hier passen wir die <code>config/prod.exs</code> an.


<syntaxhighlight lang=elixir line>
<syntaxhighlight lang=diff line>
[
diff --git a/config/prod.exs b/config/prod.exs
  adapter: Swoosh.Adapters.SMTP,
index 7272be4..cb7fb3b 100644
relay: host,
--- a/config/prod.exs
  username: user,
+++ b/config/prod.exs
  password: password,
@@ -11,7 +11,7 @@ import Config
from_email: from_email,
# before starting your production server.
no_mx_lookups: true
  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
</syntaxhighlight>
</syntaxhighlight>
Okey, weiter:


Das ist wichtig, damit Keila sich nicht mit dem Posteingangs-Server versucht zu verbinden. Okey, weiter:
<syntaxhighlight lang=shell line>
# Es kann hier schon ein Updatescript bereitgelegt und ggf angepasst werden:
# https://dev.hostsharing.net/hostsharing/hs.scripts/src/branch/main/updates/keila.sh


<syntaxhighlight lang=shell line>
export MIX_ENV=prod
export MIX_ENV=prod


Zeile 178: Zeile 194:
* <code>systemctl restart --user keila</code>
* <code>systemctl restart --user keila</code>
** bei systemd Fehler sicherstellen das die nötige Variabel gesetzt ist (siehe oben, systemd)
** bei systemd Fehler sicherstellen das die nötige Variabel gesetzt ist (siehe oben, systemd)
<strong>Alternativ:</strong> [https://dev.hostsharing.net/hostsharing/hs.scripts/src/branch/main/updates/keila.sh 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 ====
<syntaxhighlight lang=diff line>
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,
</syntaxhighlight>
Dies ergänzt einen neuen <code>Heading 4</code> 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 ====
<syntaxhighlight lang=diff line>
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 })
  ]
})
</syntaxhighlight>
Dies ergänzt keinen extra Button, aber wenn eine neue Zeile mit <code>####</code> begonnen wird, wird automatisch ein <code>h4</code> interpretiert. Die CSS scheint hier ohne weitere Anpassungen zu passen.


= Troubleshooting =
= Troubleshooting =


== Loglevel konfigurieren ==
== Loglevel konfigurieren ==
Leider reicht es nicht immer <code>MIX_ENV</code> zu verwenden. Um das Loglevel hochzusetzen kann die <code>prod.exs</code> manipuliert werden. '''Keila muss im Anschluss allerdings erneut gebaut werden''':
Um das Loglevel hochzusetzen kann die <code>prod.exs</code> manipuliert werden. '''Keila muss im Anschluss allerdings erneut gebaut werden''':


<syntaxhighlight lang=diff line>
<syntaxhighlight lang=diff line>

Aktuelle Version vom 21. Juni 2024, 10:42 Uhr

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