On Premise

To install Ideanote in your own environment, use the Ideanote Helm Chart.
This chart contains all the required components to get started and can scale to large deployments.

The Ideanote Helm Chart comes with "batteries included" and is designed to be easy to install and configure.
The chart includes multiple sub-charts and a default configuration that can be customized to suit your needs.
Please see the architecture section for more information on the components included in the Helm chart.

Architecture

Ideanote consists of multiple components that are deployed in a Kubernetes cluster with the help of the Ideanote Helm Chart.
The following diagram shows the architecture of these components and how they interact with each other.

Prerequisites

Before you deploy Ideanote in a Kubernetes cluster, you must decide on and follow the these prerequisites:

1. Create a Kubernetes cluster.

2. Install kubectl.

3. Install Helm.

4. Get a ZIP-folder from Ideanote team with required tokens to access the Helm chart and Docker images.

5. Authenticate with the Ideanote Helm registry

6. Choose how core services should be served

7. Choose how you want to do load balancing

8. Choose how to do backups

9. Choose how to do monitoring

10. Create tokens for integrations

11. Update the configuration in the values.yaml file

1. Create a Kubernetes cluster

A cluster with a total of at least 4 virtual CPUs and 10 GB of RAM is recommended.
Please refer to your cloud providers’ instructions on how to create a Kubernetes cluster.

2. Install kubectl

To install kubectl, see the Kubernetes installation documentation. The documentation covers most operating systems.

After you create the cluster, you must configure kubectl before you can interact with the cluster from the command line.

3. Install Helm

For this guide, we use the latest release of Helm v3 (v3.15.4 or later). To install Helm, see the Helm installation documentation.

4. A ZIP-folder from Ideanote team

To request access to the Ideanote Helm chart, you will need to get in contact the Ideanote team at hello@ideanote.io.
An Ideanote license is required in order to get this access token.

Ideanote will supply you with a ZIP-folder called ideanote-on-premise.zip containing the following:

• A values.yaml file with the default configuration. This file also contains registry secrets that are required for the Kubernetes cluster to pull Docker images. Please read this guide for more information on how to configure the Helm chart for production.
• A helm-access-token.json file containing the access token to the Helm registry.

5. Authenticate with the Ideanote Helm registry

Please run the following command to authenticate with the Helm registry using helm-access-token.json from the Ideanote-supplied ZIP-folder:

# Linux/MacOS
cat helm-access-token.json | helm registry login -u _json_key --password-stdin europe-west3-docker.pkg.dev

# Windows (Command Prompt)
type helm-access-token.json | helm registry login -u _json_key --password-stdin europe-west3-docker.pkg.dev

# Windows (PowerShell)
Get-Content helm-access-token.json | helm registry login -u _json_key --password-stdin europe-west3-docker.pkg.dev

Optional: You can run the following command to verify that you are authenticated with the Helm registry.
This will download the Ideanote Helm Chart to your local machine.

helm pull oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0

6. Choose how core services should be served

The Ideanote Helm Chart includes two sub-charts for database and caching services that are installed as part of the installation process:

• PostgreSQL that is used as the primary database
• Redis that is used as the caching service

However, for production environments, we recommend that you instead use externally managed services for Redis and PostgreSQL and provide the connection details when installing the Helm chart.

Therefore, before installing the Ideanote Helm Chart you must choose between the following two options:

1. Included sub-charts: Let the Helm chart automatically install Redis and PostgreSQL in your cluster. This is the default option.. Read more about how to configure these included core services here.
2. Managed core services: Use managed services for Redis and/or PostgreSQL. This option requires you to provide the connection details for the managed services when installing the Helm chart. Please follow this guide for more information on configuring your own managed services.

7. Choose how you want to do load balancing

The Ideanote Helm Chart includes two sub-charts for managing load-balancing and SSL certificates:

• ingress-nginx Ingress controller/load balancer that is used to route traffic to the Ideanote services.
• cert-manager that is used to automatically issue SSL certificates for the Ideanote services using Let’s Encrypt.

When installing the Ideanote Helm Chart, you must therefore choose between the following two options:

1. Included sub-charts: Let the Helm chart automatically install the ingress-nginx load balancer and cert-manager in your cluster. This is the default option. This option requires that you have a domain you own, to which you can add a DNS record. This can be a sub-domain such as poc.domain.com. The Let’s Encrypt servers must be able to resolve the IP-address of your Kubernetes cluster in order to issue certificates. Read more about how to configure the built in load-balancer here.
2. Managed load-balancer: Choose your own load-balancing solution with either your own managed Ingress controller/load balancer or a cloud provider’s load balancer. Read more about how to configure your own custom load-balancer here.

Regardless of what you choose above, when you install the Helm chart you must supply Ideanote with an URL that you will use to access the Ideanote services.
This URL must be added to the values.yaml file under global.ideanote.ingress.url.

global:
  ideanote:
    ingress:
      url: https://<your-domain>

If you choose to use the included nginx Ingress controller/load balancer and cert-manager sub-charts, you must also supply your email address in the values.yaml file.
This email address is used by Let’s Encrypt to issue SSL certificates for the Ideanote services.

cert-manager:
  email: <your-email-address>

8. Choose how to do backups

The Ideanote Helm Chart doesn't currently come with a built-in backup solution.
We strongly recommend that you set up a backup schedule for production deployments.

Depending on which sub-charts you choose to install, ideanote will create 3 PVCs (Persistent Volume Claims) in your cluster with volumes all of which you must back up:

• PostgreSQL database volume: data-<release>-postgresql-0 (not created if using managed PostgreSQL)
• Redis database volume: redis-data-<release>-redis-master-0 (not created if using managed Redis)
• Ideanote uploads volume: <release>-storage-data

9. Choose how to do monitoring

The Ideanote Helm Chart doesn't currently come with a built-in monitoring solution.
We are working on adding support for Prometheus and Grafana in the future.

The Ideanote services write logs to stdout and stderr.
These logs are then captured by the container runtime and can be accessed via Kubernetes tools like kubectl logs.
However, by default these logs are tied to the lifecycle of the pod so when a pod is terminated, its logs are lost unless preserved elsewhere.

Therefore, in order to set up proper monitoring for the Ideanote services you must install a monitoring solution that can collect these logs from the running containers in the Kubernetes cluster.

10. Create tokens for integrations

The following optional functionality requires that you create and configure tokens for (external) integrations. They are all optional.

• OpenAI integration for AI functionality. Set the ideanote.api.openai.key value to a valid OpenAI API key. Read more about how to configure the OpenAI integration here.
• Sendgrid integration for email-notification functionality. Set the ideanote.api.sendgrid.key value to a valid Sendgrid API key. Read more about how to configure the Sendgrid integration here.
• SAML integration for single sign-on functionality. Read more about how to configure the SAML integration here.
• LDAP integration for single sign-on functionality. Read more about how to configure the LDAP integration here.

11. Update the configuration in the values.yaml file

The values.yaml included with the ZIP-folder supplied by the Ideanote team contains the default configuration for the Ideanote Helm Chart.

The default configuration is not intended for production and can be used as a starting point for customizing the Helm chart for your needs.

Required values:

• global.ingress.url (required): The URL for Ideanote to operate under. Examples: https://domain.com, https://poc.domain.com, http://192.0.2.0. Read more about the load-balancing here.
• cert-manager.email (required if choosing default load-balancer and cert-manager): Your email address, so Let’s Encrypt can issue a certificate. Read more about cert-manager here.

Installing Ideanote

Before installing the Helm chart you will have to follow all the above 11 prerequisites.

To install the Ideanote Helm Chart, run the following command.
This assumes you have configured values.yaml according to the prerequisites and your needs.

helm install ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --create-namespace --namespace ideanote --wait --timeout 10m -f values.yaml

This will install the Ideanote services in your Kubernetes cluster in a new namespace called ideanote and a release name of ideanote.
Please wait a couple of minutes for all resources to be allocated and services to start.

You can check the status of each pod by running the following command:

kubectl get pods -n ideanote --watch

Follow these steps to complete the installation

These steps assume that you are installing the Ideanote Helm Chart with the included ingress-nginx load-balancer and cert-manager sub-charts.

1․ Collect the IP-address that has been dynamically allocated for the installed NGINX Ingress:

kubectl get ingress -l "app.kubernetes.io/part-of"=ideanote --namespace ideanote

2․ Add this IP-address to your DNS records for the domain you specified in the values.yaml file.

3․ Wait a couple of minutes for the DNS records to propagate and for cert-manager to issue the SSL certificates. Check up on the status of the certificates by running the following commands:

kubectl describe certificate -l "app.kubernetes.io/part-of"=ideanote --namespace ideanote

kubectl get certificaterequest -n ideanote
kubectl describe CertificateRequest ideanote-tls-1 -n ideanote

4․ Finally, visit the URL you specified in the values.yaml file to set up Ideanote.

Setting up your Ideanote workspace

Now that you have installed Ideanote in your Kubernetes cluster, the final step is to set up your Ideanote workspace.
You can access your Ideanote workspace by visiting the URL you specified in the values.yaml file and following the on-screen instructions.

You can choose to set up your workspace in two ways:

• From scratch: You can choose to set up a workspace from scratch. This will guide you through the process of creating an Ideanote owner account and a workspace.
• Import data: If you have been using Ideanote on ideanote.io in the past you can choose to import your entire workspace to your on-premise environment. To do this, please reach out to the Ideanote team that will supply you with a TAR-folder containing all your workspace data. This TAR-file should be imported during the workspace setup process when prompted.

Example deployments

This section contains examples of how to deploy Ideanote in different Cloud providers and environments.
This can serve as inspiration for how to deploy Ideanote in your own environment.
You can install Ideanote on a cloud provider of your choice but we recommend using AWS, Azure, or Google Cloud Platform.
You can also install Ideanote on a local Kubernetes cluster using Minikube.

All example deployments assume that you have followed the prerequisites and have configured the values.yaml file according to your needs.

Minikube

The configuration of Minikube will disable the included nginx load-balancing sub-chart and instead use the native routing addon provided by minikube.

To install Ideanote on Minikube, follow these steps:

1․ Install Docker

2․ Install Minikube

3․ Start Minikube with the following command. This will allocate 4 CPUs and 8 GB of RAM to the cluster:

minikube start --cpus 4 --memory 8192

4․ Enable the required addons:

minikube addons enable metrics-server
minikube addons enable ingress

5․ Make sure that the following configuration is set in the values.yaml file:

global:
  ideanote:
    ingress:
      # `minikube tunnel` will expose the load balancer on this IP
      url: "http://127.0.0.1"
      tls:
        enabled: false

# Disable both cert-manager and nginx because Minikube is using its own routing addon
cert-manager:
  install: false

ingress-nginx:
  install: false

6․ Install the Ideanote Helm chart:

helm install ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --create-namespace --namespace ideanote --wait --timeout 10m -f values.yaml

7․ Start the Minikube tunnel (and dashboard):

minikube tunnel
minikube dashboard

8․ Visit: http://127.0.0.1 and set up your Ideanote instance.

Azure Kubernetes Service (AKS)

The configuration of Azure will use the included nginx Ingress controller and cert-manager provided by the Ideanote Helm Chart.
If you instead choose to use Azure's native routing add-on for Kubernetes, you can do so by following these instructions and disabling the included services nginx and cert-manager (see how to disable those services here).

1․ Create an Azure Kubernetes Service (AKS) cluster with at least 2 vCPU and 8 GB memory (for example using Standard_DS2_v2). Read this guide for more information on how to create an Azure Kubernetes Cluster.

2․ Install the Azure CLI on your local machine. Read this guide for more information.

3․ Run the following command to configure kubectl to connect to your AKS cluster:

az aks get-credentials --resource-group Ideanote --name Ideanote

4․ Configure the values.yaml according to the prerequisites and your needs. Set global.ingress.url to the domain name you want to use for Ideanote. You will have to set up a DNS record for this domain later in this guide.

5․ Install the Ideanote Helm chart:

helm install ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --create-namespace --namespace ideanote --wait --timeout 10m -f values.yaml

6․ Wait a couple of minutes until all services have started and collect the IP-address that has been dynamically allocated by Azure for the installed NGINX Ingress:

kubectl get ingress -l "app.kubernetes.io/part-of"=ideanote --namespace ideanote

7․ Add this IP-address to your DNS records for the domain you specified in the values.yaml file.

8․ Wait a couple of minutes for the DNS records to propagate and then visit the URL you specified in the values.yaml file to set up Ideanote. Please read the troubleshooting guide if you are having issues with the URL/IP-address.

Configuring the LoadBalancer nginx Ingress controller for Azure

If you need to configure the included LoadBalancer nginx Ingress controller for Azure, you can do so by adding these annotations to the values.yaml file.
You can also use these annotations for assigning a static IP address to the LoadBalancer by following this guide.
For example:

ingress-nginx:
  controller:
    service:
      annotations:
        "service.beta.kubernetes.io/azure-load-balancer-resource-group": "MC_Ideanote_Ideanote_francecentral"
        "service.beta.kubernetes.io/azure-pip-name": "public-cluster-load-balancer-ip"

Using Azure spot nodes

Please add the following to the values.yaml file to run all deployments on Azure spot nodes:

tolerationsAndAffinity: &tolerationsAndAffinity
  affinity:
    nodeAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
          - matchExpressions:
              - key: "kubernetes.azure.com/scalesetpriority"
                operator: In
                values:
                  - "spot"
  tolerations:
    - key: "kubernetes.azure.com/scalesetpriority"
      operator: "Equal"
      value: "spot"
      effect: "NoSchedule"

postgresql:
  primary:
    <<: *tolerationsAndAffinity

redis:
  master:
    <<: *tolerationsAndAffinity

ingress-nginx:
  controller:
    <<: *tolerationsAndAffinity

cert-manager:
  <<: *tolerationsAndAffinity
  cainjector:
    <<: *tolerationsAndAffinity
  webhook:
    <<: *tolerationsAndAffinity
  startupapicheck:
    <<: *tolerationsAndAffinity

global:
  ideanote:
    <<: *tolerationsAndAffinity

Google Cloud Platform (GKE)

This example will show you how to set up Ideanote on a GCP Kubernetes Autopilot Cluster (GKE).
The cluster will be production ready with a managed PostgreSQL and a managed LoadBalancer, including CDN caching for assets.

Prerequisites:

• Follow all primary prerequisites
• You must own a domain that you can add a DNS record to
• You must have a Google Cloud Platform account

1․ Create a new VPC network
2․ Create a new Kubernetes Autopilot Cluster

• Attach the VPC network you created in step 1

3․ Create a new PostgreSQL instance

• Attach the VPC network you created in step 1
• Create a new database called ideanote
• Create a new user called ideanote and write down the password

4. Install gcloud cli and log in to your GCP account
5. Configure kubectl to connect to your GCP cluster

gcloud container clusters get-credentials <cluster> --region <region> --project <project>

6. Create a new static IP address for the LoadBalancer and write down the IP address:

gcloud compute addresses create ideanote-global --global
gcloud compute addresses list --project ideanote-sa

7. Go to your DNS provider and add an A record for the domain you want to use for Ideanote. Point the A record to the static IP address you created in step 6.

8. Configure the values.yaml file with the following values. Fill in values for global.ideanote.psql.host, global.ideanote.psql.passwordSecret.password, global.ideanote.ingress.url, and global.ideanote.gke.ingress.staticIPName.

global:
  # This will create GKE-specific resources such as selecting the native GCP ingress controller, creating backend/frontend configs and activating CDN caching for assets
  cloudProvider: GKE

  gke:
    ingress:
      staticIPName: "<static-google-cloud-ip-name>"

  ideanote:
    ingress:
      url: "https://<your-domain>"

    autoscaling:
      enabled: true

    resources:
      enabled: true

    psql:
      database: "ideanote"
      username: "ideanote"
      host: "<google-cloud-sql-ip>"
      passwordSecret:
        password: "<google-cloud-sql-password>"

    storage:
      persistence:
        size: "50Gi"

cert-manager:
  install: false

ingress-nginx:
  install: false

postgresql:
  install: false

redis:
  install: true
  master:
    persistence:
      size: 5Gi

9. (Optional) patch default Storage Class with allowVolumeExpansion: true which allows the PVCs to be easily resized:

kubectl patch storageclass standard-rwo -p '{"allowVolumeExpansion": true}'

10. Install the Ideanote Helm chart:

helm install ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --create-namespace --namespace ideanote --wait --timeout 10m -f values.yaml

11. Wait for the cluster to be ready and visit the URL specific in values.yaml. Autopilot clusters can take a long time to allocate resources initially. In addition, please wait up to 1 hour for Google Cloud to issue the SSL certificate.

Make your GKE cluster production ready

12. Patch volume claims with persistentVolumeReclaimPolicy: Retain to prevent data loss when deleting the Helm release:

kubectl patch pvc -n ideanote ideanote-storage-data -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
kubectl patch pvc -n ideanote redis-data-ideanote-redis-master-0 -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

13. Set up backups for the PostgreSQL database. You can use Cloud SQL backups or a third-party backup solution.

14. Set up backups for the entire Kubernetes cluster, including VPCs (Persistent Volume Claims) by following this guide.

Using GCP spot nodes

Please add the following to the values.yaml file to run deployments on GCP spot VMs:

nodeSelector: &nodeSelector
  nodeSelector:
    cloud.google.com/gke-spot: "true"

redis:
  master:
    <<: *nodeSelector

global:
  ideanote:
    <<: *nodeSelector

Ubuntu 24 with MicroK8s (AWS EC2 Instance, single node cluster)

This guide will show you how to install Ideanote on a single node Kubernetes cluster using MicroK8s on an AWS EC2 instance.
It uses the included MicroK8s addons nginx for load-balancing and hostpath-storage addon for storage.
Consider replacing these addons with a production-ready solution like openebs for storage and AWS ELB for load-balancing in a production environment.

1. Create a new Ubuntu 24 EC2 instance

• At least 4 CPUs and 8 GB of RAM (for example using t1.large instance type).
• At least 30 GB of storage.
• Check Allow HTTPS traffic from the internet
• Check Allow HTTP traffic from the internet
• Create, associate and download key-value pair for SSH access.

2. Associate the instance IP address with a domain name

Note the public IP address of the instance and associate it with a domain name that you own by adding an A record to the domain's DNS settings.
For example: ideanote.your-domain.com or your-domain.com.

3. SSH into the instance

4. Install MicroK8s

# Update the system
sudo apt update && sudo apt upgrade -y

# Install MicroK8s
sudo snap install microk8s --classic --channel=1.31

# Join the `microk8s` group
sudo usermod -a -G microk8s ubuntu
sudo chown -R ubuntu ~/.kube
newgrp microk8s

# Wait for all services to be running
microk8s status --wait-ready
microk8s kubectl get nodes
microk8s kubectl get services

# Alias `kubectl` to `microk8s kubectl`
alias kubectl='microk8s kubectl'

# Alias 'helm' to 'microk8s helm'
alias helm='microk8s helm'

# Add the above aliases to the `.bashrc` file
echo -e "\n# Alias kubectl to microk8s kubectl\nalias kubectl='microk8s kubectl'\n# Alias helm to microk8s helm\nalias helm='microk8s helm'" >> ~/.bashrc && source ~/.bashrc

5. Enable addons

# Required addons
microk8s enable ingress
microk8s enable hostpath-storage # Consider using "openebs" in production environment

# Optional addons
microk8s enable dashboard
microk8s enable metrics-server

6. Upload the ZIP-folder supplied by the Ideanote team to the instance

# Run this on your local machine
chmod 400 <key>.pem
scp -i <key>.pem ideanote-on-premise.zip ubuntu@<instance ip address>:/home/ubuntu

7. Unzip the ZIP-folder on the EC2 instance and authenticate with the Helm registry

sudo apt install unzip
cd /home/ubuntu
unzip ideanote-on-premise.zip
cat helm-access-token.json | helm registry login -u _json_key --password-stdin europe-west3-docker.pkg.dev

8. Update the values.yaml file with the following values

cert-manager:
  install: true
  email: <your-email-address>

# Don't install the included `nginx` Ingress controller as we are using the MicroK8s `ingress` addon
ingress-nginx:
  install: false

global:
  ideanote:
    ingress:
      url: "https://your-domain.com"

9. Install the Ideanote Helm chart

helm install ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --create-namespace --namespace ideanote --wait --timeout 10m -f values.yaml

10. Wait a couple of minutes for all services to start and for the SSL certificates to be issued by cert-manager

kubectl get deployments -n ideanote --watch
kubectl get certificaterequest -n ideanote --watch

11. Finally, visit https://your-domain.com to set up your Ideanote workspace

Configure values.yaml

The following table lists the configurable parameters of the Ideanote chart and their default values.

Configure included sub-charts

Configuring the included postgresql sub-chart

The Ideanote Helm Chart installs the Bitnami PostgreSQL chart as a sub-chart by default.
This configures a PostgreSQL database for the Ideanote service.

You can configure the PostgreSQL sub-chart by changing the values in the values.yaml file under the postgresql key.
Please see this list of allowed values for the included PostgreSQL sub-chart here
Example configuration:

postgresql:
  install: true
  primary:
    persistence:
      size: 5Gi
    resources:
      requests:
        memory: 1Gi
        cpu: 250m
      limits:
        memory: 2Gi
        cpu: 500m

Password

The included PostgreSQL sub-chart will automatically create a secret with the password for the database user and admin.
You can override the auto-generated password for the database by setting the global.ideanote.psql.passwordSecret.password value in the values.yaml file.

Connecting to the postgresql database from outside the cluster

To connect to your database from outside the cluster execute the following commands:

kubectl get secret -n ideanote ideanote-postgres-password -o jsonpath="{.data.postgres-password-user}" | base64 -d

kubectl exec -it -n ideanote svc/ideanote-postgresql -- psql -U ideanote -d ideanote
# or
kubectl port-forward -n ideanote svc/ideanote-postgresql 5432:5432 &
psql --host 127.0.0.1 -d postgres -p 5432 -U postgres

Configuring the included redis sub-chart

The Ideanote Helm Chart installs the Bitnami Redis chart as a sub-chart by default.
This configures a Redis database for the Ideanote service.

You can configure the Redis sub-chart by changing the values in the values.yaml file under the redis key.
Please see this list of allowed values for the included Redis sub-chart here.
Example configuration:

redis:
  install: true
  master:
    persistence:
      size: 5Gi
    resources:
      requests:
        memory: 1Gi
        cpu: 250m
      limits:
        memory: 2Gi
        cpu: 500m

Connecting to the redis database from outside the cluster

To connect to your redis database from outside the cluster execute the following commands:

kubectl exec -it -n ideanote svc/ideanote-redis-master -- redis-cli
# or
kubectl port-forward -n ideanote svc/ideanote-redis-master 6379:6379
redis-cli -h localhost -p 6379

Configuring the included ingress-nginx sub-chart

The Ideanote Helm Chart installs the ingress-nginx chart as a sub-chart by default.
This configures a load-balancer for the Ideanote service and is used as the ingress-controller for the Ideanote ingress object.

You can configure the ingress-nginx sub-chart by changing the values in the values.yaml file under the ingress-nginx key.
Please see this list of allowed values for the included ingress-nginx sub-chart here.

Example configuration:

ingress-nginx:
  enabled: true
  controller:
    service:
      annotations:
        cloud.google.com/load-balancer-type: "Internal"
    resources:
      requests:
        memory: 1Gi
        cpu: 250m
      limits:
        memory: 2Gi
        cpu: 500m

Configuring the included cert-manager sub-chart

The Ideanote Helm Chart installs the cert-manager chart as a sub-chart by default.
This configures the cert-manager to automatically create and manage TLS certificates for the Ideanote service.

You can configure the cert-manager sub-chart by changing the values in the values.yaml file under the cert-manager key.
Please see this list of allowed values for the included cert-manager sub-chart here.

Example configuration:

cert-manager:
  install: true
  installCRDs: false
  replicaCount: 2

Interacting with the cert-manager service

We recommend installing cmctl to interact with the cert-manager service.
This CLI tool can help you to manage cert-manager resources inside your cluster.

For example, with this tool you can renew the certificate by running the following command:

cmctl renew ideanote-tls -n ideanote

kubectl get certificaterequest -n ideanote

Configure external/managed services

Ideanote comes with included sub-charts for PostgreSQL, Redis and Load-balancer services.
These services are managed by the Ideanote Helm Chart and are installed by default when deploying Ideanote.
However we recommend using external/managed services for as many of these services as possible when running Ideanote in a production environment.
This will ensure that you have a reliable and scalable infrastructure.

This section included a guide for how to configure external/managed services for the PostgreSQL, Redis and the Load-balancer (the combination of ingress-nginx and cert-manager).

Configure an external PostgreSQL instance

In order to use an external PostgreSQL instance with Ideanote, you need to provide the connection details when installing the Ideanote Helm Chart.
Here is an example configuration for connecting to an external PostgreSQL instance:

global:
  ideanote:
    psql:
      database: <database>
      username: <username>
      host: <host>
      passwordSecret:
        password: <password>

      # You can also instead create a secret object yourself with "kubectl" and provide it here
      # passwordSecret:
      #   name: <secret-name>
      #   key: postgres-password      # The key in the secret object where the password is stored

postgresql:
  install: false

Configure an external Redis instance

In order to use an external Redis instance with Ideanote, you must provide the connection details when installing the Ideanote Helm Chart.
Here is an example configuration for connecting to an external Redis instance:

global:
  ideanote:
    redis:
      username: <username>
      host: <host>
      passwordSecret:
        password: <password>

      # You can also instead create a secret object yourself with "kubectl" and provide it here
      # passwordSecret:
      #   name: <secret-name>
      #   key: redis-password      # The key in the secret object where the password is stored

redis:
  install: false

Configure a custom load-balancer

We recommend using a native cloud provider load-balancer for the ingress controller.
Often cloud providers offer managed load-balancers that can be used with Kubernetes by setting the ingress class or adding annotations to the ingress object.
You can add these values using the following configuration:

global:
  ideanote:
    ingress:
      annotations: <annotations>
      className: <ingress-class>

cert-manager:
  install: false

ingress-nginx:
  install: false

Configure integrations

Here you can find guides on how to configure the different integrations that Ideanote supports.
None of these integrations are required for running Ideanote on-premise, but they can enhance the functionality of your workspace.

Configure Sendgrid integration

In order for Ideanote to send emails, you need to provide a Sendgrid API key when installing the Ideanote Helm Chart.
Please follow this guide for setting up the Sendgrid integration:

1․ Create a Sendgrid account if you don't already have one.

2․ Create an API key in the Sendgrid dashboard. It needs to have at least Mail Send capabilities.

3․ Provide the API key to the values.yaml file:

ideanote:
  api:
    sendgrid:
      key: "SG........."

Configure OpenAI integration

In order for Ideanote platform to provide AI-functionality, you need to provide an OpenAI API key when installing the Ideanote Helm Chart.
Please follow this guide for setting up the OpenAI integration:

1․ Create an OpenAI account if you don't already have one.

2․ Create an API key in the OpenAI dashboard. It needs to have All permissions.

3․ Provide the API key to the values.yaml file:

ideanote:
  api:
    openai:
      key: "sk-........."

Configure SAML integration

The Ideanote Helm Chart supports setting up your deployment as a SAML service provider so that you can use your own identity provider for authentication.
This requires you to provide a certificate when setting up the SAML integration.

Please follow this guide to set up the SAML integration:

1․ Create a self-signed certificate with the following command:

openssl req -x509 -nodes -days 730 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=my-service.example.com"

2․ Provide the certificate and key to the values.yaml file and install the Ideanote Helm Chart:

global:
  ideanote:
    saml:
      cert: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      key: ....

3․ Visit https://<your-domain>/api/sso/saml/metadata.xml this is now the metadata endpoint for your Ideanote SAML service provider.

4․ Configure your identity provider. Please follow this guide for more information and remember to replace the metadata.xml URL with your own.

Configure LDAP integration

Ideanote supports the LDAP protocol for integrating with your existing directory of users and groups, such as Microsoft Active Directory and Entra ID. You can use LDAP for authenticating and syncing users, both for just-in-time provisioning as they log in to your Workspace, or ahead-of-time via a Provisioning step built directly into the LDAP configuration wizard. LDAP is not configurable using the values.yaml configuration, but must instead be configured after or during the setup-process of your Ideanote workspace.

If you wish to use LDAP, but have not yet implemented LDAP in your IT-infrastructure, please consult the relevant documentation for implementing LDAP that matches your IT-infrastructure. We recommend the following resources:

• LDAP authentication with Microsoft Entra ID
• Step by Step Guide to Setup LDAPS on Windows Server

In this guide, we'll walk you through the setup process on the Ideanote platform.

Setting up LDAP on your Workspace

1. Go to Settings.
   
2. Go to Authentication.
   
3. Click on Add to create a new sign-in option.
   
4. Select LDAP from the list of options.
   

Configuring LDAP

1. Click on Add Configuration.
   
2. Enter your LDAP Server URL, excluding the ldap:// protocol, and exluding its port.
   
3. Enter the Bind DN/UPN, which is the Distinguished Name (DN) or the User Principal Name (UPN) in some environments such as Microsoft Active Directory or Microsoft Entra ID, used to bind (authenticate) to your LDAP directory. It specifies the entry within the directory that Ideanote will use for authentication and searching purposes. This acount should have read access to the directory. For example, a UPN may look like you@your-domain.com, making it easier to remember and use. Alternatively, a more traditional Bind DN might look like CN=Admin,OU=Users,DC=your-domain,DC=com, which specifies an administrative user within the Users organizational unit of the your-domain.com domain.
   
4. Enter the Bind Password. This is the password associated with the Bind Distinguished Name (Bind DN/UPN). This password is used by Ideanote to authenticate the specified Bind DN when connecting to the LDAP directory. This password should correspond to the account specified in the Bind DN/UPN field, whether it’s a User Principal Name (UPN) like you@your-domain.com or a traditional LDAP Distinguished Name like CN=Admin,OU=Users,DC=your-domain,DC=com. This password is critical for establishing a secure connection to perform searches and fetch user information for authentication processes. The stored value will be AES-256 encrypted.
   
5. Click on Test Connection to verify that the LDAP Server URL can be connected to, and that you can bind to it ("authenticate") with the provided Bind DN/UPN and Bind Password. If the connection is successful, the text LDAP connection successfully established will be visible next to the Test Connection button.
   

In case you encounter an issue, please see the Connection Troubleshooting section.

Additional configuration fields

1. Base DN represents the top-level of your directory tree that should be searched when provisioning users and groups. You can use this to narrow which branch of your directory to focus on. The Bind DN must have readable access to the Base DN and its objects.
   
2. The LDAP Filter, if given, will be applied when searching the directory that you have configured in your Base DN. This is useful if you want to enforce restrictions on the scope of users who can be provisioned and authenticate on your Workspace. You must use standard LDAP query syntax as described in RFC 4515. For example: (&(givenName=you)(sn=yourlastname)).
   
3. By toggling on Use SSL/TLS, LDAP over SSL (ldaps) will be enabled. Several additional
   fields will become visible, which you can read about here.
   
4. By toggling on Use StartTLS, StartTLS will be used to first begin an unencrypted connection over the standard LDAP port (389), but then later upgrade the connection to use TLS via a StartTLS operation. Several additional fields will become visible, which you can read about here.
   

Configure LDAPS or StartTLS

When Use SSL/TLS or Use StartTLS is toggled on, additional optional configuration fields will appear below it:

1. LDAP Server CA Certificate(s): Provide the Certificate Authority (CA) certificate(s) that signed your LDAP server's SSL certificate. This is required if your LDAP server uses self-signed certificates or certificates issued by a private CA. The certificate(s) should be in PEM format.
   
2. Client Certificate: Provide the client certificate to present to the LDAP server for authentication. This is Required if your LDAP server requires client certificate authentication. The certificate should be in PEM format.
   
3. Client Private Key: Provide the private key corresponding to your client certificate. This is required if you have provided a client certificate. The private key should be in PEM format and not password-protected.
   
4. Allow Self-Signed Certificates: Enable this to allow connections to LDAP servers using self-signed certificates without verifying the CA. Warning: Enabling this option can make your connection vulnerable to man-in-the-middle attacks.
   

Attribute Mapping

Many modern LDAPv3-compatible servers support querying the supported schema of available attributes. When available, Ideanote will detect the schema and come up with some good default suggestions for how to map from the data in your directory to equivalent Ideanote User/Team properties. You can see and customize these mappings from the Attribute Mapping page.

1. 
   LDAP-attribute represents attributes discovered in your LDAP-server schema. These come from your directory-provider, such as Microsoft Active Directory or Microsoft Entra ID. If for some reason your LDAP-server is not LDAPv3-compliant, we fall back to guessing what the attribute names may be, based on historical conventions and the attribute types outlined in RFC4519. For example givenName typically represents the firstname of a person, while sn typically represents the surname/lastname of a person.
   
2. 
   
   Type represents a simplified version of the Syntax definition of an LDAP attribute. There are many such Syntax definitions, all of which are described here in RFC4517, but for the purposes of simplicity, Ideanote combines them into the following definitions:
   
   
   
   
   
   
   
   • 
     string: Represents a sequence of characters. LDAP syntax definitions such as DirectoryString, PrintableString, TelephoneNumber, NumericString, and others will all use this type.
     
   • 
     date: Represents a date with a timestamp, either in Generalized Time (YYYYMMDDHHMMSSZ) or in UTCTime (YYMMDDHHMMSSZ). Ideanote will understand and parse this, so you can map it to date-specific Ideanote user/team properties.
     
   • 
     integer: While LDAP does not have syntax definitions for floating point values (these will instead use syntax definitions such as NumericString, which will be mapped to string in Ideanote), the `integer` type represents whole numbers, which can be mapped to numeric Ideanote user/team properties.
     
   • 
     boolean: the boolean values true and false.
     
   • 
     binary: some LDAP attributes represent binary data, such as the common thumbnailPhoto attribute for user profile avatars. These can typically only be mapped to avatar on Ideanote Users, and logo on Ideanote teams.
     
   • 
     reference: The DN (Distinguished Name) LDAP syntax definition refers to another entity with that DN, and is typically used in attribute mapping on the Ideanote platform to map the memberOf attribute of group associations for a User to equivalent Ideanote teams.
     
3. 
   Matching Ideanote attribute represents the data property on users/teams, the LDAP attribute should map to. You can customize it by clicking on the dropdown menu for each row in the list. The available options for selection will depend on the type of the LDAP-attribute. For example, an LDAP attribute of type date can not be mapped to First name.
   

Changing user groups/teams synchronization

If you want to synchronize (or stop synchronizing) the team memberships of a user when they sign in to Ideanote (or when they are pre-provisioned via the provisioning step), identify the LDAP attribute that represents the group(s) the user is part of.

With Microsoft Active Directory and Microsoft Entra ID, this attribute is commonly called memberOf, and has the reference type in Ideanote.

By default, this will already be mapped to the special Teams Ideanote user property, as seen in the illustration above.

If you want to stop synchronizing teams:

1. Identify the memberOf LDAP-attribute (or the equivalent property in your LDAP server schema)
2. Click the dropdown menu on that row, in the Matching Ideanote attribute column.
3. Select Do Not Import.

Creating a custom attribute mapping

The mappings Ideanote shows by default are based on our attempts to come up with good defaults. If you want to map other attributes to Ideanote, you can also click the Add Attribute button found under both the user and the group/team table.

In the dialog that appears, you will be able to type in a custom attribute name, and give it the data type that best matches it. The text field will show all other attributes discovered from your LDAP server that the default mapping suggestions didn't include. You don't have to pick any of these, although it is very likely your LDAP-server only supports any of the suggested attribute names.

Attribute mappings you have created via the Add Attribute dialog can be deleted by clicking the 'Cross'-icon next to the row as seen below, or by changing the mapping to Do Not Import.

Provisioning

As your users sign in to your Workspace, they will be provisioned. This means that their data representation in your directory will be synced to their equivalent Ideanote user, according to the Attribute Mapping rules you have defined.

However, there are many cases where it makes sense to provision users ahead of time. One popular use case is to pre-provision all your users and teams such that you can set up accesses across your idea collections before formally inviting them to contribute on your Workspace.

The Provisioning step in the LDAP-settings enables you to do this.

1. The Search field enables you to perform a search directly against your LDAP directory. Your entry will search within the common LDAP attributes distinguishedName, userPrincipalName, sAMAccountName, mail, displayName, and cn.
   
2. The Table shows all the entries that was fetched from your directory, as well as relevant details about each one, such as whether they represent a User or a Group, when they were last synced to your Workspace, etc.
   
3. The Filter allows you to narrow down the search results even further. You can either decide only to list groups or users, as well as only show entities that have never been provisioned on your Workspace.
   
4. The Start Provisioning Button starts the provisioning process. You will be able to follow the progress in a progress-bar next to the button. When provisioning is active, you will also be able to click Cancel to prevent additional entities from being provisioned.
   

Connection Troubleshooting

When LDAP has been configured correctly, the text LDAP connection successfully established will be visible next to the Test Connection button.

However, you may encounter some common issues. Below are troubleshooting tips for each potential error message:

Error: The LDAP server could not be resolved. Make sure you have typed in the correct Server URL and that your current network can connect to it.

Possible Causes:

• The LDAP Server URL may be mistyped or incorrect.
• The application cannot reach the LDAP server due to network restrictions.

Troubleshooting Steps:

• Double-check the hostname or IP address for typos.
• Confirm that the LDAP server is on the same Virtual Network as your Ideanote deployment. If not, set up network peering or a VPN so that the two networks can communicate.
• Ensure that outbound connections from the Kubernetes cluster running the on-premise deployment of Ideanote are allowed on the following ports:
  
  
  • 389 for LDAP (by default)
  • 636 for LDAPS (by default)
• Update firewall rules to permit traffic to the LDAP server on these ports.
• If using a hostname, verify that DNS resolution is correctly configured within the Kubernetes cluster.
• If you're using Microsoft Entra ID and you have just set up Microsoft Entra Domain Services for enabling the LDAP Integration, you must fully restart your Kubernetes cluster before it will be able to resolve the hostname.

Error: LDAP authentication with the provided Bind DN and Bind Password failed.

Possible Causes:

• The credentials are incorrect.
• Password hash synchronization is not enabled (a common issue with Microsoft Entra Domain Services)
• The bind user's account is disabled, locked, or expired.
• The LDAP server requires LDAPS, and you may not have enabled the Use SSL/TLS toggle, or provided incorrect certificates/keys.

Troubleshooting Steps:

• Double-check the Bind DN for correct syntax and typos.
  
  
  • The Bind DN should be the full DN of the user (e.g., cn=admin,dc=example,dc=com), or their UPN such as you@your-domain.com when using Microsoft Entra ID or Microsoft Active Directory.
• Ensure the Bind Password is correct.
• Authenticate using an LDAP client with the Bind DN and Bind Password to confirm they work outside of Ideanote.
• When using Microsoft Entra Domain Services, make sure that password hash synchronization is enabled. If you recently set up Microsoft Entra DOmain Services, you may have to reset the password of the Bind DN account you are trying to authenticate with. Here are the instructions for cloud-only user accounts, and here are the instructions for synced user accounts.
• Check that the bind user's account is active and not subject to any restrictions.
• Determine if the LDAP server requires SSL/TLS.
  
  
  • If so, enable Use SSL/TLS to use ldaps:// in the Server URL. Also make sure the LDAP Server PORT points to the correct port, which is 636 by default for LDAPS.
  • Verify that you have provided the correct LDAP Server CA Certificate, Client Certificate, and Client Private key (if required).
  • Test if enabling 'Allow Self-Signed Certificates' resolves the issue.
  • Ensure that the LDAP server's SSL certificate is trusted by the Kubernetes cluster.
  • Import the LDAP server's certificate into the cluster's trust store if necessary.

Error: LDAP authentication was successful, but the provided Base DN was not searchable.

Possible Causes:

• The Base DN is incorrect or points to the wrong location in the directory.
• The Bind user does not have permission to search the provided Base DN.

Troubleshooting Steps:

• Ensure the Base DN is correctly formatted (e.g., DC=your-domain,DC=com).
• Check for typos or misplaced commas and equal signs.
• Confirm that the bind user specified by the Bind DN has read/search permissions for the Base DN.
• Use an LDAP client (like ldapsearch) to test searching the Base DN with the bind user's credentials.
• Ensure that the directory structure under the Base DN contains the user entries you intend to access.

If none of these troubleshooting tips help, please consult the documentation provided by your infrastructure provider, or reach out to Ideanote for further troubleshooting help.

Configure for production

This section includes recommendations for configuring the Ideanote Helm Chart for production environments.

External services

We recommend offloading as many services as possible to external/managed services when running Ideanote in a production environment.
This is to ensure that you have a reliable and scalable infrastructure.

Especially the PostgreSQL service should be managed externally as the included PostgreSQL sub-chart does not support high-availability, backups and scaling out of the box.

Please refer to the Configure external/managed services section for more information on how to configure external services.

Autoscaling

By default, the Ideanote Helm Chart doesn't enable autoscaling for the services.
All services come with a default replica count of 1 and can be scaled manually by changing the replicaCount value in the values.yaml file.

You can enable autoscaling for the services by adding the following to the values.yaml file:

global:
  ideanote:
    autoscaling:
      enabled: true

ingress-nginx:
  controller:
    autoscaling:
      enabled: true
      minReplicas: 2
      maxReplicas: 6

This will create a Horizontal Pod Autoscaler (HPA) for each Ideanote service and scale the number of replicas based on the CPU and memory utilization of the service.
The api and webapp services will scale between 2 and 4 replicas by default and the rest between 1 and 4, but you can change the min and max replicas by changing the minReplicas and maxReplicas values in the values.yaml file for each service.
Example configuration:

ideanote:
  api:
    autoscaling:
      minReplicas: 3
      maxReplicas: 5

  html-renderer:
    autoscaling:
      enabled: false

  convert:
    autoscaling:
      minReplicas: 2
      maxReplicas: 3

Resource requests

By default, the Ideanote Helm Chart doesn't set resource requests for the Ideanote services.
This is to allow for services to run on clusters with limited resources.

In production environments, we recommend activating resource requests globally by adding the following to the values.yaml file:

global:
  ideanote:
    resources:
      enabled: true

Each service comes with a default CPU/Memory requests and limits that should work for most use-cases, so enabling resources globally should be enough.
However, if you need to change the resource requests for a specific service, you can do so by changing the values in the values.yaml file under the corresponding service key.
For example:

global:
  ideanote:
    resources:
      enabled: true

ideanote:
  api:
    resources:
      requests:
        memory: 1Gi
        cpu: 250m
      # Disable limits
      limits:
        memory: null
        cpu: null

postgresql:
  primary:
    resources:
      requests:
        memory: 1024Mi
        cpu: 500m
      limits:
        memory: 1536Mi
        cpu: 750m

redis:
  master:
    resources:
    requests:
        memory 512Mi
        cpu: 500m
    limits:
        memory: 768Mi
        cpu: 750m

ingress-nginx:
  controller:
    resources:
      requests:
        memory: 256Mi
        cpu: 250m
      limits:
        memory: 512Mi
        cpu: 500m

cert-manager:
  cainjector:
    resources:
      requests:
        cpu: 50m
        memory: 128Mi
  webhook:
    resources:
      requests:
        cpu: 50m
        memory: 128Mi
  startupapicheck:
    resources:
      requests:
        cpu: 50m
        memory: 128Mi
  resources:
    requests:
      cpu: 50m
      memory: 128M

Persistent volumes and backups

If installing the Ideanote Helm Chart with all included sub-charts it will create 3 PVCs (Persistent Volume Claims) in your cluster:

• data-<release>-postgresql-0 for the PostgreSQL database
• redis-data-<release>-redis-master-0 for the Redis database
• <release>-storage-data for the Ideanote media uploads

Kubernetes will allocate corresponding PVs (Persistent Volumes) to these PVCs and the data will be stored on these volumes.

For production deployments, we recommend doing the 3 following tasks:

1․ The default storage allocated for services is set to a minimum. We recommend increasing the storage size based on your needs by changing the values.yaml file:

postgresql:
  primary:
    persistence:
      # Used as primary database. Critical to increase if you expect a large amount usage.
      size: 10Gi

redis:
  master:
    persistence:
      # Used as a memory cache. Not necessarily critical to increase.
      size: 5Gi

ideanote:
  storage:
    persistence:
      # User uploaded files will be stored here. Increase if you expect large file uploads.
      size: 20Gi

2․ PVs are by default created with the reclaim policy Delete, which means that when the PVC is deleted, the PV and the data on it will be deleted as well. Therefore we recommend changing the reclaim policy to Retain for the PVs created by the Ideanote Helm Chart. You can do that by patching the allocated PVs with the following command:

# Set all PVs in the ideanote namespace to "Retain"
kubectl get pv -n ideanote -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}' | xargs -I {} kubectl patch pv {} -n ideanote -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

# Check that the PVs have been patched
kubectl get pv -n ideanote

# Patch individual PVs with the reclaim policy Retain
kubectl patch pv <pv-name> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' -n ideanote

3․ We also recommend setting up an automatic backup strategy for all volumes.

Logging and monitoring

Currently, Ideanote doesn't provide a built-in logging solution with the Helm chart, but we recommend setting up a monitoring solution in production environments.

In production environments, we also recommend adjusting global.ideanote.logLevel to info or warn in the values.yaml file to reduce the amount of logs generated by the services.

We also recommend setting up health checks to monitor the availability of your Ideanote deployment.
If you choose to set up health checks, these are the paths you should monitor:

External health checks

Internal health checks

Load balancing and CDN

If possible in your environment, we recommend setting up a CDN in front of the Ideanote load-balancer to cache static assets and reduce the load on the service.
Preferably, the CDN should be set up to cache all paths beginning with /files and /chunk-.

Upgrading

When running Ideanote on-premise, you will need to upgrade to a new version when a new release is available.
Ideanote will let you know when a new release is available and will provide release notes for each new version, which will include information on breaking changes and new features.

In production environments you will need to pay special attention to the upgrading guide provided by Ideanote to avoid any downtime or data loss.

Troubleshooting

Please reach out to developer@ideanote.io if you are having issues when running Ideanote on-premise.
Ideanote will help troubleshooting the issue and provide guidance on how to fix it according to the agreement in place.
Before reaching out, please check the following troubleshooting guide in order to understand and potentially fix the issue yourself.

The helm chart is failing to install

If the Ideanote Helm Chart is failing to install, please run the install command with the --debug flag to get more information about the error.
This will provide more detailed information about the error and help you understand what is causing the issue.

If you are not able to resolve the issue, please reach out to developer@ideanote.io for further assistance.
Please include as much information about the problem, including the output of installing with the --debug and the values.yaml file.

You can also get an overview of failing components by running the following command:

kubectl get all,certificaterequests,issuer -n ideanote

The helm chart is stuck in a pending state or failed state

See the status of the helm chart by running the following command:

helm status ideanote -n ideanote
# or
helm history ideanote -n ideanote

If the helm chart is stuck in a pending or failed state, you might have to roll back using the following command:

helm rollback ideanote -n ideanote

My URL/IP-address or SSL-certificate is not working

You can test if the IP-address associated with your load-balancer is answering correctly by running the following commands:

1․ Collect the IP-address that has been dynamically allocated for your load-balancer. Make sure that the ingress is associated with an IP-address and host-names.

kubectl get ingress -n ideanote

2․ Check if your Kubernetes cluster is responding correctly to requests by using this curl command with values (the associated IP-address and one host name) from the above command. Make sure that it responds with a 200 OK status code and the index-html of the Ideanote service.

# With only host
curl -kivL <host>

# With host and IP-address
curl -kivL -H 'Host: <host>' <ip-address>

3․ With included nginx ingress-controller sub-chart, the service should be available with a TLS certificate after a couple of minutes. It will be using a self-signed certificate provided as a default from the ingress-nginx-controller until the certificate has been created. Browsers will show a warning that this is an invalid certificate. After a couple of minutes, the certificate should be created and the service should be available with a valid certificate.

4․ You can check the status of the CertificateRequest by running the following command:

kubectl get certificaterequest -n ideanote
kubectl describe CertificateRequest ideanote-tls-1 -n ideanote
kubectl get Issuer -n ideanote

The API service keeps crashing because it can't connect to the database/redis

If the api service is crashing because it can't connect to the database or Redis, please check the following.

2․ Check the logs of the api service:

kubectl logs -n ideanote svc/ideanote-api

2․ Check if postgres and redis are running (follow steps )

kubectl get pods -n ideanote

Sometimes your might just need to force restart the api service to make it connect to the database and Redis again.

kubectl get pods -n ideanote
kubectl delete pod <pod-name> -n ideanote --force

kubectl run --rm -it --image=busybox test-pod -- /bin/sh
ping <redis-service-ip>
nc -zv <redis-service-ip> 6379

ping <postgres-service-ip>
nc -zv <postgres-service-ip> 5432

kubectl exec -it -n ideanote svc/ideanote-api -- /bin/sh

I'm seeing a lot of TypeError: fetch failed errors in the logs

First, check that all pods are running:

kubectl get pods -n ideanote

You can also check that you can you can resolve the DNS for the service directly from the pod. For example:

kubectl exec svc/ideanote-api -n ideanote -- nslookup ideanote-convert.ideanote.svc.cluster.local

You can check that you can ping other services directly from the pod. For example:

kubectl exec svc/ideanote-webapp -n ideanote -- wget -qO- http://ideanote-api.ideanote.svc.cluster.local

It can also be a problem related to network policies which can sometimes block communication between services.
You might have to temporarily disable network policies for Ideanote to see if that is the issue.
You can disable network policies by setting global.ideanote.networkPolicies.enabled to false in the values.yaml file.

Monitor network traffic in your cluster

You can use https://www.kubeshark.co/ to monitor network traffic in your cluster.

1․ Install kubeshark

sh <(curl -Ls https://kubeshark.co/install)

# OR

brew install kubeshark

2․ Start kubeshark

kubeshark tap -n ideanote

3․ Open the kubeshark dashboard in your browser and monitor traffic

Testing the availability of each service

Here is an overview of how to test the availability of each service.
Please use this guide as a reference for how to test each service in case of issues.

Streaming logs

In order to see the logs for a specific service, you can use the following command.

kubectl logs -n ideanote svc/ideanote-api

This is useful for debugging issues with the service. You can also print logs for all pods in the ideanote namespace by running the following command:

kubectl get pods -n ideanote -o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{end}' | xargs -I {} kubectl logs -n ideanote {} --all-containers=true

If you wish to stream logs for all services at once, we recommend installing kubetail and running the following command:

kubetail -n ideanote

During troubleshooting we also recommend adjusting global.ideanote.logLevel to debug in the values.yaml file to increase the amount of logs generated by the services.

Check the status of services

To check if the deployments are ready, you can run the following command. It should say 1/1 READY for each service.

kubectl get deployments -n ideanote

If one of the services is not ready, you can check the service by running the following command:

kubectl describe deployment <service-name> -n ideanote

For a more detailed view of the services we recommend installing k9s and running the following command:

k9s -n ideanote

webapp

The webapp service should be available at the / path. The following command should return a 200 OK status code with the index html:

curl -kL your-domain.com

Alternatively, you can port-forward the service to your local machine and test it with curl:

kubectl port-forward --namespace ideanote svc/ideanote-webapp 3000:80
curl -kL localhost:3000

api

The api service should be available at the /api path. The following command should return a 200 OK status code with the text "Ideanote API":

curl -kL your-domain.com/api

Alternatively, you can port-forward the service to your local machine and test it with curl:

kubectl port-forward --namespace ideanote svc/ideanote-webapp 3000:80
curl -kL localhost:3000

If you want to inspect the internal message queue of the Ideanote API, you can visit the /api/bullmq path.
To get the credentials for the API message queue, please run the following command:

kubectl get secret --namespace ideanote ideanote-api -o jsonpath="{.data.API_BULLMQ_CREDENTIALS}" | base64 -d

idea-widget

The idea-widget service should be available at the /widget path. The following command should return a 200 OK status code with the index html:

curl -kL your-domain.com/widget

Alternatively, you can port-forward the service to your local machine and test it with curl:

kubectl port-forward --namespace ideanote svc/ideanote-idea-widget 3000:80
curl -kL localhost:3000

storage

The storage service should be available at the /files path. The following command should return a 200 OK status code with the text "Ideanote Storage":

curl -kL your-domain.com/files

Alternatively, you can port-forward the service to your local machine and test it with curl. It should return a 200 OK status code with the text "Ideanote Convert":

kubectl port-forward --namespace ideanote svc/ideanote-storage 3000:80
curl -kL localhost:3000

convert

The convert service isn't exposed to the internet, but you can test it by port-forwarding the service to your local machine and testing it with curl.
It should return a 200 OK status code with the text "Ideanote Convert":

kubectl port-forward --namespace ideanote svc/ideanote-convert 3000:80
curl -kL localhost:3000

You can also check the state of the media upload convert jobs by visiting the /bullmq path.

# 1: Port-forward the service to your local machine
kubectl port-forward --namespace ideanote svc/ideanote-convert 3000:80
# 2: Visit the /bullmq path in a browser:
http://localhost:3000/bullmq

html-renderer

The html-renderer service isn't exposed to the internet, but you can test it by port-forwarding the service to your local machine and testing it with curl.
It should return a 200 OK status code with the text "Ideanote HTML Renderer":

kubectl port-forward --namespace ideanote svc/ideanote-html-renderer 3000:80
curl -kL localhost:3000

postgresql

In order to check the availability of the PostgreSQL service, you can port-forward the service to your local machine and test it with psql.

# 1. Get the password for the database
kubectl get secret --namespace ideanote ideanote-postgres-password -o jsonpath="{.data.postgres-password-user}" | base64 -d

# 2. Open a connection to the database
kubectl exec -it -n ideanote svc/ideanote-postgresql -- psql -U ideanote -d ideanote

# 3. Check that the API has correctly run migrations in the database.
#    It should show a list of tables.
#    If this command shows "Did not find any relations." it means that the API hasn't been able to connect to the database.
ideanote=> \d

# 4. Exit psql
ideanote=> \q

redis

In order to check the availability of the Redis service, you can port-forward the service to your local machine and test it with redis-cli.

# 1. Port-forward the service to your local machine
kubectl port-forward --namespace ideanote svc/ideanote-redis-master 6379:6379

# 2. Initiate a connection to the database
redis-cli -h localhost -p 6379

# 3. Check that the api and convert services have been able to connect to the database.
127.0.0.1:6379> CLIENT LIST

# 4. Check that the api and convert services have been able to create keys in the database.
127.0.0.1:6379> KEYS *

cert-manager

Please see the official guide for how to verify that cert-manager is installed correctly.

If your certificate is not being created, you can check the status of the CertificateRequest by running the following command:

kubectl get certificaterequest -n ideanote
kubectl describe CertificateRequest ideanote-tls-1 -n ideanote

You can also check the status of the Issuer by running the following command:

kubectl get Issuer -n ideanote

It's also helpful to check the logs of the cert-manager service to see if there are any issues.

ingress-nginx

To check the status of the ingress-nginx service, first verify that it is running:

kubectl get deployments -l app.kubernetes.io/name=ingress-nginx -n ideanote

Try port-forwarding the service to your local machine and test it with curl (which should return a "404 Not Found" status code):

kubectl port-forward --namespace ideanote svc/ideanote-ingress-nginx-controller 8080:80
curl -kL localhost:8080

You should also verify that is has been allocated an IP-address:

kubectl get svc -l app.kubernetes.io/name=ingress-nginx -n ideanote

Also verify that the Ideanote ingress object has been correctly assigned to the ingress-nginx load-balancer.
It should show the same IP-address as the ingress-nginx service and the expected host name that you set in the values.yaml file when installing the Ideanote Helm Chart.

kubectl get ingresses -n ideanote

Try to curl the IP-address. It should return with a "404 Not Found" status code:

curl -kL <ip-address>

Now try to include a "Host" header in the request.
It should respond with the index html of the Ideanote webapp service:

curl -kL -H 'Host: <host>' <ip-address>

Finally try visiting the domain in a browser. It should show the Ideanote webapp.

Upgrading Ideanote to a new version

Ideanote will periodically release new versions of the Ideanote Helm Chart with new features and bug fixes.
When upgrading to a new version, you will need to follow the upgrade guide provided by Ideanote in order to avoid any downtime or data loss.

All services are designed to be stateless (expect for redis, postgres and storage) and can be upgraded without any downtime using a rolling update strategy.

Releases and database migrations happen automatically and are developed to have at least downtime as possible.
During database migrations which typically takes a couple of minutes, the services will still be available, but some features might be disabled or slow down until the migration is complete.
Please refer to the release notes for each new version to see if there are any migrations to be aware of.

We make sure to test releases in our own production environments before releasing them to the public, but we recommend that you test the new version in a staging environment before upgrading the production environment.

Before upgrading to a new version, please follow these steps

1․ Check the release notes to see if there are any breaking changes or new features.

2․ Backup your data. We recommend taking a backup of the PostgreSQL and Redis databases before upgrading to a new version. In addition, have a clear and tested database rollback plan in case the upgrade fails.

3․ We recommend installing the helm-diff plugin and running the following command to see the exact changes that will be made to your Kubernetes cluster:

HELM_DIFF_USE_INSECURE_SERVER_SIDE_DRY_RUN=true helm diff upgrade oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --namespace ideanote --values values.yaml --dry-run=server

When upgrading to a new version, please follow these steps:

1․ Upgrade the Ideanote Helm Chart to the new version:

helm upgrade ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --namespace ideanote --wait --timeout 10m -f values.yaml

2․ Check the status of the upgrade:

helm status ideanote --namespace ideanote

helm history ideanote --namespace ideanote

kubectl get pods -n ideanote --watch

3․ api is the most critical service to check after an upgrade because migrations can take a couple of minutes to complete and potentially fail causing downtime. Stream API logs to monitor migrations:

kubectl logs svc/ideanote-api -n ideanote -f

When rolling back to a previous version, please follow these steps:

1․ Check if any migrations has been run in the api service:

kubectl logs svc/ideanote-api -n ideanote

You can also check the status of the api migrations using psql:

# 1. Get the password for the database
kubectl get secret --namespace ideanote ideanote-postgres-password -o jsonpath="{.data.postgres-password-user}" | base64 -d

# 2. Open a connection to the database
kubectl exec -it -n ideanote svc/ideanote-postgresql -- psql -U ideanote -d ideanote

# 3. Check if the API has ran migrations in the database. You can compare "migration_time" with the current date.
ideanote=> select * from knex_migrations order by migration_time desc limit 10;

2․ Rollback helm to the previous version:

helm rollback ideanote --namespace ideanote

3․ Check the status of the rollback:

helm status ideanote --namespace ideanote

4․ If any migrations did in fact complete in the api service and you need to roll back, it's critical that you also roll back the database to the previous state, because the new database schema might not be compatible with the old version of the api service and the api pod will fail to start due to database schema mismatch.

Helm Chart Releases

Here is a list of the releases of the Ideanote Helm Chart and the changes made in each release.

1.0.0

The initial release of the public Ideanote Helm Chart.

Changing values.yaml after installation

If you change the values.yaml file after the installation of the Ideanote Helm Chart, you can upgrade the release with the following command:

helm upgrade ideanote oci://europe-west3-docker.pkg.dev/ideanote/charts/ideanote --version 1.0.0 --namespace ideanote --wait --timeout 10m -f values.yaml

Uninstalling Ideanote

To uninstall the Ideanote Helm Chart, run the following command:

helm uninstall ideanote --namespace ideanote

This will remove all resources and services associated with the Ideanote Helm Chart from your Kubernetes cluster.

However, not all resources will be uninstalled, and you will need to manually remove the following resources:

# Delete all PVCs associated with the Ideanote Helm Chart
kubectl delete pvc -l app.kubernetes.io/name=postgresql -n ideanote
kubectl delete pvc -l app.kubernetes.io/name=redis -n ideanote
kubectl delete pvc -l app.kubernetes.io/name=storage -n ideanote

# Delete all PV's associated with the Ideanote Helm Chart
kubectl get pv -n ideanote
kubectl delete pv <pv-name>

# Delete global CustomResourceDefinitions (don't do this if you have multiple Ideanote installations in the same cluster)
kubectl delete crd \
  issuers.cert-manager.io \
  clusterissuers.cert-manager.io \
  certificates.cert-manager.io \
  certificaterequests.cert-manager.io \
  orders.acme.cert-manager.io \
  challenges.acme.cert-manager.io

# Delete the namespace
kubectl delete namespace ideanote