Skip to content

Setup Gauzy (Self Hosted)

Jump to bottom
Ruslan K edited this page Feb 10, 2024 · 14 revisions

Using pre-build Ever Gauzy Server software

Please see https://github.com/ever-co/ever-gauzy/wiki/Gauzy-Server.

Using Helm in Kubernetes

Please see https://charts.ever.co and https://github.com/ever-co/ever-charts.

Setup in DigitalOcean

  1. Fork Gauzy Platform repo (private or public).

  2. Run PostgreSQL DB in DigitalOcean (DO) and create an empty DB. Take connection parameters and add them to your GitHub Secrets into corresponding env vars:

  • DB_HOST / DB_HOST_PUBLIC (Hostname of DB)
  • DB_PASS (Password for DB user)
  • DB_PORT (Database Port)
  • DB_SSL_MODE (value should be true if your DB provider requires SSL connectivity)
  • DB_TYPE (e.g. "postgres" for PostgreSQL DB)
  • DB_USER (Username used to connect to DB)

We recommend running the latest PostgreSQL (16.x) and also using connection pooling enabled for production workloads. Make sure you create a PostgreSQL cluster in the SAME region as your Kubernetes cluster.

You need to create a special env var DB_CA_CERT for DO DB CA Certificate, use the Bash command below to get a value for it (assuming you saved the CA Cert file in the ca-certificate.crt file):

base64 ca-certificate.crt
  1. Create Kubernetes cluster (k8s) in DO (latest version). We recommend running at least 2 node clusters, each node with 8Gb RAM or more. Make sure it runs in the same region as your DB and make sure you allow connection to DB from that cluster (it's a setting of PostgreSQL DB in DO). Write down the name of the cluster you created, you will need to update it in our codebase.

You need to define the env var that stores the DO access token: DIGITALOCEAN_ACCESS_TOKEN as it's used in the installation/configuration of doctl CLI:

- name: Install doctl
              uses: digitalocean/action-doctl@v2
              with:
                  token: ${{ secrets.DIGITALOCEAN_ACCESS_TOKEN }}

(see for example deploy-do-demo.yml file in the .github/workflows folder)

  1. Add an SSL Certificate for your domain to "Networking" in DO. We recommend using Cloudflare to generate such a server certificate (free of charge)

  2. Check GitHub actions that deploy docker containers to the k8s cluster in DigitalOcean (DO), e.g. https://github.com/ever-co/ever-gauzy/blob/develop/.github/workflows/deploy-do-prod.yml and note all names of env vars that needs to be created as GitHub Secrets (e.g. DB_USER, DB_PASSWORD, and so on).

  3. Check k8s Manifest in https://github.com/ever-co/ever-gauzy/blob/develop/.deploy/k8s/k8s-manifest.prod.yaml. You mostly need to replace some parameters, such as domain names, certificate IDs in DO, etc. In addition, you need to replace our docker images for API and UI (e.g. "registry.digitalocean.com/ever/gauzy-api:latest") with your own images (e.g. if you copy to your own registry, recommended for production workloads) or use our public images (see https://github.com/orgs/ever-co/packages?repo_name=ever-gauzy)

  4. After you defined all Secrets in GitHub and changed manifests/workflows described above, you need to push your changes to the develop branch (if it's your default one) and next to the master branch to make sure deployment proceeds. As a result, you should be able to see Pods running in the k8s cluster: for API and UI (frontend).

We estimate it should take from a few hours to about 8 hours of work for a senior DevOps Engineer (depending on many factors) and if you want us to help with that setup, feel free to email to ever@ever.tech. The cost will be calculated on the exact amount of hour setup takes on the 35$ per hour rate.

Setup in CoreWeave

  1. Register or Login in https://coreweave.com Note: At this stage, registration requires manual approval and additional approval for k8s usage!

  2. Define CW_KUBECONFIG env var (e.g. set it as GitHub Secret, if you are using GitHub Actions) with the value equal to base64 encoded k8s cluster config file:

base64 -w0 cw-kubeconfig
  1. SSL Certificates
  • Create SSL Certificates for the domain you would like to use. We recommend using Cloudflare.com and creating an "Origin Server Certificate".
  • Save the public key into pub.txt and the private key into key.txt and run the bellow commands to convert both into Base64 (Bash):
cat pub.txt | base64 -w0 > pub.64.txt
cat key.txt | base64 -w0 > key.64.txt

  • Copy content from pub.64.txt into INGRESS_API_CERT and INGRESS_WEBAPP_CERT secrets or env vars (assuming you run both API and Web UI on the sub-domains of the same domain)

  • Copy content from key.64.txt into INGRESS_API_CERT_KEY and INGRESS_WEBAPP_CERT_KEY Secrets or env vars

Setup in CIVO Cloud

  1. Register in https://www.civo.com
  2. Create k3s cluster and download kubeconfig file
  3. Encode base64 content of kubeconfig using below:
base64 -w0 civo-kubeconfig > k8s.txt
  1. Define CIVO_KUBECONFIG env var (e.g. set it as GitHub Secret, if you are using GitHub Actions) with the value equal to base64 encoded k8s cluster config file (see above)

Setup Manually on your server

It's common to setup Gauzy on some server (host, virtual server, virtual instance in some Cloud, or even PC in your home/office) to allow one or multiple clients to connect to it (from the browser, from our desktop, or mobile apps).

You need to setup 2 parts of the Ever Gauzy platform on your server: Gauzy API and Gauzy UI

Gauzy API setup

Please refer first to the basic steps outlined in our main README file here: https://github.com/ever-co/ever-gauzy#quick-start. You can use our pre-built Docker images or setup Manually on your server.

Below are some important notes regarding a production setup.

a) Make sure you setup a separate PostgreSQL DB (server or service). We recommend cloud services, such as AWS RDS (e.g. Aurora PostgreSQL), DigitalOcean PostgreSQL, or similar.

b) We recommend using PM2 for production setup. Please run yarn start:api:pm2 to run the backend APIs with PM2. It will allow a more reliable setup, and possibilities to monitor your processes with https://pm2.io, etc.

c) Make sure you made relevant changes in the .env file in the root of mono-repo or you submit correct environment variables if running Gauzy API using docker container. For example:

  • If you want to expose Gauzy APIs for external connectivity, you may need to set API_HOST env var to 0.0.0.0
  • If you need to connect Gauzy backend to external DB, please set env vars that start from DB_ (e.g. DB_TYPE=postgres, DB_HOST=XXX, etc)
  • Check other possible settings in the .env.sample file in the root of mono-repo.

Gauzy UI Setup

Please refer first to the basic steps outlined in our main README file here: https://github.com/ever-co/ever-gauzy#quick-start. You can use our pre-built Docker images or setup Manually on your server.

Below are some important notes regarding a production setup.

a) For production setup we recommend hosting Gauzy UI as a static build (e.g. in AWS S3 + Cloudfront or similar) or using PM2.

b) Please run yarn start:gauzy:pm2 to run the UI hosting with PM2 on your server. It will allow a more reliable setup, and possibilities to monitor your processes with https://pm2.io, etc.

c) Make sure you made relevant changes in the .env file in the root of mono-repo or you submit correct environment variables if running Gauzy UI using docker container.

Probably the most important environment variable for Gauzy UI is API_BASE_URL which is used in the frontend as an API endpoint URL to which the frontend sends all requests. For example, when running locally, API_BASE_URL is set to http://localhost:3000 (default API endpoint), but when UI running on a separate server (or statically hosted), you most likely want to set API_BASE_URL to something like https://api.mywebsite.com (for that, of course, you should configure DNS, SSL Certificate, etc) or something like http://IP-OF-API-SERVER:3000 (usually for testing).

Another important env var to expose Gauzy APIs for external connectivity is API_HOST, which you may want to set to 0.0.0.0.

d) if you run both Gauzy API and Gauzy UI, open UI in the browser, and see an error message such as "Gauzy Maintenance", it's most probably API_BASE_URL env variable is set incorrectly and as a result, the browser can't connect to correct API endpoint or the firewall on API server prevents your browser to connect to the API endpoint. To debug, open Chrome Web Tools (or similar) and check the Network tab to see where requests are sent for calls to the API (e.g. to endpoints like http(s)://xxxxxx/api/yyyyyy). In most cases you will be able to easily spot issues by looking into URL requests that are sent and errors you get (404, 500, or some other). Please see also https://github.com/ever-co/ever-gauzy/issues/3274 for a bit more information.

Clone this wiki locally