BookWyrm-Server benötigen gewisse Umgebungsvariablen (engl. "environment", kurz ENV), um korrekt zu funktionieren. Diese werden in einer Datei namens .env gesetzt, die in dem Verzeichnis liegt, aus dem heraus du BookWyrm ausführst. Du wirst die meisten dieser Variablen in der Datei .env.example beschrieben finden, die im Hauptcoderepository liegt. Kopiere diese Datei und nutze sie als Basis für deine Datei .env.
BookWyrm-Instanzadministrator*innen sollten aufmerksam die Veröffentlichungshinweise jeder Version auf Änderungen oder Erweiterungen der Umgebungsvariablen prüfen.
Wo immer dies möglich ist, sollten BookWyrm-Entwickler*innen site.settings gegenüber ENV-Werten bevorzugen, wenn sie neue Konfigurationsoptionen einführen.
Die Datei .env.example beinhaltet Standardwerte für die Kerneinstellungen. Diese sind als sichere Standardwerte für Produktivumgebungen ausgelegt, abgesehen von den Standardpasswörtern. Nutzer*innen von Docker können ./bw-dev create_secrets ausführen, um sichere und einzigartige Geheimnisse für folgende Variablen zu generieren:
SECRET_KEYPOSTGRES_PASSWORDREDIS_ACTIVITY_PASSWORDREDIS_BROKER_PASSWORDFLOWER_PASSWORDDu musst jeder dieser Einstellungen in deiner .env-Datei angemessene Werte zuweisen:
SECRET_KEYDOMAINFLOWER_USERFLOWER_PASSWORDFLOWER_PORTEMAIL_HOSTEMAIL_PORTEMAIL_HOST_USEREMAIL_HOST_PASSWORDEMAIL_USE_TLSEMAIL_USE_SSLEMAIL_SENDER_NAMEPOSTGRES_USERPOSTGRES_DBPOSTGRES_HOSTPOSTGRES_PASSWORDREDIS_BROKER_HOSTREDIS_BROKER_PORTREDIS_ACTIVITY_HOSTREDIS_ACTIVITY_PORTREDIS_ACTIVITY_PASSWORDREDIS_BROKER_PASSWORDWenn BookWyrm in einer Entwicklungsumgebung betrieben wird:
NGINX_SETUP muss reverse_proxy zugewiesen werdenDEBUG sollte true zugewiesen werdenDOMAIN darf localhost zugewiesen werdenWenn BookWyrm in einer Produktivumgebung betrieben wird:
DEBUG muss false zugewiesen werdenDOMAIN darf nicht localhost zugewiesen werdenLerne mehr über alle diese Einstellungen in der Django-Referenz.
ALLOWED_HOSTSEine Liste von Zeichenketten, die die Hosts und Domain-Namen representieren, unter denen diese Seite ausgeliefert werden darf. Dies ist eine Sicherheitsmaßnahme, um HTTP-Host-Header-Angriffe zu verhindern, die selbst bei vielen scheinbar sicheren Web-Server-Konfigurationen möglich sind.
Der Standard ist es, alle Hosts zuzulassen, aber du solltest dies ändern. Beispiel: "localhost,bookwyrm.example.com"
MEDIA_ROOTimagesAbsoluter Dateipfad zu dem Verzeichnis, das von Nutzer*innen hochgeladene Dateien enthält. Wenn Docker zum Einsatz kommt, denke daran, dass dieses Verzeichnis innerhalb deines Containers liegt, nicht auf der Host-Maschine.
SECRET_KEY"7(2w1sedok=aznpq)ta1mc4i%4h=xx@hxwx*o57ctsuml0x%fr"Ein geheimer Schlüssel für die jeweilige BookWyrm-Instanz. Er wird genutzt, um kryptographische Signaturen bereitzustellen, und sollte auf eine einzigartige, nicht vorhersagbare, lange Zeichenkette festgelegt werden.
Wenn du den SECRET_KEY in .env.example nicht änderst, wird BookWyrm eine Fehlermeldung zeigen und sich weigern, zu starten.
STATIC_ROOTstaticDer absolute Pfad zu dem Verzeichnis, in dem collectstatic alle statischen Dateien zur Auslieferung aufsammelt. Wenn Docker zum Einsatz kommt, denke daran, dass dieses Verzeichnis innerhalb deines Containers liegt, nicht auf der Host-Maschine.
DEBUGfalseDEBUG stellt in der Weboberfläche nützliche Fehlerinformationen bereit, die zum Debuggen des Entwicklungsservers genutzt werden können.
In Produktivsystemen sollte false zugewiesen werden. Stelle niemals eine Seite öffentlich zur Verfügung, bei der DEBUG auf true gesetzt wurde.
Hinweis: Bis einschließlich Version 0.7.5 war der Standardwert für DEBUG true.
LANGUAGE_CODE"en-us"Eine Zeichenkette, die die Standardsprache für diese Installation repräsentiert.
SESSION_COOKIE_AGE2592000Die Zeit, bis man abgemeldet wird (in Sekunden). Der Standardwert entspricht 30 Tagen. Zukünftig wird dieser Wert voraussichtlich auf ein Jahr geändert.
DATA_UPLOAD_MAX_MEMORY_MiB100Maximal erlaubter Speicher für Dateiuploads. Du kannst dies erhöhen, wenn Nutzer*innen Probleme beim Upload von BookWyrm-Exportdateien feststellen. Die eigentliche Django-Einstellung ist DATA_UPLOAD_MAX_MEMORY_SIZE, allerdings nutzen wir in der .env-Datei diese Variable, um Instanz-Administrator*innen zu erlauben, den Wert in Mebibytes anstelle von Bytes anzugeben.
DEFAULT_LANGUAGEEnglishBücher werden in Suchergebnissen priorisiert, wenn eine ihrer Sprachen (im Feld language) diesem Wert entspricht.
DOMAINDer Fully Qualified Domain Name deiner Website. Gib kein Protokoll und keinen Port an. Beispiel: example.com oder subdomain.example.com.
EMAILDie Adresse wird in der docker-compose.yml-Datei des production-Branches an Certbot weitergereicht.
NGINX_SETUPhttpshttps, reverse_proxySignalisiert die nginx-Konfiguration. https nimmt an, dass der gesamte Datenverkehr durch BookWyrms nginx-Container gehandhabt wird. In dieser Konfiguration wird versucht, mit Certbot ein HTTPS-Zertifikat zu erstellen. reverse_proxy dagegen nimmt an, dass der Datenverkehr von einem vorgeschalteten Webserver zwischen BookWyrm und der Außenwelt gehandhabt wird. In der Entwicklungsumgebung sollte immer reverse_proxy gesetzt werden.
PORT443, oder 80, wenn die Domain localhost entspricht.Der Port, der für die Kommunikation im Web genutzt wird. Beachte, dass diese Einstellung sich von Djangos PORT unterscheidet.
USE_HTTPSDiese Variable wurde nach Version v0.7.5 obsolet. Es wird angenommen, dass deine Instanz HTTPS verwendet, sofern die Domain nicht localhost ist.
Diese Konfiguration kann künftig zu site.settings verschoben werden.
SEARCH_TIMEOUT8Die Höchstdauer in Sekunden, die die Instanz nutzen wird, um über Konnektoren Inhalte zu suchen.
QUERY_TIMEOUT5Zeitbeschränkung für eine Anfrage an einen einzelnen Konnektor.
Die Hauptdatenbank für BookWyrm nutzt Postgres.
PGPORT5432Der Port, um sich mit dem Postgres-Server zu verbinden. Entspricht Djangos PORT.
POSTGRES_PASSWORDbookwyrmPasswort für die Datenbank. Lege hier ein starkes Passwort fest. Setze es in Anführungszeichen, um Probleme mit der Fehlinterpretation gewisser Zeichen zu vermeiden.
Nutze weder die Standardwerte aus .env noch aus setings.py, da diese öffentlich bekannt sind.
POSTGRES_USERbookwyrmDer Name deines Datenbankbenutzers. Entspricht Djangos USER.
POSTGRES_DBbookwyrmDer Name deiner Datenbank.
POSTGRES_HOSTlocalhostDer Host-Server deiner Datenbank. Wird dieser Wert nicht gesetzt oder leer gelassen, wird localhost angenommen. Entspricht Djangos HOST.
Redis wird verwendet, um sowohl Aktivitätsströme als auch Hintergrundaufgaben zu verwalten.
MAX_STREAM_LENGTH200Die Maximallänge für Redis-Streams. Wird ein Stream größer, wird Redis die ältesten Elemente verwerfen, um die MAX_STREAM_LENGTH nicht zu überschreiten.
Siehe Redis-XTRIM-Dokumentation für weitere Details.
REDIS_ACTIVITY_HOSTlocalhostDer Redis-Server-Host. Wird als localhost angenommen, sofern nichts anderes angegeben wird. Wenn du Docker verwendest, sollte der Wert üblicherweise redis_activity sein, damit du den gleichnamigen Redis-Container verwendest.
REDIS_ACTIVITY_PORT6379Der Port, den dein Redis-Server verwendet.
REDIS_ACTIVITY_PASSWORDDas Passwort für deine Redis-Datenbank.
REDIS_ACTIVITY_DB_INDEXWenn du nicht das Standard-Docker-Setup mit separatem Redis-Server für Aktivitäts-Streams verwendest, solltest du REDIS_ACTIVITY_DB_INDEX setzen, um zu signalisieren, welche Redis-Datenbank für BookWyrms Aktivitätsströme verwendet wird.
REDIS_ACTIVITY_URLWenn du eine externe Redis-Datenbank oder einen Unix-Socket verwendest, kannst du alle anderen Redis-Einstellungen überschreiben, indem du die volle REDIS_ACTIVITY_URL setzt.
Beispiel: "redis://username:top_secret_pass@example.com:6380/0"
REDIS_BROKER_HOSTlocalhostDer Redis-Celery-Server-Host. Wird als localhost angenommen, sofern nichts anderes angegeben wird. Wenn du Docker verwendest, sollte der Wert üblicherweise redis_broker sein, damit du den gleichnamigen Redis-Container verwendest.
REDIS_BROKER_PORT6379Der Port, den dein Redis-Celery-Server verwendet.
REDIS_BROKER_PASSWORDDas Passwort für deine Redis-Celery-Datenbank.
REDIS_BROKER_DB_INDEXWenn du nicht das Standard-Docker-Setup mit separatem Redis-Server für Celery verwendest, solltest du REDIS_ACTIVITY_DB_INDEX setzen, um zu signalisieren, welche Redis-Datenbank für BookWyrms Aktivitätsströme verwendet wird.
REDIS_BROKER_URLWenn du eine externe Redis-Datenbank oder einen Unix-Socket verwendest, kannst du alle anderen Redis-Einstellungen für deine Celery-Datenbank überschreiben, indem du die volle REDIS_BROKER_URL setzt.
Beispiel: "redis://username:top_secret_pass@example.com:6380/0"
Flower stellt eine Weboberfläche zur Verfügung, um Celery-Tasks zu überwachen.
FLOWER_PORT8888Der Port für die Flower-Seite, um Celery unter https://example.com/flower zu überwachen.
FLOWER_USERDer Nutzer deiner Flower-Instanz.
FLOWER_PASSWORDDas Passwort für deine Flower-Überwachungsoberfläche. Flower kann alle Nachrichten sehen, die deinen Server erreichen, daher ist es wichtig, dass du ein starkes, einzigartiges Passwort setzt und dieses sicher verwahrst.
EMAIL_HOSTDie SMTP-Adresse deines E-Mail-Hosts. Beispiel: smtp.mailgun.org. Prüfe stets die Nutzungsbedingungen deines E-Mail-Anbieters, bevor du deinen Account nutzt, um große Mengen E-Mails zu versenden. Du wirst vermutlich einen Dienst wie Mailgun benötigen.
EMAIL_PORT587Der SMTP-Server-Port deines E-Mail-Anbieters.
EMAIL_HOST_USERDer Nutzername deines E-Mail-Anbieters. Normalerweise eine volle E-Mail-Adresse wie mail@your.domain.here.
EMAIL_HOST_PASSWORDDas Passwort für den Account bei deinem E-Mail-Anbieter.
EMAIL_USE_TLStrueOb deine SMTP-Verbidung TLS nutzt. Prüfem hierfür, ob du den richtigen EMAIL_PORT verwendest.
EMAIL_USE_SSLfalseOb deine SMTP-Verbidung SSL nutzt. Prüfem hierfür, ob du den richtigen EMAIL_PORT verwendest.
EMAIL_SENDER_NAMEadminDer erste Teil der E-Mail-Adresse für Nachrichten, die deine BookWyrm-Instanz versendet. Beispiel: admin@example.com.
EMAIL_SENDER_DOMAINDOMAINDie Domain der E-Mail-Adresse für Nachrichten, die deine BookWyrm-Instanz versendet. Beispiel: admin@example.com.
USE_S3falseZeigt an, ob du S3-Object-Storage für Bilder und statische Dateien nutzt.
USE_S3_FOR_EXPORTSfalseZeigt an, ob du S3-Object-Storage für Dateien bei Kontoexporten und -importen nutzt. Standardmäßig beinhaltet USE_S3 Kontoimporte und -exporte nicht. Es ist sicherer, hierfür den lokalen Speicher zu verwenden und den normalen Dateilöschvorgang regelmäßig auszuführen. Auf größeren Instanzen kann der lokale Speicher Performanzprobleme hervorrufen und es kann sich anbieten, diesen Wert auf true zu setzen.
S3_SIGNED_URL_EXPIRY900Die Anzahl an Sekunden, bevor signierte S3-URLs ablaufen. Dies wird aktuell nur für Konto-Exportdateien verwendet. Der Wert sollte nur so groß sein, wie es notwendig ist, um als Nutzer*in einen Download abzuschließen, nachdem man bei Abschluss eines Exports auf "Herunterladen" geklickt hat.
AWS_ACCESS_KEY_IDZugriffsschlüssel für S3-Speicher aller Art.
AWS_DEFAULT_ACLBackblaze (B2) erkennt "public-read" nicht als eine Standard-ACL-Einstellung an. Backblaze-Nutzer*innen sollten daher eine leere Zeichenkette angeben.
AWS_SECRET_ACCESS_KEYGeheimer Schlüssel für S3-Speicher aller Art.
AWS_STORAGE_BUCKET_NAMEDer Bucket-Name, den du nutzt. Beispiel: "example-bucket-name"
AWS_S3_REGION_NAMEDer S3-Regionenname. Beispiel: "eu-west-1" für AWS, "fr-par" für Scaleway, "nyc3" für Digital Ocean oder "cluster-id" für Linode.
AWS_S3_CUSTOM_DOMAINDie Domain, unter der Assets ausgeliefert werden. Beispiel: "example-bucket-name.s3.fr-par.scw.cloud"
AWS_S3_URL_PROTOCOLPROTOCOL mit Doppelpunkt, also etwa "http:"Protokoll für den S3-Speicher. Wird in der Produktivumgebung standardmäßig als https: angenommen. Du musst dies nicht setzen, sofern du das Standardverhalten nicht überschreiben möchtest.
AWS_S3_ENDPOINT_URLDer S3-API-Endpunkt. Beispiel: "https://s3.fr-par.scw.cloud"
Diese Werte werden benötigt, wenn Azure-Blob-Storage zum Einsatz kommt.
USE_AZUREfalseAZURE_ACCOUNT_NAMEBeispiel: "example-account-name"
AZURE_ACCOUNT_KEYBeispiel: "Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw=="
AZURE_CONTAINERDer einzigartige Name deines Containers. Beispiel: "example-blob-container-name".
AZURE_CUSTOM_DOMAINDu kannst eine eigene Domain für den Azure-Blob-Storage nutzen, aber dies ist nicht notwendig. Beispiel: "example-account-name.blob.core.windows.net".
Teile dieser Konfiguration könnten künftig zu site.settings verschoben werden.
ENABLE_THUMBNAIL_GENERATIONfalseOb die Generierung von Vorschaubildern für Buch-Titelbilder aktiviert werden soll. Wenn du dies auf true setzt, wird die Performanz beim Rendern der Bilder verbessert. Allerdings wird für das Speichern der Titelbilder 4- bis 5-mal soviel Speicher benötigt. Aus diesem Grund ist der Standardwert false.
ENABLE_PREVIEW_IMAGESfalseDiese Einstellung erlaubt es dem Server, Vorschaubilder zu generieren, die als OpenGraph-Bilder (auch als Twitter-Card-Bilder bekannt) genutzt werden. Diese Vorschaubilder werden für Bücher (jedes Mal, wenn sich der Titel, das Vorschaubild oder der*die Autor*in ändern oder wenn eine neue öffentliche Bewertung veröffentlicht wird), Konten (jedes Mal, wenn sich der Name oder Avatar ändert) und die Website (jedes Mal, wenn sich der Seitenname, die Beschreibung oder das Logo ändert) generiert. Siehe Optionale Features für weitere Informationen.
PREVIEW_BG_COLORuse_dominant_color_lightDie Hintergrundfarbe für Vorschaubilder. Du kannst ein RGB-Tupel oder RGB-Hex-Werte angeben oder use_dominant_color_light/use_dominant_color_dark angeben.
PREVIEW_TEXT_COLOR#363636Die Textfarbe für Vorschaubilder. Wenn die PREVIEW_BG_COLOR auf use_dominant_color_dark gesetzt ist, sollte dies #fff sein.
PREVIEW_IMG_WIDTH1200Breite für Vorschaubilder in Pixeln.
PREVIEW_IMG_HEIGHT630Höhe für Vorschaubilder in Pixeln.
PREVIEW_DEFAULT_COVER_COLOR#002549Wenn es zu einem Buch kein Titelbild gibt, erstellen wir ein neues Titelbild. Diese Einstellung bestimmt die Farbe dieses neuen Titelbilds.
PREVIEW_DEFAULT_FONTSource Han SansWenn es zu einem Buch kein Titelbild gibt, erstellen wir ein neues Titelbild. Diese Einstellung bestimmt die Schriftart dieses neuen Titelbilds.
Nutze diese Einstellungen, um das automatische Senden von Telemetriedaten an OTLP-kompatible Dienste zu aktivieren. Viele der Haupt-Verwaltungsanwendungen haben OLTP-Konnektoren, einschließlich NewRelic, DataDog und Honeycomb.io – lies in ihren Dokumentationen nach, wie du sie aufsetzt.
OTEL_EXPORTER_OTLP_ENDPOINTAPI-Endpunkt deines Anbieters.
OTEL_EXPORTER_OTLP_HEADERSAlle Header, die benötigt werden, üblicherweise für Authentifizierungs-Informationen.
OTEL_SERVICE_NAMEDer Dienstname ist ein arbiträrer Tag, der allen versendeten Daten hinzugefügt wird, um verschiedene Quellen zu unterscheiden. Er kann nützlich sein, um Produktiv- und Entwicklungsmetriken am selben Ort zu sammeln und sie dort zu trennen.
HTTP_X_FORWARDED_PROTOfalseWenn du dies auf true setzt, kann das die Sicherheit deiner Website kompromittieren. Stelle sicher, dass du dein Setup komplett verstehst, bevor du dies änderst.
Nutze es nur, wenn dein Proxy "verschluckt", ob die originäre Anfrage per HTTPS erfolgte. Bitte sieh in der Django-Dokumentation nach und bewerte die Risiken für deine Instanz.
CSP_ADDITIONAL_HOSTSZusätzliche Hosts, die in der Content-Security-Policy erlaubt werden sollen; "self" (sollte DOMAIN mit optionalem Doppelpunkt und PORT sein) und AWS_S3_CUSTOM_DOMAIN (sofern verwendet) werden standardmäßig hinzugefügt. Der Wert sollte eine kommaseparierte Liste von Hostnamen sein.
Teile dieser Konfiguration könnten künftig zu site.settings verschoben werden.
TWO_FACTOR_LOGIN_VALIDITY_WINDOW2Setzt die Zeit, in der die Codes von beiden Seiten akzeptiert werden. Dies sollte eine niedrige Zahl sein, aber du kannst sie erhöhen, wenn deine Nutzer*innen hohe Netzwerklatenzen erfahren und ihre Codes ablaufen, bevor sie den Login abschließen können. Mit der Standardeinstellung hierfür und TWO_FACTOR_LOGIN_MAX_SECONDS haben Nutzer*innen bis zu 180 Sekunden, um einen Code zu verwenden. Sie können einen gültigen Code bis zu zwei vor dem aktuellen verwenden.
TWO_FACTOR_LOGIN_MAX_SECONDS60Zeit in Sekunden, für die ein Login-Code gültig ist.