From f8e6eaa2d915b30d92acad423d25914f43650fe3 Mon Sep 17 00:00:00 2001 From: Kailash Nadh Date: Tue, 30 Jul 2024 00:07:48 +0530 Subject: [PATCH] Add docs for v4.x.x multi-user upgrade changes. --- docs/docs/content/configuration.md | 6 ++---- docs/docs/content/installation.md | 11 ++++++----- docs/docs/content/upgrade.md | 11 +++++++++++ 3 files changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/docs/content/configuration.md b/docs/docs/content/configuration.md index 6944a658..11e7244f 100644 --- a/docs/docs/content/configuration.md +++ b/docs/docs/content/configuration.md @@ -13,8 +13,6 @@ Example: | **Environment variable** | Example value | | ------------------------------ | -------------- | | `LISTMONK_app__address` | "0.0.0.0:9000" | -| `LISTMONK_app__admin_username` | listmonk | -| `LISTMONK_app__admin_password` | listmonk | | `LISTMONK_db__host` | db | | `LISTMONK_db__port` | 9432 | | `LISTMONK_db__user` | listmonk | @@ -141,8 +139,8 @@ with any Timezone listed [here](https://en.wikipedia.org/wiki/List_of_tz_databas ### Retries The `Settings -> SMTP -> Retries` denotes the number of times a message that fails at the moment of sending is retried silently using different connections from the SMTP pool. The messages that fail even after retries are the ones that are logged as errors and ignored. -### Blocked Ports -Some server hosts block SMTP ports (25, 465) so you have to get request to unblock them i.e. [Hetzner](https://docs.hetzner.com/cloud/servers/faq/#why-can-i-not-send-any-mails-from-my-server). +## SMTP ports +Some server hosts block outgoing SMTP ports (25, 465). You may have to contact your host to unblock them before being able to send e-mails. Eg: [Hetzner](https://docs.hetzner.com/cloud/servers/faq/#why-can-i-not-send-any-mails-from-my-server). ## Performance diff --git a/docs/docs/content/installation.md b/docs/docs/content/installation.md index e1c9571e..3d545c44 100644 --- a/docs/docs/content/installation.md +++ b/docs/docs/content/installation.md @@ -3,13 +3,14 @@ listmonk requires Postgres ⩾ 12 !!! Admin - Set environment variables `LISTMONK_ADMIN_USER` and `LISTMONK_ADMIN_PASSWORD` when installing listmonk to create the Super Admin user. If these are not set, listmonk generates a username and temporary password which are printed on the terminal output. + listmonk generates and prints admin credentials to the terminal during installation. This can be copied to login to the admin dashboard and later changed. To choose a custom username and password during installation, + set the environment variables `LISTMONK_ADMIN_USER` and `LISTMONK_ADMIN_PASSWORD` during installation. ## Binary -- Download the [latest release](https://github.com/knadh/listmonk/releases) and extract the listmonk binary. `amd64` is the main one. It works for Intel and x86 CPUs. -- `./listmonk --new-config` to generate config.toml. Then, edit the file. -- `./listmonk --install` to install the tables in the Postgres DB. Copy the username and password from the terminal output. -- Run `./listmonk` and visit `http://localhost:9000`. +1. Download the [latest release](https://github.com/knadh/listmonk/releases) and extract the listmonk binary. `amd64` is the main one. It works for Intel and x86 CPUs. +1. `./listmonk --new-config` to generate config.toml. Edit the file. +1. `./listmonk --install` to install the tables in the Postgres DB. Copy the admin username and password from the terminal output (these can be changed from the admin UI later). To choose a custom username and password during installation, run: `LISTMONK_ADMIN_USER=myuser LISTMONK_ADMIN_PASSWORD=xxxxx ./listmonk --install` +1. Run `./listmonk` and visit `http://localhost:9000`. ## Docker diff --git a/docs/docs/content/upgrade.md b/docs/docs/content/upgrade.md index 2c8371ce..8c7ff096 100644 --- a/docs/docs/content/upgrade.md +++ b/docs/docs/content/upgrade.md @@ -58,3 +58,14 @@ x-app-defaults: &app-defaults 4. Restart: `sudo docker compose up -d app db nginx certbot` + +## Upgrading to v4.x.x +v4 is a major upgrade from prior versions with significant changes to certain important features and behaviour. It is the first version to have multi-user support and full fledged user management. Prior versions only had a simple BasicAuth for both admin login (browser prompt) and API calls, with the username and password defined in the TOML configuration file. + +It is safe to upgrade an older installation with `--upgrade`, but there are a few important things to keep in mind. The upgrade automatically imports the `admin_username` and `admin_password` defined in the TOML configuration into the new user management system. + +1. **New login UI**: Once you upgrade an older installation, the admin dashboard will no longer show the native browser prompt for login. Instead, a new login UI rendered by listmonk is displayed at the URI `/admin/login`. + +1. **API credentials**: If you are using APIs to interact with listmonk, after logging in, go to Settings -> Users and create a new API user with the necessary permissions. Change existing API integrations to use these credentials instead of the old username and password defined in the legacy TOML configuration file or environment variables. + +1. **Credentials in TOML file or old environment variables**: The admin dashboard shows a warning until the `admin_username` and `admin_password` fields are removed from the configuration file or old environment variables. In v4.x.x, these are irrelevant as user credentials are stored in the database and managed from the admin UI. IMPORTANT: if you are using APIs to interact with listmonk, follow the previous step before removing the legacy credentials.