[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-73416":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":9,"pushedAt":9,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":15,"starSnapshotCount":15,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},73416,"huly-selfhost","hcengineering\u002Fhuly-selfhost","hcengineering","Huly for Self Hosting",null,"Shell",3264,385,28,112,0,5,18,54,15,84.16,"Eclipse Public License 2.0",false,"main",true,[],"2026-06-12 04:01:09","# 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\nIf you prefer Kubernetes deployment, there is a sample Kubernetes configuration under [kube](kube) directory.\n\n## System Requirements\n\nHuly is resource-heavy. Use a server that meets or exceeds the following:\n\n- **Minimum:** 2 vCPUs and 8 GB RAM\n- **Recommended:** 4 vCPUs and 16 GB RAM or more\n\n> [!WARNING]\n> Servers below the minimum may stop responding or fail.\n\n\n## Platform Repository\n\nThe Huly platform source code is available on GitHub: **[hcengineering\u002Fplatform](https:\u002F\u002Fgithub.com\u002Fhcengineering\u002Fplatform)**\n\n> [!NOTE]\n> For self-hosted deployments, use production versions (`v*` tags). For example: `v0.7.310`, `v0.7.307`, `v0.6.501`\n> See all available versions on [GitHub Releases](https:\u002F\u002Fgithub.com\u002Fhcengineering\u002Fplatform\u002Freleases).\n\n## Updating to a new Huly version\n\nBefore updating, **always review `MIGRATION.md`** in this repository:\n\n- **Open `MIGRATION.md`** and find the section for your target version (for example `v0.7.423`).\n- **If the section says \"No changes required\"**, you can upgrade just by updating container versions.\n- **If there are additional steps**, follow them carefully (backup, config changes, service additions\u002Fremovals, etc.) **before** or **during** the update.\n- **If you are upgrading from any 0.6.x version to 0.7.x**, you **must** follow the dedicated migration steps in the `v0.7` section of `MIGRATION.md` (especially `v0.7.204`) instead of doing a direct in-place upgrade.\n\nTo update an existing self-hosted deployment to a new Huly version:\n\n1. **Stop the stack (optional but recommended for major upgrades):**\n   ```bash\n   cd huly-selfhost\n   docker compose down\n   ```\n2. **Update the `huly-selfhost` repository:**\n   ```bash\n   git pull\n   ```\n3. **Set the new Huly version in `.env`:**\n   - Edit the `.env` file in the project root and update:\n     - `HULY_VERSION` to the desired platform version tag (for example `v0.7.423`)\n     - `DESKTOP_CHANNEL` to the same version without the leading `v` (for example `0.7.423`) if you use the desktop app.\n4. **Pull updated container images:**\n   ```bash\n   docker compose pull\n   ```\n5. **Start the updated stack:**\n   ```bash\n   docker compose up -d\n   ```\n\n## Disable default content in new workspaces\n\nBy default, Huly can initialize new workspaces with predefined content. To disable that behavior, set `INIT_REPO_DIR` in the `workspace` service to a non-existing path:\n\n```yaml\nworkspace:\n  image: hardcoreeng\u002Fworkspace:${HULY_VERSION}\n  environment:\n    # ...\n    - INIT_REPO_DIR=\u002Fno-init-scripts\n```\n\n## Architecture Overview\n\nFor detailed information about the Huly self-hosted architecture, services, and their interactions, see [ARCHITECTURE_OVERVIEW.md](ARCHITECTURE_OVERVIEW.md).\n\n## Quick Start (Local Testing)\n\nFor fast local verification without going through the full setup process:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fhcengineering\u002Fhuly-selfhost.git\ncd huly-selfhost\n.\u002Fsetup.sh --quick\n```\n\nThis will:\n- Use `localhost:8087` as the host address\n- Skip all configuration prompts\n- Use default Docker volumes\n- Automatically start all services\n\nAccess Huly at **http:\u002F\u002Flocalhost:8087** (wait ~60 seconds for services to initialize). To stop all services, run `docker compose down` from the `huly-selfhost` folder.\n\n> [!NOTE]\n> Quick start is intended for local testing only. For production deployments, follow the full setup instructions below.\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:\u002F\u002Fdocs.docker.com\u002Fengine\u002Finstall\u002Fubuntu\u002F) from docker website.\nAfterwards perform [post-installation steps](https:\u002F\u002Fdocs.docker.com\u002Fengine\u002Finstall\u002Flinux-postinstall\u002F). 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:\u002F\u002Fgithub.com\u002Fhcengineering\u002Fhuly-selfhost.git\ncd huly-selfhost\n.\u002Fsetup.sh\n```\n\nThis will generate a [huly_v7.conf](.\u002Fhuly_v7.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)\u002Fnginx.conf \u002Fetc\u002Fnginx\u002Fsites-enabled\u002Fhuly.conf\n```\n\n> [!NOTE]\n> If you change `HOST_ADDRESS`, `SECURE`, `HTTP_PORT` or `HTTP_BIND` be sure to update your [nginx.conf](.\u002Fnginx.conf)\n> by running:\n> ```bash\n> .\u002Fnginx.sh\n> ```\n>You can safely execute this script after adding your custom configurations like ssl. It will only overwrite the\n> 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! To stop all services, run `docker compose down` from the `huly-selfhost` project directory.\n\n> [!IMPORTANT]\n> Provided configrations include deployments of CockroachDB and Redpanda which might not be production-ready. Please inspect them carefully before using in production. For more information on the recommended deployment configurations, please refer to the [CockroachDB](https:\u002F\u002Fwww.cockroachlabs.com\u002Fdocs\u002Fstable\u002Frecommended-production-settings) and [Redpanda](https:\u002F\u002Fdocs.redpanda.com\u002F24.3\u002Fdeploy\u002F) documentation.\n\n## Troubleshooting\n\n### Huly opens, but user sign-up fails\n\nIf the UI loads but sign-up fails, check logs for the `account` service first:\n\n```bash\ndocker compose logs -f account\n```\n\nThis usually reveals issues with account callbacks, URL configuration, or connectivity to dependent services.\n\n### SSL errors (for example: `SSL wrong version number`)\n\nThis usually means HTTPS\u002FWSS is enabled in configuration, but the endpoint is serving plain HTTP\u002FWS or has invalid TLS setup.\n\n- Verify your Nginx TLS configuration and certificates (`ssl_certificate`, `ssl_certificate_key`).\n- Confirm your domain points to the correct host and that port `443` is reachable.\n- For local\u002Ftesting deployments, disable secure mode by setting `SECURE=` in `huly_v7.conf`, then regenerate\u002Freload config and restart containers.\n\n## Volume Configuration\n\nBy default, Huly uses Docker named volumes to store persistent data (database, Elasticsearch indices, and uploaded files). You can optionally configure custom host paths for these volumes during the setup process.\n\n### During Setup\n\nWhen running `.\u002Fsetup.sh`, you'll be prompted to specify custom paths for:\n\n- **Elasticsearch volume**: Search index data storage  \n- **Files volume**: User-uploaded files and attachments\n- **CockroachDB data volume**: Data storage for workspaces and accounts\n- **CockroachDB certs volume**: Certificates for CockroachDB\n- **Redpanda data volume**: Data storage for Kafka\n\nYou can either:\n- Press Enter to use the default Docker named volumes\n- Specify an absolute path on your host system (e.g., `\u002Fvar\u002Fhuly\u002Fdb`)\n- Enter `default` to clear an existing custom path and revert to Docker named volumes\n\n> [!NOTE]\n> When using custom paths, pay attention to the permissions of the directory. each folder needs to be owned by the user defined in the setup script\n> for example: `chown -R 1000:1000 \u002Fvar\u002Fhuly\u002Fdb` (this is the user most services uses) but for example redpanda uses user 101\n\n### Quick Reset to Default Volumes\n\nTo quickly reset all volumes back to default Docker named volumes without prompts:\n\n```bash\n.\u002Fsetup.sh --reset-volumes\n```\n\n### Manual Configuration\n\nYou can also manually configure volume paths by editing the `huly_v7.conf` file:\n\n```bash\n# Docker volume paths - specify custom paths for persistent data storage\n# Leave empty to use default Docker named volumes\nVOLUME_ELASTIC_PATH=\u002Fpath\u002Fto\u002Felasticsearch\nVOLUME_FILES_PATH=\u002Fpath\u002Fto\u002Ffiles\nVOLUME_CR_DATA_PATH=\u002Fpath\u002Fto\u002Fcockroachdb\u002Fdata\nVOLUME_CR_CERTS_PATH=\u002Fpath\u002Fto\u002Fcockroachdb\u002Fcerts\nVOLUME_REDPANDA_PATH=\u002Fpath\u002Fto\u002Fredpanda\u002Fdata\n```\n\nTo revert to default volumes, simply leave the paths empty:\n\n```bash\nVOLUME_ELASTIC_PATH=\nVOLUME_FILES_PATH=\nVOLUME_CR_DATA_PATH=\nVOLUME_CR_CERTS_PATH=\nVOLUME_REDPANDA_PATH=\n```\n\nAfter modifying the configuration, restart the services:\n\n```bash\ndocker compose down\ndocker compose up -d\n```\n\n> [!WARNING]\n> When changing from named volumes to host paths (or vice versa), make sure to migrate your data appropriately to avoid data loss.\n\n## Redpanda Configuration\n\nWhen using a production deployment of Redpanda with topics auto-creation turned off, you'll need to manually create the following topics:\n\n- fulltext\n- process\n- tx\n- users\n- workspace\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\nAs the browser must access the public key for web push notifications setup, you also need to provide it to the front-end service.\n\nAdd the public key into `compose.yaml` in section `services:front:environment`:\n\n```yaml\n- PUSH_PUBLIC_KEY=your public key\n```\n\n## Web Push Notifications\n\n> [!NOTE]\n> In version 0.7.x and later, the legacy `ses` service has been replaced with the **`notification`** service for web push notifications and the `mail` service for sending emails using SES. New deployments should use the `notification` service.\n\nTo enable web push notifications in Huly, you need to configure the `notification` service with the VAPID keys and point `transactor` to it.\n\n### Step 1: Configure the Transactor Service\n\nAdd `WEB_PUSH_URL` to the `transactor` container:\n\n```yaml\ntransactor:\n  ...\n  environment:\n    - WEB_PUSH_URL=http:\u002F\u002Fnotification:8091\n  ...\n```\n\n### Step 2: Configure the Notification Service\n\nAdd the `notification` container to your `docker-compose.yaml` file with the generated VAPID keys:\n\n```yaml\nnotification:\n  image: hardcoreeng\u002Fnotification:${HULY_VERSION}\n  environment:\n    - PORT=8091\n    - SOURCE=mail@example.com\n    - STATS_URL=http:\u002F\u002Fstats:4900\n    - PUSH_PUBLIC_KEY=${PUSH_PUBLIC_KEY}\n    - PUSH_PRIVATE_KEY=${PUSH_PRIVATE_KEY}\n  restart: unless-stopped\n  networks:\n    - huly_net\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\u002Fmail:${HULY_VERSION}\n      container_name: mail\n      ports:\n        - 8097:8097\n      environment:\n        - PORT=8097\n        - SOURCE=\u003CEMAIL_FROM>\n      restart: unless-stopped\n      networks:\n        - huly_net\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:\u002F\u002Fmail:8097\n      ...\n    transactor:\n      ...\n      environment:\n        - MAIL_URL=http:\u002F\u002Fmail:8097\n      ...\n    ```\n\n3. In `Settings -> 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>\n        - SMTP_PORT=\u003CSMTP_SERVER_PORT>\n        - SMTP_USERNAME=\u003CSMTP_USER>\n        - SMTP_PASSWORD=\u003CSMTP_PASSWORD>\n    ```\n\n2. Replace `\u003CSMTP_SERVER_URL>` and `\u003CSMTP_SERVER_PORT>` with your SMTP server's hostname and port. It's recommended to use a secure port, such as `587`.\n\n3. Replace `\u003CSMTP_USER>` and `\u003CSMTP_PASSWORD>` 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>` and a token as `\u003CSMTP_PASSWORD>` for enhanced security.\n\n### Amazon SES Configuration\n\n1. Set up Amazon Simple Email Service in AWS: [AWS SES Setup Guide](https:\u002F\u002Fdocs.aws.amazon.com\u002Fses\u002Flatest\u002Fdg\u002Fsetting-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>\n        - SES_SECRET_KEY=\u003CSES_SECRET_KEY>\n        - SES_REGION=\u003CSES_REGION>\n    ```\n\n### Verifying Mail Service\n\nTo verify that the mail service is running correctly:\n\n```bash\n# Check if the mail container is running\nsudo docker ps | grep mail\n\n# View mail service logs\nsudo docker logs mail\n\n# Follow mail service logs in real-time\nsudo docker logs -f mail\n```\n\n### Troubleshooting SMTP Issues\n\nIf you're experiencing issues with email delivery, see the [SMTP Troubleshooting Guide](guides\u002Fsmtp-troubleshooting.md) for comprehensive debugging steps and solutions.\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## Gmail Integration\n\nHuly supports Gmail integration allowing users to connect their Gmail accounts and manage emails directly within the platform.\n\nFor detailed setup instructions, see the [Gmail Configuration Guide](guides\u002Fgmail-configuration.md).\n\n\n## Love Service (Audio & 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:\u002F\u002Fcloud.livekit.io) account\n2. Add `love` container to the docker-compose.yaml\n\n    ```yaml\n      love:\n        image: hardcoreeng\u002Flove:${HULY_VERSION}\n        container_name: love\n        ports:\n          - 8096:8096\n        environment:\n          - PORT=8096\n          - SECRET=${SECRET}\n          - ACCOUNTS_URL=http:\u002F\u002Faccount:3000\n          - DB_URL=${CR_DB_URL}\n          - STORAGE_CONFIG=minio|minio?accessKey=minioadmin&secretKey=minioadmin\n          - STORAGE_PROVIDER_NAME=minio\n          - LIVEKIT_HOST=\u003CLIVEKIT_HOST>\n          - LIVEKIT_API_KEY=\u003CLIVEKIT_API_KEY>\n          - LIVEKIT_API_SECRET=\u003CLIVEKIT_API_SECRET>\n        restart: unless-stopped\n        networks:\n          - huly_net\n    ```\n\n3. Configure `front` service:\n\n    ```yaml\n      front:\n        ...\n        environment:\n          - LIVEKIT_WS=\u003CLIVEKIT_HOST>\n        ...\n    ```\n\n4. Uncomment love section in `.huly.nginx` file and reload nginx\n\nNote that the `LIVEKIT_HOST` should include the protocol (`wss:\u002F\u002F` by default if using livekit cloud).\n\n## HulyPulse (Push \u002F real-time updates)\n\nHulyPulse provides WebSocket push notifications and real-time updates.\nIt will allow the following functions to work:\n- The knock and invite features in video calls\n- Information about who is viewing\u002Fediting objects right now\n- Shows that someone is typing a message in a chat.\n\nSince Huly platform version `v0.7.375`, HulyPulse supports an **in-memory backend**.\nBy default, templates in this repository use:\n\n- `HULY_BACKEND=memory`\n\nThis mode does not require Redis and is suitable for single-node or small self-hosted deployments.\n\n### Enabling HulyPulse (in-memory backend)\n\n1. Enable HulyPulse in `compose.yml`:\n   - Uncomment the `hulypulse` service.\n\n2. Configure the `transactor` service:\n\n    ```yaml\n    transactor:\n      ...\n      environment:\n        - PULSE_URL=http:\u002F\u002Fhulypulse:8099\n      ...\n    ```\n\n3. Configure the `front` service:\n\n    ```yaml\n    front:\n      ...\n      environment:\n        - PULSE_URL=http${SECURE:+s}:\u002F\u002F${HOST_ADDRESS}\u002F_pulse\n      ...\n    ```\n\n4. Uncomment the `\u002F_pulse` location in `.huly.nginx` and reload nginx:\n\n    ```bash\n    sudo nginx -s reload\n    ```\n\n5. Recreate and start the stack from the `huly-selfhost` folder:\n\n    ```bash\n    docker compose up -d --force-recreate\n    ```\n\n### Using Redis as backend (optional)\n\nRedis can be used as an alternative backend for HulyPulse – for example, in multi-node or higher-availability setups.\n\n1. Enable Redis and HulyPulse in `compose.yml`:\n   - Uncomment the `redis` service.\n   - Uncomment the `hulypulse` service.\n   - In the `hulypulse` environment, switch to Redis:\n\n     ```yaml\n     - HULY_BACKEND=redis\n     - HULY_REDIS_MODE=direct\n     - HULY_REDIS_URLS=redis:\u002F\u002Fredis:6379\n     # or with password:\n     # - HULY_REDIS_URLS=redis:\u002F\u002F:YOUR_PASSWORD@redis:6379\n     ```\n\n2. Redis is configured with a 512 MB memory limit by default in the provided `compose.yml`. Adjust limits, password, and URLs as needed for your production setup. The image tag uses `HULY_PULSE_VERSION` if set (default `0.1.29`).\n\n## Print Service\n\n1. Add `print` container to the docker-compose.yaml\n\n    ```yaml\n      print:\n        image: hardcoreeng\u002Fprint:${HULY_VERSION}\n        container_name: print\n        ports:\n          - 4005:4005\n        environment:\n          - STORAGE_CONFIG=minio|minio?accessKey=minioadmin&secretKey=minioadmin\n          - STATS_URL=http:\u002F\u002Fstats:4900\n          - SECRET=${SECRET}\n          - ACCOUNTS_URL=http:\u002F\u002Faccount:3000\n          - FRONT_URL=http${SECURE:+s}:\u002F\u002F${HOST_ADDRESS}\n        restart: unless-stopped\n        networks:\n          - huly_net\n    ```\n\n2. Configure `front` service:\n\n    ```yaml\n      front:\n        ...\n        environment:\n          - PRINT_URL=http${SECURE:+s}:\u002F\u002F${HOST_ADDRESS}\u002F_print\n        ...\n    ```\n\n3. Uncomment print section in `.huly.nginx` file and reload nginx\n\n## Export Service\n\n1. Add `exports` container to `compose.yml`\n\n```yml\nexports:\n    image: hardcoreeng\u002Fexport:${HULY_VERSION}\n    ports:\n      - 4009:4009\n    environment:\n      - STORAGE_CONFIG=minio|minio?accessKey=minioadmin&secretKey=minioadmin\n      - SECRET=${SECRET}\n      - DB_URL=${CR_DB_URL}\n      - ACCOUNTS_URL=http:\u002F\u002Faccount:3000\n      - SERVICE_ID=export-service\n      - PORT=4009\n    restart: unless-stopped\n    networks:\n      - huly_net\n```\n2. Configure `front` service\n\n```yml\nfront:\n  ...\n  environment:\n    ...\n    - EXPORT_URL=https:\u002F\u002F${HOST_ADDRESS}\u002F_export\n```\n3. Uncomment `_export` route in `.huly.nginx`\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. Enable MongoDB service (required by aibot):\n   - Uncomment the `mongodb` service in `compose.yml`\n   - Uncomment the `mongodb` volume entry in the `volumes` section of `compose.yml`\n   - MongoDB is used by the aibot service for storing conversation data\n3. Add `aibot` container to the docker-compose.yaml\n\n    ```yaml\n      aibot:\n        image: hardcoreeng\u002Fai-bot:${HULY_VERSION}\n        ports:\n          - 4010:4010\n        environment:\n          - STORAGE_CONFIG=minio|minio?accessKey=minioadmin&secretKey=minioadmin\n          - SERVER_SECRET=${SECRET}\n          - ACCOUNTS_URL=http:\u002F\u002Faccount:3000\n          - DB_URL=${CR_DB_URL}\n          - MONGO_URL=mongodb:\u002F\u002Fmongodb:27017\n          - STATS_URL=http:\u002F\u002Fstats:4900\n          - FIRST_NAME=Bot\n          - LAST_NAME=Huly AI\n          - PASSWORD=\u003CPASSWORD>\n          - OPENAI_API_KEY=\u003COPENAI_API_KEY>\n          - OPENAI_BASE_URL=\u003COPENAI_BASE_URL>\n          # optional if you use love service\n          - LOVE_ENDPOINT=http:\u002F\u002Flove:8096\n        restart: unless-stopped\n        networks:\n          - huly_net\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${SECURE:+s}:\u002F\u002F${HOST_ADDRESS}\u002F_aibot\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:\u002F\u002Faibot:4010\n        ...\n    ```\n5. Uncomment aibot section in `.huly.nginx` file and reload nginx\n\n> [!NOTE]\n> You can also add the `AI_OPENAI_MODEL`, `AI_OPENAI_TRANSLATE_MODEL`, `AI_OPENAI_SUMMARY_MODEL` environment variables to the aibot service to use a different model, by default it uses `gpt-4o-mini` for all of them\n\n## Configure Google Calendar Service\n\nTo integrate Google Calendar with Huly, follow these steps:\n\n### Google side\n\n1. Set up a Google Cloud project and enable the Google Calendar API in Google Cloud Console.\n2. Create OAuth 2.0 credentials. Use `Web application` as the application type and `https:\u002F\u002F${HOST_ADDRESS}\u002F_calendar\u002Fsignin\u002Fcode` (SET REAL VALUE INSTEAD OF ${HOST_ADDRESS}, https is required!!!) as Authorised redirect URIs. Save your credentials!\n3. Add these scopes `.\u002Fauth\u002Fcalendar.calendarlist.readonly` `.\u002Fauth\u002Fuserinfo.email` `.\u002Fauth\u002Fcalendar.calendars.readonly` `.\u002Fauth\u002Fcalendar.events`\n\n### Docker-compose side\n\nAdd `calendar` container to the docker-compose.yaml\n\n```yaml\n  calendar:\n    image: hardcoreeng\u002Fcalendar:${HULY_VERSION}\n    ports:\n      - 8095:8095\n    environment:\n      - MONGO_URI=mongodb:\u002F\u002Fmongodb:27017\n      - MONGO_DB=%calendar-service\n      - Credentials=\u003CJSON_STRING_CREDENTIALS_FROM_GOOGLE_CONSOLE>\n      - WATCH_URL=https:\u002F\u002F${HOST_ADDRESS}\u002F_calendar\u002Fpush\n      - ACCOUNTS_URL=http:\u002F\u002Faccount:3000\n      - STATS_URL=http:\u002F\u002Fstats:4900\n      - SECRET=${SECRET}\n      - KVS_URL=http:\u002F\u002Fkvs:8094\n    restart: unless-stopped\n    networks:\n      - huly_net\n```\n\n## Configure OpenID Connect (OIDC)\n\nYou can configure a Huly instance to authorize users (sign-in\u002Fsign-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}\u002Fauth\u002Fopenid\u002Fcallback` 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\u002Fbrowser side. In the provided example setup, the account service runs on port 3000.\n\n   **URI Example:**\n   - `http:\u002F\u002Fhuly.mydomain.com:3000\u002Fauth\u002Fopenid\u002Fcallback`\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\u002Fsign-up pages.\n\n## Configure GitHub OAuth\n\nYou can also configure a Huly instance to use GitHub OAuth for user authorization (sign-in\u002Fsign-up).\n\n### On the GitHub side\n1. Create a new GitHub OAuth application.\n   * Use `{huly_account_svc}\u002F_accounts\u002Fauth\u002Fgithub\u002Fcallback` 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\u002Fbrowser side.\n\n\n   **URI Example:**\n   - `http:\u002F\u002Fhuly.mydomain.com\u002F_accounts\u002Fauth\u002Fgithub\u002Fcallback`\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\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\u002Fsign-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\n## GitHub Service\n\nHuly provides GitHub integration for bi-directional synchronization of issues, pull requests, comments, and reviews.\n\n### Prerequisites\n\nSet up a GitHub Application for your deployment.\nPlease refer to [GitHub Apps documentation](https:\u002F\u002Fdocs.github.com\u002Fen\u002Fapps\u002Fcreating-github-apps\u002Fregistering-a-github-app\u002Fregistering-a-github-app) for full instructions on how to register your app.\n\nDuring registration of the GitHub app, the following secrets should be obtained:\n\n- `GITHUB_APPID` - The application ID number (e.g., `123456`), found under **General → About** in the GitHub App settings.\n- `GITHUB_APP_SLUG` - The app slug from its public URL: `github.com\u002Fapps\u002F\u003Cslug>`. For example, if the URL is `github.com\u002Fapps\u002Fmy-huly-dev`, the slug is `my-huly-dev`.\n- `GITHUB_CLIENTID` - The client ID shown on the same page (e.g., `Iv1.11a1aaa11aa11111`).\n- `GITHUB_CLIENT_SECRET` - A client secret generated in the **Client secrets** section of the General page.\n- `GITHUB_PRIVATE_KEY` - A private key for authentication. GitHub will generate and download a `.pem` file. This is an RSA key containing multiple lines — copy the entire content into the environment variable as-is.\n- `GITHUB_WEBHOOK_SECRET` - The webhook secret you set when configuring the webhook URL (see step 5 below).\n\n### Configure Permissions\n\nSet the following permissions for the app:\n\n- Commit statuses: _Read and write_\n- Contents: _Read and write_\n- Custom properties: _Read and write_\n- Discussions: _Read and write_\n- Issues: _Read and write_\n- Metadata: _Read-only_\n- Pages: _Read and write_\n- Projects: _Read and write_\n- Pull requests: _Read and write_\n- Webhooks: _Read and write_\n\n### Subscribe to Events\n\nEnable the following event subscriptions:\n\n- Issues\n- Pull request\n- Pull request review\n- Pull request review comment\n- Pull request review thread\n\n### Docker Configuration\n\n1. Add the `github` container to the `compose.yml`:\n\n```yaml\ngithub:\n  image: hardcoreeng\u002Fgithub:${HULY_VERSION}\n  ports:\n    - 3500:3500\n  environment:\n    - PORT=3500\n    - STORAGE_CONFIG=minio|minio?accessKey=minioadmin&secretKey=minioadmin\n    - SERVER_SECRET=${SECRET}\n    - ACCOUNTS_URL=http:\u002F\u002Faccount:3000\n    - STATS_URL=http:\u002F\u002Fstats:4900\n    - APP_ID=${GITHUB_APPID}\n    - CLIENT_ID=${GITHUB_CLIENTID}\n    - CLIENT_SECRET=${GITHUB_CLIENT_SECRET}\n    - PRIVATE_KEY=${GITHUB_PRIVATE_KEY}\n    - COLLABORATOR_URL=ws${SECURE:+s}:\u002F\u002F${HOST_ADDRESS}\u002F_collaborator\n    - WEBHOOK_SECRET=${GITHUB_WEBHOOK_SECRET}\n    - FRONT_URL=http${SECURE:+s}:\u002F\u002F${HOST_ADDRESS}\n    - BOT_NAME=${GITHUB_APP_SLUG}[bot]\n  restart: unless-stopped\n  networks:\n    - huly_net\n```\n\n2. Configure the `front` service:\n\n```yaml\n  front:\n   ...\n   environment:\n    # this should be available outside of the cluster\n    - GITHUB_URL=http${SECURE:+s}:\u002F\u002F${HOST_ADDRESS}\u002F_github\n    - GITHUB_APP=${GITHUB_APP_SLUG}\n    - GITHUB_CLIENTID=${GITHUB_CLIENTID}\n   ...\n```\n\n3. Uncomment the github section in `.huly.nginx` file and reload nginx\n\n4. Configure Callback URL and Setup URL (with redirect on update set) to your host: `http${SECURE:+s}:\u002F\u002F${HOST_ADDRESS}\u002Fgithub`\n\n5. Configure Webhook URL to `http${SECURE:+s}:\u002F\u002F${HOST_ADDRESS}\u002F_github\u002Fapi\u002Fwebhook` and set a webhook secret (use the same value as `GITHUB_WEBHOOK_SECRET` above)\n\n## Telegram Bot Service\n\nTelegram Bot Service is responsible for sending notifications from Huly to Telegram (private chats or groups). The service works as an external notification channel and does not provide interactive control or command execution for Huly.\n\n### Prerequisites\n\n1. Create a Telegram bot using **@BotFather**.\n2. Obtain the **BOT_TOKEN**.\n3. Determine the **CHAT_ID**:\n   - for private messages — send a message to the bot and retrieve `chat_id` using the `getUpdates` method\n   - for group chats — add the bot to the group and use the group `chat_id` (usually a negative value)\n\n### Docker Configuration\n\n1. Add the `telegram-bot` service to `compose.yml`:\n\n```yaml\n  telegram-bot:\n    image: hardcoreeng\u002Ftelegram-bot:${HULY_VERSION}\n    container_name: telegram-bot\n    restart: unless-stopped\n    environment:\n      - PORT=4020\n      - DB_URL=${CR_DB_URL}\n      - BOT_TOKEN=${TELEGRAM_BOT_TOKEN}\n      - ACCOUNTS_URL=http:\u002F\u002Faccount:3000\n      - SECRET=${SECRET}\n      - SERVICE_ID=telegram-bot-service\n      - STORAGE_CONFIG=minio|minio?accessKey=minioadmin&secretKey=minioadmin\n      - QUEUE_CONFIG=redpanda:9092\n      - QUEUE_REGION=\n    networks:\n      - huly_net\n```\n\n2. Configure the `front` service:\n\n```yaml\nfront:\n  ...\n  environment:\n    - TELEGRAM_BOT_URL=http${SECURE:+s}:\u002F\u002F${HOST_ADDRESS}\u002F_telegram\n  ...\n```\n\n3. Uncomment the _telegram section in the .huly.nginx file.\n\n### Notifications Setup\n\nAfter the service is running:\n\n1. Go to **Settings → Notifications**.\n2. Enable Telegram notifications.\n3. Specify the `CHAT_ID` where notifications should be delivered.\n\n> **Note**  \n> Notification settings are user-specific. Each user must configure Telegram notifications individually.\n","Huly Self-Hosted 是一个用于在服务器上自托管 Huly 平台的项目。它支持通过 Docker Compose 或 Kubernetes 部署，主要使用 Shell 脚本进行配置和管理。该项目要求至少 2 vCPUs 和 8 GB RAM 的服务器资源，推荐配置为 4 vCPUs 和 16 GB RAM 或更高。适用于需要将 Huly 平台部署到自己服务器上的用户或团队，特别是那些希望完全控制其数据和服务的企业。此外，项目提供了详细的迁移指南和架构概览文档，帮助用户顺利升级版本并理解系统内部结构。",2,"2026-06-11 03:45:26","high_star"]