From 7db3c2bac28fdc2b19670ef8db3422e0a49cb216 Mon Sep 17 00:00:00 2001 From: Ilya Gulya Date: Sat, 28 Dec 2024 21:33:19 +0500 Subject: [PATCH] ses: fix README --- .gitignore | 3 +- README.md | 133 +++++++++++++++++++++++++++++++++++++---------------- 2 files changed, 95 insertions(+), 41 deletions(-) diff --git a/.gitignore b/.gitignore index 34c6225..8fb5138 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,5 @@ traefik/docker-compose.yaml nginx.conf nginx.conf.bak huly.conf -.huly.secret \ No newline at end of file +.huly.secret +.idea diff --git a/README.md b/README.md index 280025c..31f4652 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,18 @@ # Huly Self-Hosted -Please use this README if you want to deploy Huly on your server with `docker compose`. I'm using a Basic Droplet on Digital Ocean with Ubuntu 23.10, but these instructions can be easily adapted for any Linux distribution. +Please use this README if you want to deploy Huly on your server with `docker compose`. I'm using a Basic Droplet on +Digital Ocean with Ubuntu 23.10, but these instructions can be easily adapted for any Linux distribution. > [!NOTE] -> Huly is quite resource-heavy, so I recommend using a Droplet with 2 vCPUs and 4GB of RAM. Droplets with less RAM may stop responding or fail. +> Huly is quite resource-heavy, so I recommend using a Droplet with 2 vCPUs and 4GB of RAM. Droplets with less RAM may +> stop responding or fail. If you prefer Kubernetes deployment, there is a sample Kubernetes configuration under [kube](kube) directory. ## Installing `nginx` and `docker` -First, let's install `nginx` and `docker` using the commands below if you have not already installed them on your machine. +First, let's install `nginx` and `docker` using the commands below if you have not already installed them on your +machine. ```bash sudo apt update @@ -26,18 +29,23 @@ git clone https://github.com/hcengineering/huly-selfhost.git cd huly-selfhost ./setup.sh ``` + This will generate a [huly.conf](./huly.conf) file with your chosen values and create your nginx config. To add the generated configuration to your Nginx setup, run the following: + ```bash sudo ln -s $(pwd)/nginx.conf /etc/nginx/sites-enabled/huly.conf ``` + > [!NOTE] -> If you change `HOST_ADDRESS`, `SECURE`, `HTTP_PORT` or `HTTP_BIND` be sure to update your [nginx.conf](./nginx.conf) by running: +> If you change `HOST_ADDRESS`, `SECURE`, `HTTP_PORT` or `HTTP_BIND` be sure to update your [nginx.conf](./nginx.conf) +> by running: > ```bash > ./nginx.sh > ``` ->You can safely execute this script after adding your custom configurations like ssl. It will only overwrite the necessary settings. +>You can safely execute this script after adding your custom configurations like ssl. It will only overwrite the +> necessary settings. Finally, let's reload `nginx` and start Huly with `docker compose`. @@ -51,18 +59,25 @@ Now, launch your web browser and enjoy Huly! ## Generating Public and Private VAPID keys for front-end You'll need `Node.js` installed on your machine. Installing `npm` on Debian based distro: + ``` sudo apt-get install npm ``` + Install web-push using npm + ``` sudo npm install -g web-push ``` + Generate VAPID Keys. Run the following command to generate a VAPID key pair: + ``` web-push generate-vapid-keys ``` + It will generate both keys that looks like this: + ``` ======================================= @@ -74,9 +89,11 @@ asdfsadfasdfsfd ======================================= ``` + Keep these keys secure, as you will need them to set up your push notification service on the server. Add these keys into `compose.yaml` in section `services:front:environment`: + ``` - PUSH_PUBLIC_KEY=your public key - PUSH_PRIVATE_KEY=your private key @@ -86,14 +103,35 @@ Add these keys into `compose.yaml` in section `services:front:environment`: 1. Setup Amazon Simple Email Service in AWS: https://docs.aws.amazon.com/ses/latest/dg/setting-up.html -2. Add email address you'll use to send notifications into "SOURCE", SES access such as ACCESS_KEY, SECRET_KEY, REGION +2. [Create new policy](https://us-east-1.console.aws.amazon.com/iam/home?region=eu-central-1#/policies/create) with + following permissions: + ``` + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "ses:SendEmail", + "ses:SendRawEmail" + ], + "Resource": "*" + } + ] + } + ``` + +3. [Create separate IAM user](https://us-east-1.console.aws.amazon.com/iam/home?region=eu-central-1#/users/create) for + SES API access. Assign previously created policy to this user during creation. + +4. Add email address you'll use to send notifications into "SOURCE", SES access such as ACCESS_KEY, SECRET_KEY, REGION ```yaml ses: - image: hardcoreeng/ses:v0.6.295 + image: hardcoreeng/ses:v0.6.377 container_name: ses - ports: - - 3335:3335 + expose: + - 3335 environment: - SOURCE= - ACCESS_KEY= @@ -103,33 +141,35 @@ Add these keys into `compose.yaml` in section `services:front:environment`: restart: unless-stopped ``` -3. Add SES container URL into `transactor` and `account` containers: +5. Add SES container URL into `transactor` and `account` containers: ```yaml account: - ... + # ... environment: - SES_URL=http://ses:3335 - ... + # ... transactor: - ... + # ... environment: - SES_URL=http://ses:3335 - ... + # ... ``` -4. In `Settings -> Notifications` setup email notifications for events you need to be notified for. It's a user's setting not a company wide, meaning each user has to setup their own notification rules. +6. In `Settings -> Notifications` setup email notifications for events you need to be notified for. It's a user's + setting not a company wide, meaning each user has to setup their own notification rules. ## Love Service (Audio & Video calls) -Huly audio and video calls are created on top of LiveKit insfrastructure. In order to use Love service in your self-hosted Huly, perform the following steps: +Huly audio and video calls are created on top of LiveKit insfrastructure. In order to use Love service in your +self-hosted Huly, perform the following steps: 1. Set up [LiveKit Cloud](https://cloud.livekit.io) account 2. Add `love` container to the docker-compose.yaml ```yaml love: - image: hardcoreeng/love:v0.6.295 + image: hardcoreeng/love:v0.6.377 container_name: love ports: - 8096:8096 @@ -151,11 +191,11 @@ Huly audio and video calls are created on top of LiveKit insfrastructure. In ord ```yaml front: - ... + # ... environment: - LIVEKIT_WS= - LOVE_ENDPOINT=http://love:8096 - ... + # ... ``` ## Configure OpenID Connect (OIDC) @@ -163,15 +203,19 @@ Huly audio and video calls are created on top of LiveKit insfrastructure. In ord You can configure a Huly instance to authorize users (sign-in/sign-up) using an OpenID Connect identity provider (IdP). ### On the IdP side -1. Create a new OpenID application. - * Use `{huly_account_svc}/auth/openid/callback` as the sign-in redirect URI. The `huly_account_svc` is the hostname for the account service of the deployment, which should be accessible externally from the client/browser side. In the provided example setup, the account service runs on port 3000. - **URI Example:** - - `http://huly.mydomain.com:3000/auth/openid/callback` +1. Create a new OpenID application. + * Use `{huly_account_svc}/auth/openid/callback` as the sign-in redirect URI. The `huly_account_svc` is the hostname + for the account service of the deployment, which should be accessible externally from the client/browser side. In + the provided example setup, the account service runs on port 3000. + + **URI Example:** + - `http://huly.mydomain.com:3000/auth/openid/callback` -2. Configure user access to the application as needed. +2. Configure user access to the application as needed. ### On the Huly side + For the account service, set the following environment variables as provided by the IdP: * OPENID_CLIENT_ID @@ -184,52 +228,61 @@ Ensure you have configured or add the following environment variable to the fron You will need to expose your account service port (e.g. 3000) in your nginx.conf. -Note: Once all the required environment variables are configured, you will see an additional button on the sign-in/sign-up pages. +Note: Once all the required environment variables are configured, you will see an additional button on the +sign-in/sign-up pages. ## Configure GitHub OAuth You can also configure a Huly instance to use GitHub OAuth for user authorization (sign-in/sign-up). ### On the GitHub side -1. Create a new GitHub OAuth application. - * Use `{huly_account_svc}/auth/github/callback` as the sign-in redirect URI. The `huly_account_svc` is the hostname for the account service of the deployment, which should be accessible externally from the client/browser side. In the provided example setup, the account service runs on port 3000. - **URI Example:** - - `http://huly.mydomain.com:3000/auth/github/callback` +1. Create a new GitHub OAuth application. + * Use `{huly_account_svc}/auth/github/callback` as the sign-in redirect URI. The `huly_account_svc` is the hostname + for the account service of the deployment, which should be accessible externally from the client/browser side. In + the provided example setup, the account service runs on port 3000. + + **URI Example:** + - `http://huly.mydomain.com:3000/auth/github/callback` ### On the Huly side + Specify the following environment variables for the account service: -* `GITHUB_CLIENT_ID` -* `GITHUB_CLIENT_SECRET` +* `GITHUB_CLIENT_ID` +* `GITHUB_CLIENT_SECRET` Ensure you have configured or add the following environment variable to the front service: -* `ACCOUNTS_URL` (The URL of the account service, accessible from the client side.) +* `ACCOUNTS_URL` (The URL of the account service, accessible from the client side.) You will need to expose your account service port (e.g. 3000) in your nginx.conf. Notes: + * The `ISSUER` environment variable is not required for GitHub OAuth. -* Once all the required environment variables are configured, you will see an additional button on the sign-in/sign-up pages. +* Once all the required environment variables are configured, you will see an additional button on the sign-in/sign-up + pages. ## Disable Sign-Up -You can disable public sign-ups for a deployment. When configured, sign-ups will only be permitted through an invite link to a specific workspace. +You can disable public sign-ups for a deployment. When configured, sign-ups will only be permitted through an invite +link to a specific workspace. To implement this, set the following environment variable for both the front and account services: ```yaml account: - ... + # ... environment: - DISABLE_SIGNUP=true - ... - front: - ... + # ... + front: + # ... environment: - DISABLE_SIGNUP=true - ... + # ... ``` -_Note: When setting up a new deployment, either create the initial account before disabling sign-ups or use the development tool to create the first account._ +_Note: When setting up a new deployment, either create the initial account before disabling sign-ups or use the +development tool to create the first account._