Hoppscotch Chart

Relevant source files

The following files were used as context for generating this wiki page:

• charts/hoppscotch/Chart.yaml
• charts/hoppscotch/values.yaml
• charts/hoppscotch/templates/deployment.yaml
• charts/agh3/Chart.yaml
• charts/agh2/templates/captain/captain-deployment.yml

The Hoppscotch Helm chart is designed to deploy the Hoppscotch API development ecosystem services onto a Kubernetes cluster. It simplifies the management of a Hoppscotch instance by packaging the application and its required dependencies into a single, configurable chart.

The chart deploys an all-in-one (AIO) Hoppscotch instance and includes a dependency on the Bitnami PostgreSQL chart to provide a database backend. This allows for a complete, self-contained Hoppscotch installation with persistent data storage.

Sources: charts/hoppscotch/Chart.yaml, charts/hoppscotch/templates/deployment.yaml

Architecture

The chart deploys a few key Kubernetes resources to run Hoppscotch. The primary component is a single Kubernetes Deployment that manages an "all-in-one" pod. This pod contains the main Hoppscotch application container and an init container for database setup. The chart also manages a PostgreSQL database via a chart dependency and can create an Ingress resource to expose the application to external traffic.

The following diagram illustrates the high-level architecture of the deployed services.

Deployment Configuration

The core of the chart is the deployment.yaml template, which defines an apps/v1/Deployment for the Hoppscotch application.

Sources: charts/hoppscotch/templates/deployment.yaml

Pod Specification

The deployment manages a single replica of a pod labeled app: {{ .Release.Name }}-aio. This pod has a specific security context and contains one init container and one main application container.

• Security Context: The pod is configured with net.ipv4.ip_unprivileged_port_start set to 0, allowing services inside the container to bind to privileged ports.
• Containers:
  1. init-db (Init Container): Prepares the database before the main application starts.
  2. hoppscotch-aio (Main Container): Runs the Hoppscotch application.

Sources: charts/hoppscotch/templates/deployment.yaml:4-13, 14-31, 32-79

Database Initialization

Before the main Hoppscotch application can start, the init-db container runs to ensure the database schema is up to date.

• Image: It uses the same Hoppscotch image as the main application.
• Command: It executes pnpx prisma migrate deploy to apply any pending database migrations.
• Environment: It receives the DATABASE_URL environment variable, constructed from PostgreSQL credentials, to connect to the database.

This process ensures that the application always starts with a compatible database schema.

The following diagram shows the pod startup sequence.

Environment and Secrets

The hoppscotch-aio container is configured with several environment variables, which are critical for its operation. These are sourced from values.yaml and Kubernetes Secrets.

• Database URL: The DATABASE_URL is constructed using the username, password, service host, and database name for the PostgreSQL instance. The password is retrieved from the secret created by the PostgreSQL sub-chart.
• Authentication Secrets: Sensitive values like JWT_SECRET, SESSION_SECRET, MAILER_SMTP_PASSWORD, and DATA_ENCRYPTION_KEY are sourced from a Kubernetes Secret. By default, this secret is named {{ .Release.Name }}-secrets.
• Application Environment: Other configuration options are passed as environment variables directly from the hoppscotch.env section of the values.yaml file.

Sources: charts/hoppscotch/templates/deployment.yaml:54-76, charts/hoppscotch/values.yaml:23-70

Health Probes

The deployment includes readiness and liveness probes to ensure the pod is healthy.

• Readiness Probe: Checks http://<pod-ip>:3000/ to determine if the application is ready to accept traffic.
• Liveness Probe: Checks http://<pod-ip>:3000/ to determine if the application is still running. If this probe fails, the container is restarted.

Sources: charts/hoppscotch/templates/deployment.yaml:45-53

Configuration Parameters

The chart's behavior is controlled through the values.yaml file. The main sections are detailed below.

Sources: charts/hoppscotch/values.yaml

PostgreSQL Configuration (postgresql)

This section configures the PostgreSQL dependency.

Parameter	Description	Default Value
enabled	If true, deploys the PostgreSQL sub-chart.	true
global.postgresql.auth.username	The username for the Hoppscotch database user.	"hoppscotch"
global.postgresql.auth.password	The password for the Hoppscotch database user.	"your-hoppscotch-password"
global.postgresql.auth.database	The name of the database to create.	"hoppscotch"
global.postgresql.auth.existingSecret	Name of an existing secret for PostgreSQL credentials.	""
primary.persistence.enabled	If true, enables persistent storage for PostgreSQL.	false
primary.persistence.size	The size of the persistent volume.	8Gi

Sources: charts/hoppscotch/values.yaml:2-19

Hoppscotch Application Configuration (hoppscotch)

This section configures the Hoppscotch application container.

Parameter	Description	Default Value
image.repository	The container image repository.	hoppscotch/hoppscotch
image.tag	The container image tag.	2024.9.1
image.pullPolicy	The image pull policy.	IfNotPresent
auth.JWT_SECRET	Default JWT secret if not using existingSecret.	"secret1233"
auth.SESSION_SECRET	Default session secret.	"add some secret here"
auth.DATA_ENCRYPTION_KEY	Default data encryption key (must be 32 chars).	"data encryption key with 32 char"
auth.existingSecret	Name of an existing secret for Hoppscotch auth values.	""
env	A map of environment variables for the application.	See values.yaml
ports	Port mappings for the container.	3000, 3100, 3170, 80

Sources: charts/hoppscotch/values.yaml:21-79

Ingress Configuration (ingress)

This section configures the Ingress resource to expose the Hoppscotch service.

Parameter	Description	Default Value
enabled	If true, creates an Ingress resource.	true
hostname	The hostname for the Ingress rule.	"hoppscotch.test.com"
annotations	Annotations to add to the Ingress resource.	{}
path	The path for the Ingress rule.	/
tls.enabled	If true, enables TLS configuration for the Ingress.	true
tls.secretName	The name of the secret containing the TLS certificate.	hoppscotch-tls

Sources: charts/hoppscotch/values.yaml:81-87

Dependencies

The Hoppscotch chart relies on other charts to function. Its primary dependency is declared in Chart.yaml.

• postgresql: The chart depends on the postgresql chart from the Bitnami repository (https://charts.bitnami.com/bitnami) at version 16.0.1. This dependency is not conditional and will always be installed alongside the Hoppscotch chart.

This is a simpler dependency model compared to other charts in the repository, such as agh3, which uses conditional dependencies for multiple components like MinIO, RabbitMQ, and Redis.

Sources: charts/hoppscotch/Chart.yaml:6-9, charts/agh3/Chart.yaml:16-59