knadh/listmonk
1
1
Fork 0
mirror of https://github.com/knadh/listmonk.git synced 2024-11-13 02:55:04 +08:00
Code Issues Projects Releases Packages Wiki Activity

Add docs for v4.x.x multi-user upgrade changes.

Browse source
This commit is contained in:
Kailash Nadh 2024-07-30 00:07:48 +05:30
parent 26c6db0a13
commit f8e6eaa2d9
3 changed files with 19 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/docs/content/configuration.md
View file

@ -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

11
docs/docs/content/installation.md
View file

@ -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

11
docs/docs/content/upgrade.md
View file

@ -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.