Emails troubleshooting

scripts/wordlist.txt

@@ -268,3 +268,5 @@ Workspaces
 workspaces
 zlib
 zoomstack
+SSL
+TLS

src/misc/licensing.md

@@ -4,7 +4,7 @@
 
 ## Mergin Maps Service
 
-* <AppDomainNameLink desc="Mergin Maps Cloud" />, SaaS <MainPlatformName /> service, has proprietary license held by Lutra Consulting Ltd.
+* <AppDomainNameLink desc="Mergin Maps Cloud" />, Cloud <MainPlatformName /> service, has proprietary license held by Lutra Consulting Ltd.
 * <MainPlatformName /> EE (Enterprise Edition), on-premise <MainPlatformName /> service, has Mergin Maps Commercial Licence held by Lutra Consulting Ltd.
 * <GitHubRepo id="MerginMaps/server" desc="Mergin Maps CE (Community Edition)" />, on-premise <MainPlatformName /> service, is dual licensed under AGPL-3.0 and Mergin Maps Commercial Licence
 

src/server/administer/environment.md

@@ -1,15 +1,15 @@
 # Configure environment
 
-There are several application settings which can be changed via <GitHubRepo desc="config variables" id="MerginMaps/server/blob/master/.prod.env" />. Some of them have defaults and some of them need to be modified, particularly those with `fixme` placeholders (marked with asterisks below).
+There are several application settings which can be changed via <GitHubRepo desc="config variables" id="MerginMaps/server/blob/master/.prod.env" />. Some of them have defaults and some of them need to be modified, particularly those with required placeholders (marked with ⭐️ below).
 ​
 #### Server basics
 Variables marked with star ⭐️ need to be modified for production use.
 
 | Variable name            | Type      | Default   | Description |
 |--------------------------|-----------|-----------|-------------|
-| `CONTACT_EMAIL`⭐️         | string    |           | Email contact for application administrator. |
+| `MERGIN_BASE_URL`⭐️       | string    |        | Deployment URL where <MainPlatformName /> is hosted. |
 | `COLLECT_STATISTICS`     | Boolean   | `true`    | Whether to send usage statistics for application improvements. |
-| `MERGIN_BASE_URL`⭐️       | string    |           | Deployment URL where <MainPlatformName /> is hosted. |
+| `CONTACT_EMAIL`         | string    |     ``      | Email contact for application administrator. |
 | `SERVICE_ID`             | string    |           | Deployment UUID. Auto-generated on the first run. |
 ​
 #### Security settings (important for production use)🛡️
@@ -62,14 +62,18 @@ To ease the process of permission (user) management, you can set the following g
 ​
 | Variable name             | Type      | Default   | Description |
 |---------------------------|-----------|-----------|-------------|
-| `MAIL_SUPPRESS_SEND`     | Boolean   | `true`    | Whether to suppress email sending. If set to `false`, you should define the following variables. |
-| `MAIL_BCC`              | string    |           | Email address to send copies of all emails sent. Should be system/application administrator.  |
-| `MAIL_DEFAULT_SENDER`   | string    |           | Sender of <MainPlatformName /> emails. Best to have some no-reply address.  |
-| `MAIL_USERNAME`         | string    |           | Connection to SMTP server.  |
-| `MAIL_PASSWORD`         | string    |           | Password for user connecting to SMTP server.  |
-| `MAIL_PORT`             | integer   | `587`     | SMTP mail server port.  |
-| `MAIL_SERVER`           | string    |`localhost`| SMTP mail server host.  |
-| `MERGIN_LOGO_URL`       | string    | `null`    | Link to logo in emails. |
+| `MAIL_SUPPRESS_SEND`     | Boolean   | `false`    | Whether to suppress email sending. If set to `false`, you should define the following variables. |
+| `MAIL_DEFAULT_SENDER`⭐️   | string    |           | Sender of <MainPlatformName /> emails. Best to have some no-reply address.  |
+| `MAIL_SERVER`⭐️           | string    |`localhost`| SMTP mail server host.  |
+| `MAIL_PORT`⭐️             | integer   | `587`     | SMTP mail server port.  |
+| `MAIL_USERNAME`         | string    |   `None`   | Username of user connecting to SMTP server.  |
+| `MAIL_PASSWORD`         | string    |   `None`        | Password for user connecting to SMTP server.  |
+| `MAIL_USE_TLS`🛡️        | Boolean    |   `true`        | Use TLS encryption when connecting to SMTP server.  |
+| `MAIL_USE_SSL`🛡️        | Boolean    |   `false`        | Whether to use SSL encryption when connecting to SMTP server.  |
+| `MAIL_BCC`              | string    |   `None`   | Email address to send copies of all emails.  sent. Should be system/application administrator. Mandatory in versions until 2024.4.0  |
+| `MERGIN_LOGO_URL`       | string    | ``    | Link to logo in emails. |
+
+If you have issues with sending emails, follow [troubleshooting](../troubleshoot/index.md) page.
 
 #### Workspace management
 Workspace settings.

src/server/administer/index.md

@@ -1,6 +1,6 @@
 # Administer
 
-Administration guide will help you to configure and maintain your <CommunityPlatformNameLink /> or <EnterprisePlatformNameLink />. The main SaaS <DashboardLink desc="Mergin Maps Server"/> is maintained for you by <MainPlatformName /> team. Read more about server platforms in the [overview article](../index.md).
+Administration guide will help you to configure and maintain your <CommunityPlatformNameLink /> or <EnterprisePlatformNameLink />. The main Cloud <DashboardLink desc="Mergin Maps Server"/> is maintained for you by <MainPlatformName /> team. Read more about server platforms in the [overview article](../index.md).
 
 [[toc]]
 

src/server/install/index.md

@@ -1,6 +1,6 @@
 # Install
 
-Installation guide will help you to install your <CommunityPlatformNameLink /> or <EnterprisePlatformNameLink /> to the latest server version. The main SaaS <DashboardLink desc="Mergin Maps Server"/> is always up-to-date and managed by <MainPlatformName /> team. Read more about server platforms in [overview article](../index.md)
+Installation guide will help you to install your <CommunityPlatformNameLink /> or <EnterprisePlatformNameLink /> to the latest server version. The main Cloud <DashboardLink desc="Mergin Maps Server"/> is always up-to-date and managed by <MainPlatformName /> team. Read more about server platforms in [overview article](../index.md)
 
 [[toc]]
 
@@ -29,6 +29,7 @@ Provided that `docker` and `docker-compose` are installed on your host, running
 Once configured, you can run:
 ```shell
 $ mkdir -p projects # or wherever you set it to be
+$ mkdir -p mergin_db # or wherever you set it to be
 $ sudo chown -R  901:999 ./projects/
 $ sudo chmod g+s ./projects/
 $ docker-compose -f docker-compose.yml up
@@ -43,4 +44,4 @@ $ docker exec merginmaps-server flask user create <username> <password> --is-adm
 
 ### Setup environment
 ​
-Now tweak deployment settings by modifying environment variables. You have to fix all variables marked as `fixme` (with asterisks) in this list of [environment variables](../administer/environment.md).
+Now tweak deployment settings by modifying environment variables. You have to fix all variables marked as required in this list of [environment variables](../administer/environment.md). In [troubleshoot](../troubleshoot/index.md) section are listed some of the most common issues with custom deployments.

src/server/troubleshoot/index.md

@@ -1,6 +1,8 @@
 # Troubleshoot Custom Servers
 
-This article will help you debug and resolve issues in your <CommunityPlatformNameLink /> or <EnterprisePlatformNameLink /> deployment. If you use the main SaaS <DashboardLink desc="Mergin Maps Server"/>, it is always up-to-date and managed by <MainPlatformName /> team, so report your problems to us as [described here](../../misc/troubleshoot/index.md). Read more about server platforms in [overview article](../index.md).
+This article will help you debug and resolve issues in your <CommunityPlatformNameLink /> or <EnterprisePlatformNameLink /> deployment. If you use the main Cloud <DashboardLink desc="Mergin Maps Server"/>, it is always up-to-date and managed by <MainPlatformName /> team, so report your problems to us as [described here](../../misc/troubleshoot/index.md). Read more about server platforms in [overview article](../index.md). 
+
+To install your own server, follow our [installation guide](../install/index.md). Documentation of environment variables and other configuration options can be found in [Configure environment](../administer/environment.md).
 
 [[toc]]
 
@@ -17,3 +19,26 @@ Did you get an error that the server is not properly configured?
 
 2. Restart the container with the `MERGIN_BASE_URL` variable
 
+## Emails are not sent
+
+If you are not receiving emails, check that the following [environment variables](../administer/environment/) are set correctly:
+
+* `MAIL_DEFAULT_SENDER` needs to be a valid email address
+* `MAIL_SERVER` should be a valid URL to SMTP server
+* `MAIL_PORT` SMTP mail server port is set to `587` by default. Change it to the correct value, if you use a different port.
+* `MAIL_SUPPRESS_SEND` should be set to `false`
+
+In some deployments, there may be SMTP servers that do not support authentication and TLS. In that case, you can disable authentication by not defining variables `MAIL_USERNAME` and `MAIL_PASSWORD` (which are set to `None` by default). 
+
+If your SMTP server does not support TLS or SSL, you can disable encryption by setting `MAIL_USE_TLS` and `MAIL_USE_SSL` to `false`. However, it is recommended to use authentication and TLS encryption.
+
+Server is sending emails with a celery worker. If you are not receiving emails, check if celery worker is running. Check logs for sending emails in the `celery-worker` container:
+```shell
+$ docker logs celery-worker
+```
+
+Logs should contain information about sending emails with task `mergin.celery.send_email_async` with success status:
+
+```shell
+[2024-12-09 10:37:16,265: INFO/ForkPoolWorker-2] Task mergin.celery.send_email_async[3e50df69-90c1-49be-b31c-78f1fb417500] succeeded in 0.11469305199989321s: None
+```