{"id":13456980,"url":"https://github.com/hcengineering/huly-selfhost","last_synced_at":"2025-05-14T05:10:49.667Z","repository":{"id":227269666,"uuid":"770936497","full_name":"hcengineering/huly-selfhost","owner":"hcengineering","description":"Huly for Self Hosting","archived":false,"fork":false,"pushed_at":"2025-05-05T15:59:56.000Z","size":165,"stargazers_count":2280,"open_issues_count":68,"forks_count":202,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-05-08T02:51:25.756Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hcengineering.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-12T12:17:47.000Z","updated_at":"2025-05-07T21:36:37.000Z","dependencies_parsed_at":"2024-03-12T13:53:20.571Z","dependency_job_id":"eee0606f-c13d-4697-a556-37edf93eff0c","html_url":"https://github.com/hcengineering/huly-selfhost","commit_stats":null,"previous_names":["hcengineering/huly-selfhost"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcengineering%2Fhuly-selfhost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcengineering%2Fhuly-selfhost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcengineering%2Fhuly-selfhost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hcengineering%2Fhuly-selfhost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hcengineering","download_url":"https://codeload.github.com/hcengineering/huly-selfhost/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076850,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T08:01:31.249Z","updated_at":"2025-05-14T05:10:49.645Z","avatar_url":"https://github.com/hcengineering.png","language":"Shell","funding_links":[],"categories":["Shell","others"],"sub_categories":[],"readme":"# Huly Self-Hosted\n\nPlease 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 24.04, but these instructions can be easily adapted for any Linux distribution.\n\n\u003e [!NOTE]\n\u003e Huly is quite resource-heavy, so I recommend using a Droplet with 2 vCPUs and 4GB of RAM. Droplets with less RAM may\n\u003e stop responding or fail.\n\nIf you prefer Kubernetes deployment, there is a sample Kubernetes configuration under [kube](kube) directory.\n\n## Installing `nginx` and `docker`\n\nFirst, update repositories cache:\n\n```bash\nsudo apt update\n```\n\nNow, install `nginx`:\n\n```bash\nsudo apt install nginx\n```\n\nInstall docker using the [recommended method](https://docs.docker.com/engine/install/ubuntu/) from docker website.\nAfterwards perform [post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/). Pay attention to 3rd step with `newgrp docker` command, it needed for correct execution in setup script.\n\n## Clone the `huly-selfhost` repository and configure `nginx`\n\nNext, let's clone the `huly-selfhost` repository and configure Huly.\n\n```bash\ngit clone https://github.com/hcengineering/huly-selfhost.git\ncd huly-selfhost\n./setup.sh\n```\n\nThis will generate a [huly.conf](./huly.conf) file with your chosen values and create your nginx config.\n\nTo add the generated configuration to your Nginx setup, run the following:\n\n```bash\nsudo ln -s $(pwd)/nginx.conf /etc/nginx/sites-enabled/huly.conf\n```\n\n\u003e [!NOTE]\n\u003e If you change `HOST_ADDRESS`, `SECURE`, `HTTP_PORT` or `HTTP_BIND` be sure to update your [nginx.conf](./nginx.conf)\n\u003e by running:\n\u003e ```bash\n\u003e ./nginx.sh\n\u003e ```\n\u003eYou can safely execute this script after adding your custom configurations like ssl. It will only overwrite the\n\u003e necessary settings.\n\nFinally, let's reload `nginx` and start Huly with `docker compose`.\n\n```bash\nsudo nginx -s reload\nsudo docker compose up -d\n```\n\nNow, launch your web browser and enjoy Huly!\n\n## Generating Public and Private VAPID keys for front-end\n\nYou'll need `Node.js` installed on your machine. Installing `npm` on Debian based distro:\n\n```\nsudo apt-get install npm\n```\n\nInstall web-push using npm\n\n```bash\nsudo npm install -g web-push\n```\n\nGenerate VAPID Keys. Run the following command to generate a VAPID key pair:\n\n```\nweb-push generate-vapid-keys\n```\n\nIt will generate both keys that looks like this:\n\n```bash\n=======================================\n\nPublic Key:\nsdfgsdgsdfgsdfggsdf\n\nPrivate Key:\nasdfsadfasdfsfd\n\n=======================================\n```\n\nKeep these keys secure, as you will need them to set up your push notification service on the server.\n\nAdd these keys into `compose.yaml` in section `services:ses:environment`:\n\n```yaml\n- PUSH_PUBLIC_KEY=your public key\n- PUSH_PRIVATE_KEY=your private key\n```\n\n## Mail Service\n\nThe Mail Service is responsible for sending email notifications and confirmation emails during user login or signup processes. It can be configured to send emails through either an SMTP server or Amazon SES (Simple Email Service), but not both at the same time.\n\n### General Configuration\n\n1. Add the `mail` container to the `docker-compose.yaml` file. Specify the email address you will use to send emails as \"SOURCE\":\n\n    ```yaml\n    mail:\n      image: hardcoreeng/mail:v0.6.499\n      container_name: mail\n      ports:\n        - 8097:8097\n      environment:\n        - PORT=8097\n        - SOURCE=\u003cEMAIL_FROM\u003e\n      restart: unless-stopped\n    ```\n\n2. Add the mail container URL to the `transactor` and `account` containers:\n\n    ```yaml\n    account:\n      ...\n      environment:\n        - MAIL_URL=http://mail:8097\n      ...\n    transactor:\n      ...\n      environment:\n        - MAIL_URL=http://mail:8097\n      ...\n    ```\n\n3. In `Settings -\u003e Notifications`, set up email notifications for the events you want to be notified about. Note that this is a user-specific setting, not company-wide; each user must set up their own notification preferences.\n\n### SMTP Configuration\n\nTo integrate with an external SMTP server, update the `docker-compose.yaml` file with the following environment variables:\n\n1. Add SMTP configuration to the environment section:\n\n    ```yaml\n    mail:\n      ...\n      environment:\n        ...\n        - SMTP_HOST=\u003cSMTP_SERVER_URL\u003e\n        - SMTP_PORT=\u003cSMTP_SERVER_PORT\u003e\n        - SMTP_USERNAME=\u003cSMTP_USER\u003e\n        - SMTP_PASSWORD=\u003cSMTP_PASSWORD\u003e\n    ```\n\n2. Replace `\u003cSMTP_SERVER_URL\u003e` and `\u003cSMTP_SERVER_PORT\u003e` with your SMTP server's hostname and port. It's recommended to use a secure port, such as `587`.\n\n3. Replace `\u003cSMTP_USER\u003e` and `\u003cSMTP_PASSWORD\u003e` with credentials for an account that can send emails via your SMTP server. If your service provider supports it, consider using an application API key as `\u003cSMTP_USER\u003e` and a token as `\u003cSMTP_PASSWORD\u003e` for enhanced security.\n\n### Amazon SES Configuration\n\n1. Set up Amazon Simple Email Service in AWS: [AWS SES Setup Guide](https://docs.aws.amazon.com/ses/latest/dg/setting-up.html)\n\n2. Create a new IAM policy with the following permissions:\n\n    ```json\n    {\n      \"Version\": \"2012-10-17\",\n      \"Statement\": [\n        {\n          \"Effect\": \"Allow\",\n          \"Action\": [\n            \"ses:SendEmail\",\n            \"ses:SendRawEmail\"\n          ],\n          \"Resource\": \"*\"\n        }\n      ]\n    }\n    ```\n\n3. Create a separate IAM user for SES API access, assigning the newly created policy to this user.\n\n4. Configure SES environment variables in the `mail` container:\n\n    ```yaml\n    mail:\n      ...\n      environment:\n        ...\n        - SES_ACCESS_KEY=\u003cSES_ACCESS_KEY\u003e\n        - SES_SECRET_KEY=\u003cSES_SECRET_KEY\u003e\n        - SES_REGION=\u003cSES_REGION\u003e\n    ```\n\n### Notes\n\n1. SMTP and SES configurations cannot be used simultaneously.\n2. `SES_URL` is not supported in version v0.6.470 and later, please use `MAIL_URL` instead.\n\n\n## Love Service (Audio \u0026 Video calls)\n\nHuly audio and video calls are created on top of LiveKit insfrastructure. In order to use Love service in your\nself-hosted Huly, perform the following steps:\n\n1. Set up [LiveKit Cloud](https://cloud.livekit.io) account\n2. Add `love` container to the docker-compose.yaml\n\n    ```yaml\n      love:\n        image: hardcoreeng/love:v0.6.499\n        container_name: love\n        ports:\n          - 8096:8096\n        environment:\n          - STORAGE_CONFIG=minio|minio?accessKey=minioadmin\u0026secretKey=minioadmin\n          - SECRET=secret\n          - ACCOUNTS_URL=http://account:3000\n          - DB_URL=mongodb://mongodb:27017\n          - MONGO_URL=mongodb://mongodb:27017\n          - STORAGE_PROVIDER_NAME=minio\n          - PORT=8096\n          - LIVEKIT_HOST=\u003cLIVEKIT_HOST\u003e\n          - LIVEKIT_API_KEY=\u003cLIVEKIT_API_KEY\u003e\n          - LIVEKIT_API_SECRET=\u003cLIVEKIT_API_SECRET\u003e\n        restart: unless-stopped\n    ```\n\n3. Configure `front` service:\n\n    ```yaml\n      front:\n        ...\n        environment:\n          - LIVEKIT_WS=\u003cLIVEKIT_HOST\u003e\n          - LOVE_ENDPOINT=http://love:8096\n        ...\n    ```\n\n## AI Service\n\nHuly provides AI-powered chatbot that provides several services:\n\n- chat with AI\n- text message translations in the chat\n- live translations for virtual office voice and video chats\n\n1. Set up OpenAI account\n2. Add `aibot` container to the docker-compose.yaml\n\n    ```yaml\n      aibot:\n        image: hardcoreeng/ai-bot:v0.6.499\n        ports:\n          - 4010:4010\n        environment:\n          - STORAGE_CONFIG=minio|minio?accessKey=minioadmin\u0026secretKey=minioadmin\n          - SERVER_SECRET=secret\n          - ACCOUNTS_URL=http://account:3000\n          - DB_URL=mongodb://mongodb:27017\n          - MONGO_URL=mongodb://mongodb:27017\n          - STATS_URL=http://stats:4900\n          - FIRST_NAME=Bot\n          - LAST_NAME=Huly AI\n          - PASSWORD=\u003cPASSWORD\u003e\n          - OPENAI_API_KEY=\u003cOPENAI_API_KEY\u003e\n          - OPENAI_BASE_URL=\u003cOPENAI_BASE_URL\u003e\n          # optional if you use love service\n          - LOVE_ENDPOINT=http://love:8096\n        restart: unless-stopped\n    ```\n\n3. Configure `front` service:\n\n    ```yaml\n      front:\n        ...\n        environment:\n          # this should be available outside of the cluster\n          - AI_URL=http://aibot:4010\n        ...\n    ```\n\n4. Configure `transactor` service:\n\n    ```yaml\n      transactor:\n        ...\n        environment:\n          # this should be available inside of the cluster\n          - AI_BOT_URL=http://aibot:4010\n        ...\n    ```\n\n## Configure OpenID Connect (OIDC)\n\nYou can configure a Huly instance to authorize users (sign-in/sign-up) using an OpenID Connect identity provider (IdP).\n\n### On the IdP side\n1. Create a new OpenID application.\n   * 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.\n\n   **URI Example:**\n   - `http://huly.mydomain.com:3000/auth/openid/callback`\n\n2. Configure user access to the application as needed.\n\n### On the Huly side\n\nFor the account service, set the following environment variables as provided by the IdP:\n\n* OPENID_CLIENT_ID\n* OPENID_CLIENT_SECRET\n* OPENID_ISSUER\n\nEnsure you have configured or add the following environment variable to the front service:\n\n* ACCOUNTS_URL (This should contain the URL of the account service, accessible from the client side.)\n\nYou will need to expose your account service port (e.g. 3000) in your nginx.conf.\n\nNote: Once all the required environment variables are configured, you will see an additional button on the\nsign-in/sign-up pages.\n\n## Configure GitHub OAuth\n\nYou can also configure a Huly instance to use GitHub OAuth for user authorization (sign-in/sign-up).\n\n### On the GitHub side\n1. Create a new GitHub OAuth application.\n   * 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.\n\n   **URI Example:**\n   - `http://huly.mydomain.com:3000/auth/github/callback`\n\n### On the Huly side\n\nSpecify the following environment variables for the account service:\n\n* `GITHUB_CLIENT_ID`\n* `GITHUB_CLIENT_SECRET`\n\nEnsure you have configured or add the following environment variable to the front service:\n\n* `ACCOUNTS_URL` (The URL of the account service, accessible from the client side.)\n\nYou will need to expose your account service port (e.g. 3000) in your nginx.conf.\n\nNotes:\n\n* The `ISSUER` environment variable is not required for GitHub OAuth.\n* Once all the required environment variables are configured, you will see an additional button on the sign-in/sign-up\n  pages.\n\n## Disable Sign-Up\n\nYou can disable public sign-ups for a deployment. When configured, sign-ups will only be permitted through an invite\nlink to a specific workspace.\n\nTo implement this, set the following environment variable for both the front and account services:\n\n```yaml\n  account:\n    # ...\n    environment:\n      - DISABLE_SIGNUP=true\n    # ...\n  front:\n    # ...\n    environment:\n      - DISABLE_SIGNUP=true\n    # ...\n```\n\n_Note: When setting up a new deployment, either create the initial account before disabling sign-ups or use the\ndevelopment tool to create the first account._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcengineering%2Fhuly-selfhost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhcengineering%2Fhuly-selfhost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhcengineering%2Fhuly-selfhost/lists"}