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.
If you prefer Kubernetes deployment, there is a sample Kubernetes configuration under kube directory.
First, let's install nginx
and docker
using the commands below if you have not already installed them on your machine.
$ sudo apt update
$ sudo apt install nginx
$ sudo snap install docker
Next, let's clone the huly-selfhost
repository and configure the server address. Please replace x.y.z.w with your server's IP address.
$ git clone https://github.com/hcengineering/huly-selfhost.git
$ cd huly-selfhost
$ ./setup.sh x.y.z.w # Replace x.y.z.w with your server's IP address
$ sudo ln -s $(pwd)/nginx.conf /etc/nginx/sites-enabled/
Finally, let's restart nginx
and run Huly with docker compose
.
$ sudo systemctl restart nginx
$ sudo docker compose up
Now, launch your web browser and enjoy Huly!
When exposing your self-hosted Huly deployment to the internet, it's crucial to implement some security measures to protect your server and data.
- Do not expose MongoDB, MinIO, and Elastic services to the internet. Huly does not require them to be accessible from the internet.
- It is highly recommended to change the default credentials. By default the services, mentioned above, require no authentication, or use default well-known credentials.
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:
=======================================
Public Key:
sdfgsdgsdfgsdfggsdf
Private Key:
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
-
Setup Amazon Simple Email Service in AWS: https://docs.aws.amazon.com/ses/latest/dg/setting-up.html
-
Add email address you'll use to send notifications into "SOURCE", SES access such as ACCESS_KEY, SECRET_KEY, REGION
ses: image: hardcoreeng/ses:v0.6.295 container_name: ses ports: - 3335:3335 environment: - SOURCE=<EMAIL_FROM> - ACCESS_KEY=<SES_ACCESS_KEY> - SECRET_KEY=<SES_SECRET_KEY> - REGION=<SES_REGION> - PORT=3335 restart: unless-stopped
-
Add SES container URL into
transactor
andaccount
containers:account: ... environment: - SES_URL=http://ses:3335 ... transactor: ... environment: - SES_URL=http://ses:3335 ...
-
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.
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:
-
Set up LiveKit Cloud account
-
Add
love
container to the docker-compose.yamllove: image: hardcoreeng/love:v0.6.295 container_name: love ports: - 8096:8096 environment: - STORAGE_CONFIG=minio|minio?accessKey=minioadmin&secretKey=minioadmin - SECRET=secret - ACCOUNTS_URL=http://account:3000 - DB_URL=mongodb://mongodb:27017 - MONGO_URL=mongodb://mongodb:27017 - STORAGE_PROVIDER_NAME=minio - PORT=8096 - LIVEKIT_HOST=<LIVEKIT_HOST> - LIVEKIT_API_KEY=<LIVEKIT_API_KEY> - LIVEKIT_API_SECRET=<LIVEKIT_API_SECRET> restart: unless-stopped
-
Configure
front
service:front: ... environment: - LIVEKIT_WS=<LIVEKIT_HOST> - LOVE_ENDPOINT=http://love:8096 ...
You can configure a Huly instance to authorize users (sign-in/sign-up) using an OpenID Connect identity provider (IdP).
-
Create a new OpenID application.
- Use
{huly_account_svc}/auth/openid/callback
as the sign-in redirect URI. Thehuly_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
- Use
-
Configure user access to the application as needed.
For the account service, set the following environment variables as provided by the IdP:
- OPENID_CLIENT_ID
- OPENID_CLIENT_SECRET
- OPENID_ISSUER
Ensure you have configured or add the following environment variable to the front service:
- ACCOUNTS_URL (This should contain 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.
Note: Once all the required environment variables are configured, you will see an additional button on the sign-in/sign-up pages.
You can also configure a Huly instance to use GitHub OAuth for user authorization (sign-in/sign-up).
-
Create a new GitHub OAuth application.
- Use
{huly_account_svc}/auth/github/callback
as the sign-in redirect URI. Thehuly_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
- Use
Specify the following environment variables for the account service:
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.)
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.
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:
account:
...
environment:
- DISABLE_SIGNUP=true
...
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.