Emails troubleshooting

scripts/wordlist.txt

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

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 asterisks 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/install/index.md

@@ -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 (with asterisks) 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,6 @@
 # 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 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). Follow [installation guide](../install/index.md) to install your own server. Documentation to environment variables and other configuration options can be found in [configure](../administer/environment.md) section.
 
 [[toc]]
 
@@ -17,3 +17,25 @@ 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
+
+Mergin Maps server is sending emails to users in following cases:
+
+* Email verification
+* Password reset
+* Incoming access request
+* Invitation to workspace (only for <EnterprisePlatformName />)
+
+Definition of variables   If you are not receiving emails, check that the following environment variables are set correctly:
+
+* `MAIL_DEFAULT_SENDER` is mandatory and should be a valid email address
+* `MAIL_SERVER` should be a valid url to SMTP server
+* `MAIL_PORT` if you have different port than 587, configure it with this variable
+* `MAIL_SUPPRESS_SEND` check if you set it to `False`
+
+In some deployments are SMTP servers that are not supporting authentication and TLS. In this case, you can disable authentication by not defining variable `MAIL_USERNAME` and `MAIL_PASSWORD` (which are by default `None`). 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`. It's recommended to use authentication and TLS encryption.
+
+Server is sending emails with celery worker. If you are not receiving emails, check if celery worker is running. You can check logs for sending emails in `celery-worker` container:
+```shell
+$ docker logs celery-worker
+```