From b2d804b9ba3e0bdf7b1380f7f7895276af2c7478 Mon Sep 17 00:00:00 2001 From: luwol03 Date: Fri, 11 Feb 2022 14:34:24 +0100 Subject: [PATCH 1/4] added new email config options to server/configuration --- docs/vocascan-server/configuration.md | 37 ++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/docs/vocascan-server/configuration.md b/docs/vocascan-server/configuration.md index ad529b3..7755c23 100644 --- a/docs/vocascan-server/configuration.md +++ b/docs/vocascan-server/configuration.md @@ -43,13 +43,13 @@ There are 2 ways to configure a vocascan-server. ## Server (`server`) -| Name | Default | Description | -| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `port` | `5000` | Defines the port on which the server is listening. | -| `jwt_secret` | | Secret is used to sign the payload of the jwt token, change this to a unique string. Everyone who knows that secret is able to act as other vocascan users. | -| `salt_rounds` | `10` | The salt rounds define the coast efficiency factor to hash passwords with bcrypt. For more info, see [bcrypts documentation](https://github.com/kelektiv/node.bcrypt.js#a-note-on-rounds). | -| `registration_locked` | `false` | Locks the server and only allows registrations with an invite code. | -| `cors` | `false` | This can be either a boolean (`true`/`false`), a string with a single domain (`http://localhost:3000`) or a asterisk (`*`) to allow all domains, or a array (`["http://localhost:3000", "http://localhost:4000"]`). | +| Name | Default | Description | +| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `base_url` | | Base url of the API server. Used for links in emails. (E.g. `http://example.com`) | +| `port` | `5000` | Defines the port on which the server is listening. | +| `jwt_secret` | | Secret is used to sign the payload of the jwt token, change this to a unique string. Everyone who knows that secret is able to act as other vocascan users. | +| `salt_rounds` | `10` | The salt rounds define the coast efficiency factor to hash passwords with bcrypt. For more info, see [bcrypts documentation](https://github.com/kelektiv/node.bcrypt.js#a-note-on-rounds). | +| `cors` | `false` | This can be either a boolean (`true`/`false`), a string with a single domain (`http://localhost:3000`) or a asterisk (`*`) to allow all domains, or a array (`["http://localhost:3000", "http://localhost:4000"]`). | ## Database (`database`) @@ -124,3 +124,26 @@ For more information about the logger section see [logging guide](vocascan-serve | Name | Default | Description | | ---------------- | ------- | --------------------------------------------- | | `enable_swagger` | `true` | Enables serving of the swagger documentation. | + +## Mailer (`mailer`) + +| Name | Default | Description | +| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `enabled` | `false` | Enable/Disable mailer. | +| `host` | | Email server host. | +| `port` | | Email server port. | +| `secure` | `false` | If `true` the connection will use TLS when connecting to server, otherwise TLS is used if server supports the `STARTTLS` extension. In most cases set this value to `true` if you are connecting to port 465. For port 587 or 25 keep it `false`. | +| `auth.user` | | Email server user. | +| `auth.pass` | | Email server password. | +| `from` | `false` | The email address of vocascan should use a the sender. | + +## Service (`service`) + +| Name | Default | Description | +| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `invite_code` | `false` | Locks the server and only allows registrations with an invite code. | +| `email_confirm` | `false` | Enables email confirmation. | +| `email_confirm_live_time` | `2h` | Defines the time how long the link in the email is valid. This option is parsed with [ms](https://github.com/vercel/ms) (E.g. `2d`, `2.5h`, `30d`, ...) | +| `email_confirm_level` | `medium` | Define what a user can do if the account is not verified. `low` - no restrictions, `medium` - user can use vocascan for a specific time set by `service.email_confirm_time`, `high` - user cannot do anything except logging in. | +| `email_confirm_time` | `14d` | Defines the time a user can use vocascan without restrictions without verification. (Takes only effect, if `service.email_confirm_level` is `medium`) This option is parsed with [ms](https://github.com/vercel/ms) (E.g. `2d`, `2.5h`, `30d`, ...) | +| `access_live_time` | `30d` | Defines the time how long a jwt access token is valid. This option is parsed with [ms](https://github.com/vercel/ms) (E.g. `2d`, `2.5h`, `30d`, ...) | From 783206654ac9b8c77b416c21af803ae08e9faa5e Mon Sep 17 00:00:00 2001 From: luwol03 Date: Thu, 14 Apr 2022 16:34:09 +0200 Subject: [PATCH 2/4] Added emailSetup page --- docs/_sidebar.md | 1 + docs/vocascan-server/emailSetup.md | 60 ++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 docs/vocascan-server/emailSetup.md diff --git a/docs/_sidebar.md b/docs/_sidebar.md index d4b64c1..c7125d2 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -37,6 +37,7 @@ - [Logging](vocascan-server/logging.md) - [Command Line Interface](vocascan-server/cli.md) - [Custom Pages](vocascan-server/customPages.md) + - [Email Setup](vocascan-server/emailSetup.md) - [Contribute](vocascan-server/contribute.md) - [Changelog](vocascan-server/changelog.md) diff --git a/docs/vocascan-server/emailSetup.md b/docs/vocascan-server/emailSetup.md new file mode 100644 index 0000000..68c2604 --- /dev/null +++ b/docs/vocascan-server/emailSetup.md @@ -0,0 +1,60 @@ +# Email Setup + +## Using generic SMTP + +You can directly use the SMTP server from an external email provider like shown below. + +```js + mailer: { + enabled: true, + host: 'smtp.example.com', + port: 587, + auth: { + user: 'vocascan@example.com', + pass: 'password', + }, + from: '"Vocascan" ', + }, + service: { + email_confirm: true, + }, +``` + +## Developing with Email + +If you want to contribute and change something related to the email feature, you can either use Ethereal mail or an self +hosted version like MailCatcher. + +### Ethereal + +> [Ethereal](https://ethereal.email/) is a fake SMTP service, mostly aimed at Nodemailer users (but not limited to). +> It's a completely free anti-transactional email service where messages never get delivered. + +1. Go to https://ethereal.email/ +2. Create an free account without any registration +3. Copy the credentials to your vocascan configuration +4. Go to messages on their top bar navigation + +### MailCatcher + +> [MailCatcher](https://mailcatcher.me/) runs a super simple SMTP server which catches any message sent to it to display +> in a web interface. Run mailcatcher, set your favourite app to deliver to smtp://127.0.0.1:1025 instead of your +> default SMTP server, then check out http://127.0.0.1:1080 to see the mail that's arrived so far. + +1. Start MailCatcher inside of a docker container + + ```yml + version: "3" + + services: + ... + mailer: + image: sj26/mailcatcher:latest + restart: always + ports: + - "1080:1080" + - "1025:1025" + ``` + +2. Adjust your vocascan email configuration to use your local pc on port 1025 as email provider. +3. Open `http://localhost:1080` From 472043ba669af2a31358fdae32220977bb48d1a9 Mon Sep 17 00:00:00 2001 From: luwol03 Date: Thu, 14 Apr 2022 16:57:08 +0200 Subject: [PATCH 3/4] improved language --- docs/vocascan-server/emailSetup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/vocascan-server/emailSetup.md b/docs/vocascan-server/emailSetup.md index 68c2604..ce42d8b 100644 --- a/docs/vocascan-server/emailSetup.md +++ b/docs/vocascan-server/emailSetup.md @@ -41,7 +41,7 @@ hosted version like MailCatcher. > in a web interface. Run mailcatcher, set your favourite app to deliver to smtp://127.0.0.1:1025 instead of your > default SMTP server, then check out http://127.0.0.1:1080 to see the mail that's arrived so far. -1. Start MailCatcher inside of a docker container +1. Start MailCatcher inside a docker container ```yml version: "3" From 1d2898f2b5a038099d0eefb4b70ef8ce126e780d Mon Sep 17 00:00:00 2001 From: luwol03 Date: Sun, 17 Apr 2022 12:27:36 +0200 Subject: [PATCH 4/4] Added info box that the base_url should be set --- docs/vocascan-server/emailSetup.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/vocascan-server/emailSetup.md b/docs/vocascan-server/emailSetup.md index ce42d8b..0bba458 100644 --- a/docs/vocascan-server/emailSetup.md +++ b/docs/vocascan-server/emailSetup.md @@ -5,6 +5,9 @@ You can directly use the SMTP server from an external email provider like shown below. ```js + server: { + base_url: "http://localhost:5000" + }, mailer: { enabled: true, host: 'smtp.example.com', @@ -20,6 +23,9 @@ You can directly use the SMTP server from an external email provider like shown }, ``` +!> Please make sure, that `server.base_url` is set correctly, otherwise the verification links in the email are not +correct. + ## Developing with Email If you want to contribute and change something related to the email feature, you can either use Ethereal mail or an self