Hosting Listmonk na Managed VPS: Państwa newslettery na Państwa serwerze

Co robi Listmonk

Listmonk zarządza Państwa listami mailingowymi i newsletterami z poziomu interfejsu webowego. To pojedynczy program, napisany w Go, którego jedyną zależnością jest PostgreSQL. Jego listy są jednokierunkowe: Państwo piszą do subskrybentów, a nie jest to lista dyskusyjna między nimi.

• Listy: listy z pojedynczym lub podwójnym opt-in, aż do milionów subskrybentów, oraz segmentacja wyrażeniami SQL po ich atrybutach.
• Kampanie: wizualny edytor typu przeciągnij i upuść, edytor WYSIWYG, Markdown, HTML lub zwykły tekst oraz szablony w języku Go z ponad 100 funkcjami.
• Statystyki: otwarcia, kliknięcia, odbicia i najczęściej klikane linki, kampania po kampanii.
• Wiadomości transakcyjne: API do wysyłania wiadomości według szablonu, na przykład potwierdzenia zamówienia. „Messengery” w postaci webhooków HTTP otwierają też SMS i WhatsApp, do podłączenia do wybranej przez Państwa usługi.
• Subskrybenci: strona, na której każdy zarządza swoimi preferencjami, eksportuje swoje dane lub je usuwa.
• Zespół: precyzyjne role i uprawnienia, jednokrotne logowanie OIDC i ograniczone tokeny API.
• Media: biblioteka obrazów na dysku lub w magazynie zgodnym z S3.

Na co pozwala licencja AGPL-3.0

Listmonk jest udostępniany na licencji GNU AGPL w wersji 3. Mogą Państwo go używać, także w firmie, i wysyłać swoje kampanie oraz kampanie swoich klientów, bez zakupu licencji. Pozostaje koszt serwera i koszt Państwa usługi wysyłkowej.

Artykuł 13 dodaje warunek właściwy dla AGPL: jeśli Państwo zmodyfikują program, Państwa wersja musi wyraźnie proponować każdemu, kto korzysta z niej zdalnie, przez sieć, bezpłatne uzyskanie jej kodu źródłowego. Jeśli rozpowszechniają Państwo kopie, stosują się też obowiązki licencji dotyczące udostępniania kodu. Uruchamianie Listmonk bez modyfikacji nie uruchamia tego artykułu.

Którą wersję Listmonk zainstalować?

Jedna rzecz, którą warto znać na początku. Na GitHubie etykieta „Latest” wskazuje obecnie v7.0.0-beta.2 z 10 listopada 2026 roku, którą sam projekt przedstawia jako betę. Ostatnia wersja stabilna to v6.2.0, zawierająca poprawki bezpieczeństwa dotyczące uprawnień. Na 11 listopada 2026 roku obraz Docker latest wskazuje tę v6.2.0.

Wersja 7 zastępuje cały interfejs administracyjny, zmienia niektóre jego adresy, czyni z ustawienia app.from_email listę adresów i modyfikuje klucze tłumaczeń, co dotyka szablonów własnych. Przed przejściem proszę przeczytać jej informacje o wydaniu.

Plik Compose projektu uruchamia --upgrade --yes przy każdym starcie: nowy obraz migruje bazę bez pytania. Tymczasem zmigrowanej bazy nie da się odczytać starszą wersją, a powrót wymaga przywrócenia kopii zapasowej. Przy stałym tagu, jak v6.2.0, zmiana wersji pozostaje Państwa decyzją.

Instalacja przez Docker Compose

Projekt zaleca Docker Compose: jego plik uruchamia Listmonk i PostgreSQL razem. Na serwerze z zainstalowanym Dockerem proszę utworzyć katalog i pobrać ten plik:

mkdir listmonk
cd listmonk
curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml

Projekt każe dostosować ten plik do Państwa środowiska. Oto jedyne linie do zmiany, reszta pozostaje bez zmian:

x-db-credentials: &db-credentials
  POSTGRES_USER: &db-user listmonk
  POSTGRES_PASSWORD: &db-password un-mot-de-passe-long
  POSTGRES_DB: &db-name listmonk

services:
  app:
    image: listmonk/listmonk:v6.2.0
    ports:
      - "127.0.0.1:9000:9000"
    hostname: listmonk.example.com

• Hasło do bazy: plik podaje listmonk jako wartość wyjściową. Proszę zmienić je przed pierwszym uruchomieniem, ponieważ obraz PostgreSQL odczytuje tę zmienną tylko przy pustym katalogu danych.
• Obraz: konkretna wersja zamiast latest, z powodu opisanego wyżej.
• Port opublikowany na 127.0.0.1: to nasza adaptacja. Plik projektu publikuje port 9000 bez ograniczenia adresu, a PostgreSQL ogranicza już do adresu lokalnego. Potraktowany tak samo, Listmonk jest osiągalny wyłącznie przez odwrotne proxy.
• Nazwa hosta: plik zaleca pełną nazwę domeny.

Następnie proszę uruchomić usługi, tworząc z góry konto Super Admin. Te dwie zmienne służą tylko przy pierwszym uruchomieniu, a bez nich konto powstaje przy pierwszej wizycie w interfejsie: lepiej, by istniało, zanim otworzą Państwo swoją domenę.

LISTMONK_ADMIN_USER=votre-identifiant LISTMONK_ADMIN_PASSWORD=votre-mot-de-passe docker compose up -d

Bez Dockera: plik binarny

Listmonk działa też jako samodzielny program, obok Państwa własnego serwera PostgreSQL w wersji 12 lub nowszej, w którym baza jest już utworzona.

1. Proszę pobrać archiwum v6.2.0 ze strony wydań projektu, na przykład listmonk_6.2.0_linux_amd64.tar.gz, unikając bety wyświetlanej na górze, i rozpakować plik binarny.
2. Proszę wygenerować plik konfiguracyjny, a następnie wpisać dane dostępowe do bazy w config.toml.
3. Proszę zainstalować tabele, a potem uruchomić Listmonk.

./listmonk --new-config
./listmonk --install
./listmonk

Domyślnie config.toml nasłuchuje na localhost:9000, co pasuje za odwrotnym proxy. Repozytorium dostarcza plik usługi listmonk@.service dla systemd.

Rozmiar serwera

Strona projektu podaje instancję produkcyjną, która wysyła kampanię liczącą ponad 7 milionów e-maili, używając ułamka rdzenia procesora i szczytowo 57 MB pamięci. Nie publikuje ani minimum, ani liczby dla PostgreSQL, którego objętość rośnie wraz z subskrybentami, otwarciami i kliknięciami. Na Managed VPS wystarczy opisać nam swoje zastosowanie, a polecimy odpowiedni rozmiar.

HTTPS i odwrotne proxy

Państwa subskrybenci klikają linki wskazujące na Państwa instancję: wypisanie, potwierdzenie, śledzenie kliknięć. Udostępnia się ją więc przez HTTPS pod własną nazwą domeny. Rekordy A i AAAA tej nazwy proszę skierować na serwer, na którego porty 80 i 443 docierają odwiedzający. Dokumentacja Listmonk zostawia wybór proxy, oto dwie typowe konfiguracje.

Z Caddy

Caddy samodzielnie uzyskuje i odnawia certyfikat:

listmonk.example.com {
    reverse_proxy 127.0.0.1:9000
}

Z Nginx i Certbotem

Nginx domyślnie odrzuca żądania większe niż 1 MB, z błędem 413. Aby zaimportować plik subskrybentów albo obrazy, proszę podnieść ten limit stosownie do swoich plików:

server {
    listen 80;
    listen [::]:80;
    server_name listmonk.example.com;
    client_max_body_size 100m;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Certbot następnie instaluje certyfikat Let’s Encrypt oraz przekierowanie na HTTPS, a potem sam go odnawia:

sudo certbot --nginx -d listmonk.example.com

Pierwsze ustawienia

Proszę zalogować się na https://listmonk.example.com/admin, a następnie otworzyć „Settings”:

• „General”, „Root URL”: publiczny adres Państwa instancji, bez ukośnika na końcu, jak https://listmonk.example.com. Listmonk buduje z niego linki do wypisania, potwierdzenia i śledzenia w Państwa e-mailach. Jego wartość wyjściowa, http://localhost:9000, nie działałaby u Państwa subskrybentów.
• „General”, „Default from email”: domyślny adres nadawcy, w Państwa domenie, zamiast podanego przykładu.
• „Media”, „Upload path”: /listmonk/uploads, katalog, który plik Compose montuje na serwerze.
• „General”: publiczna strona zapisu i publiczne archiwum są na początku aktywne. Proszę je zachować, jeśli są Państwu potrzebne.
• „Security”, „Enable CAPTCHA”: na początku wyłączone, chroni publiczny formularz zapisu.

Co pozostaje publiczne, a co można zamknąć

Aby filtrować dostęp, według adresu IP lub przez proxy uwierzytelniające, dokumentacja dzieli trasy w ten sposób:

Wysyłka: Listmonk korzysta z Państwa serwerów SMTP

Listmonk przygotowuje i dozuje Państwa e-maile, a następnie powierza je serwerom SMTP, które Państwo zadeklarują w „Settings”, „SMTP”. Sam nie dostarcza ich do skrzynek subskrybentów: jakość dostarczania zależy więc od tego serwera, Państwa domeny i Państwa list.

Do wysyłki masowej proszę wybrać wyspecjalizowaną usługę wysyłkową: niesie ona reputację Państwa wysyłek i podpisy Państwa domeny oraz potrafi przekazywać odbicia. Z VPS Simafri wysyłka odbywa się przez uwierzytelniony przekaźnik SMTP, na porcie 587: tutaj przekaźnik tej usługi.

Dla orientacji dokumentacja Listmonk opisuje odbicia Amazon SES, Azure Communication Services, SendGrid, Postmark, Forward Email i Lettermint. Proszę je porównać według swojego wolumenu i odbiorców.

Następnie proszę kliknąć „Test connection”: Listmonk wysyła wiadomość próbną i wyświetla błąd serwera, jeśli wysyłka się nie powiedzie. Mogą Państwo zadeklarować kilka serwerów, wybrać jeden z nich dla kampanii albo kierować wysyłki według adresu lub domeny nadawcy.

Przepustowość

Ustawia się ją w „Settings”, „Performance”, poniżej limitu Państwa usługi:

• „Concurrency” i „Message rate”: liczba wątków wysyłki oraz wiadomości na sekundę dla każdego z nich. Wartości wyjściowe, 10 i 10, pozwalają na do 100 wiadomości na sekundę.
• „Batch size”: liczba subskrybentów odczytywanych z bazy przy każdym przebiegu, na początku 1 000, do utrzymania powyżej docelowej przepustowości. Wyższa zużywa więcej pamięci.
• „Enable sliding window limit”: pułap wiadomości w danym czasie, przydatny, gdy Państwa usługa liczy godzinowo.
• „Maximum error threshold”: liczba błędów, po przekroczeniu której kampania zostaje wstrzymana.

Wiadomość, która się nie powiodła, jest ponawiana według ustawienia „Retries”, na innych połączeniach serwera. Jeśli znów się nie powiedzie, Listmonk odnotowuje błąd i przechodzi do następnej: podczas dużej kampanii proszę obserwować te błędy.

Dostarczalność, wypisanie i zgoda

Samodzielny hosting aplikacji czyni Państwa panami tych kwestii, a to one decydują, czy Państwa e-maile dotrą.

SPF, DKIM i DMARC

Proszę wysyłać z adresu w swojej domenie i opublikować w jej strefie DNS rekordy SPF i DKIM, które podaje Państwa usługa wysyłkowa, razem z rekordem DMARC. Google wymaga wszystkich trzech od nadawców wysyłających ponad 5 000 wiadomości dziennie na konta Gmail, z domeną nadawcy zgodną z SPF lub DKIM, wypisaniem jednym kliknięciem dla wiadomości marketingowych oraz odsetkiem zgłoszeń spamu poniżej 0,30 %, najlepiej poniżej 0,10 %.

Wypisanie

• W wiadomości: {{ UnsubscribeURL }} proszę umieścić w stopce szablonu. Ten link prowadzi do zarządzania preferencjami i wypisania.
• W nagłówkach: opcja „Include List-Unsubscribe header” w „Settings”, „Privacy”, domyślnie aktywna, pozwala programom pocztowym proponować wypisanie jednym kliknięciem.
• Dane: ta sama strona ustawień daje subskrybentowi prawo do eksportu swoich danych, ich usunięcia i wpisania się na listę blokad. Te opcje są domyślnie aktywne.

Zgoda Państwa odbiorców

Listmonk stosuje typ listy, który Państwo wybiorą. Na liście z pojedynczym opt-in subskrybent dodany bez potwierdzenia i tak otrzymuje Państwa kampanie. Na liście z podwójnym opt-in otrzymuje najpierw e-mail z potwierdzeniem, a kampanie otrzymują tylko potwierdzeni subskrybenci. To wybór, który najlepiej chroni reputację Państwa wysyłek i zachowuje wyraźny ślad zgody.

Zasady zależą od kraju odbiorców. We Francji, na przykład, CNIL wymaga uprzedniej zgody osób prywatnych, wyrażonej aktywnym działaniem, jak niezaznaczone domyślnie pole, z wyjątkiem Państwa klientów w odniesieniu do podobnych produktów lub usług. Między przedsiębiorcami prospekcja może opierać się na uzasadnionym interesie, jeśli dotyczy ich zawodu. W każdym przypadku każda wiadomość wskazuje nadawcę i oferuje prosty sposób odmowy kolejnych.

Proszę pisać tylko do osób, które oczekują Państwa wiadomości. Lista kupiona lub stara zwiększa liczbę odbić i zgłoszeń spamu, a konsekwencje ponosi Państwa domena.

Śledzenie otwarć i kliknięć

Piksel śledzący i śledzenie kliknięć dotykają prywatności, a dokumentacja prosi o używanie ich z poszanowaniem przepisów takich jak RODO. Domyślnie to śledzenie nie jest powiązane z poszczególnymi subskrybentami: opcja „Individual subscriber tracking” je łączy, a „Disable tracking” wyłącza całkowicie, w „Settings”, „Privacy”.

Odbicia

Dalsze pisanie na adres, który odrzuca Państwa wiadomości, psuje reputację wysyłek. Obsługa odbić jest na początku wyłączona: proszę włączyć ją w „Settings”, „Bounces”, a następnie wybrać jedną z dwóch dróg.

• Webhook Państwa usługi wysyłkowej: proszę włączyć „Enable bounce webhooks” i opcję swojej usługi. Listmonk odbiera odbicia z SES, Azure Communication Services, SendGrid, Postmark, Forward Email i Lettermint pod adresem takim jak https://listmonk.example.com/webhooks/service/ses, przy czym ostatni człon zależy od usługi. Ten adres musi pozostać publiczny.
• Skrzynka POP3: Listmonk odczytuje skrzynkę, która odbiera odbicia, Państwa adresu nadawcy lub dedykowaną. Typ odbicia odgaduje wtedy na podstawie treści wiadomości, a to, czego nie rozpozna, uznaje za lekkie.

Dla skrzynki dedykowanej proszę zadeklarować ją jako adres zwrotny w „Settings”, „SMTP”, „Custom headers”:

[
  {"Return-Path": "your-bounce-inbox@example.com"}
]

Ustawienia wyjściowe to te, które dokumentacja podaje dla SES, i stanowią dobrą podstawę:

PostgreSQL, jedyna zależność

Listmonk wymaga PostgreSQL 12 lub nowszego. Plik Compose dostarcza postgres:17-alpine, z danymi w wolumenie Docker listmonk-data. Subskrybenci, kampanie, szablony, statystyki i większość ustawień mieszkają tam; w konfiguracji pozostają tylko dane dostępowe do bazy i adres nasłuchu.

Aby wskazać istniejący serwer PostgreSQL, proszę zmienić zmienne LISTMONK_db__host, LISTMONK_db__port, LISTMONK_db__user, LISTMONK_db__password i LISTMONK_db__database usługi app.

Listmonk zaprojektowano z myślą o dużych listach. W miarę jak baza rośnie, to ona może spowalniać interfejs: przy milionach subskrybentów panel i liczniki mogą wyświetlać się kilkadziesiąt sekund. Projekt radzi wtedy dwa kroki:

• „Cache slow database queries”, w „Settings”, „Performance”: liczniki są wyliczane w regularnych odstępach, domyślnie co noc o 3:00.
• VACUUM ANALYZE na dużej bazie, na przykład co tydzień. Polecenie blokuje zapytania na czas działania, zwykle kilka sekund.

docker compose exec db psql -U listmonk -d listmonk -c 'VACUUM ANALYZE;'

Kopie zapasowe i aktualizacje

Państwa instancję tworzą dwa elementy: baza PostgreSQL i katalog uploads, jeśli obrazy pozostają na dysku. pg_dump tworzy spójny eksport bez zatrzymywania Listmonk i bez blokowania pozostałego dostępu do bazy:

docker compose exec -T db pg_dump -U listmonk listmonk > listmonk-$(date +%F).sql
tar -czf listmonk-uploads-$(date +%F).tar.gz uploads

Aby przywrócić, proszę zatrzymać Listmonk, opróżnić bazę, a potem wczytać eksport ponownie. Jak zaznacza dokumentacja, ta czynność kasuje obecną bazę:

docker compose stop app
docker compose exec db psql -U listmonk -d listmonk -c 'DROP SCHEMA public CASCADE; CREATE SCHEMA public;'
docker compose exec -T db psql -U listmonk -d listmonk < listmonk-2026-11-01.sql
docker compose start app

Aktualizacja

1. Proszę przeczytać informacje o nowej wersji: Listmonk sygnalizuje nowe wersje w swoim interfejsie, a niektóre zawierają poprawki bezpieczeństwa.
2. Proszę wyeksportować bazę, jak projekt każe przed każdą aktualizacją.
3. Proszę zmienić tag obrazu w docker-compose.yml.
4. Proszę uruchomić polecenia z dokumentacji. Plik Compose migruje bazę przy starcie.

docker compose down app
docker compose pull
docker compose up app -d

W przypadku pliku binarnego proszę zatrzymać Listmonk, zastąpić plik binarny, uruchomić ./listmonk --upgrade, a potem uruchomić go ponownie. Aby wrócić do wersji wcześniejszej, proszę przywrócić eksport wykonany przed aktualizacją, a potem przywrócić stary tag.

Kto za co odpowiada na Managed VPS

Samodzielny hosting wymaga prowadzenia serwera, oprócz samej aplikacji. Na Managed VPS nasze zespoły przejmują serwer i proaktywnie czuwają nad Państwa instancją; Listmonk pozostaje Państwa oprogramowaniem, z Państwa ustawieniami, listami i kampaniami.

Jeśli wolą Państwo, aby nasze zespoły interweniowały w samej aplikacji, usługa ta jest rozliczana godzinowo lub ryczałtowo, z wyceną przekazaną przed interwencją.