Skip to main content

Kubernetes

This guide provides instructions for deploying Hook0 on a Kubernetes cluster using a deployments.yaml file.

Development Only

This configuration is intended for development and testing purposes only, not for production use.

This setup does not address production concerns such as:

  • Scalability - handling increased load and traffic
  • Resilience - fault tolerance and recovery
  • High availability - minimizing downtime
  • Observability - monitoring, logging, and alerting
  • 24/7 operations - on-call support and incident management
  • Security - the ready-made deployment files turn off webhook target address checking, and the Docker Compose file loosens two more guards

The Docker Compose file, the Kubernetes deployments.yaml and the Helm chart all set DISABLE_TARGET_IP_CHECK to true. That switches off the check which refuses a webhook target whose address is not globally reachable, and it is what lets a local stack deliver to localhost. It also lets a webhook from these deployments reach anything else the worker can reach on your network. On any deployment that accepts subscriptions you do not control, leave the flag at its default of false.

The Docker Compose file sets two more values that belong to a development stack alone:

  • REVERSE_PROXY_IPS holds 172.16.0.1/32, the address of this stack's own bridge gateway. A request that reaches a published port from the host arrives as that gateway rather than as the caller, and this setting tells the API to read the caller's address out of a proxy header instead. It is held to one address on purpose, since the gateway is the only address on the network that no container can be given, and anything wider would cover every sibling container and whatever an operator adds to the network next. Set it to the address of your own reverse proxy, and to nothing wider.
  • API_RATE_LIMITING_EMAIL_BURST_SIZE is raised from 5 to 20, the headroom the browser-driven end-to-end tests need. That quota is what bounds an address-enumeration sweep against the endpoints that send an email to an address the caller names, so a deployment that keeps the raised value hands an attacker four times the sweep for free.

The two interact, and the first one decides how much the second is worth. A quota keyed on the caller's IP bounds a sweep only while the caller is stuck with one address, and anyone the trusted range covers can pick a fresh one per request. Here that is every process on the host, which is what a development stack is for. Widen the range in a real deployment and you take the per-IP bound off the mail-sending endpoints altogether, whatever the burst size says. The per-account cooldown and daily allowance held in the database survive either way, but they bound what a single mailbox receives and see nothing of a sweep across many addresses. See Security for what each limiter covers.

For production workloads, use Hook0 Cloud which provides a fully managed, production-ready infrastructure.

Prerequisites​

  • A functioning Kubernetes cluster
  • kubectl tool access
  • Persistent storage capacity for PostgreSQL and Mailpit services

Core Components​

The deployment establishes five main services:

  • API endpoint
  • Frontend interface
  • Mailpit for email management
  • PostgreSQL database
  • Output Worker for webhook processing

Deployment Process​

1. Namespace Creation​

First, create a dedicated hook0 namespace:

kubectl create namespace hook0

2. Service Deployment​

Apply the complete YAML configuration file:

kubectl apply -f deployments.yaml -n hook0

3. Verification​

Confirm all pods reach "Running" state:

kubectl get pods -n hook0

Troubleshoot failures with pod descriptions:

kubectl describe pod <pod-name> -n hook0

4. Service Access​

Retrieve external IPs or NodePorts:

kubectl get services -n hook0

5. Storage Management​

PVCs automatically handle data persistence, with default 100Mi allocations per service.

6. Configuration Customization​

Modify environment variables like DATABASE_URL and APP_URL as needed in the deployment files.

7. Troubleshooting​

Common issues to address:

  • Image availability
  • Storage class compatibility
  • Network access configuration

Cleanup​

To delete the Hook0 deployment:

kubectl delete namespace hook0

This removes all associated cluster resources.