How to set up your HQ

Hosted
Self-hosted

The simplest way to use Open Politics is through our hosted platform:

Register at open-politics.org
Log in at open-politics.org/
Begin using the platform with pre-loaded data and continue to:

App Setup

Configure your API keys and providers

Our preferred way to self-host on a single machine or develop with is Docker Compose. For Multi-machine setups, we recommend Kubernetes.But in both the cases you can choose to outsource services to managed providers for a more lightweight (but less private) setup.

Service	Purpose	Example Provider
Postgres	Main database	Hetzner
Redis	Cache and queue	Upstash
MinIO / S3	Object storage	Hetzner
Nominatim	Geocoding	Nominatim	- uses lot of disk space (170gb+)
LLM API	Language model	OpenAI	- high gpu and/or cpu usage
Tavily / SerpAPI	Web search	Tavily

Docker Compose
Kubernetes

Run the complete platform locally:

Prerequisites

Docker and Docker Compose
32GB RAM recommended
20GB free disk space
Git

Clone repository

git clone https://github.com/open-politics/open-politics-hq.git
cd open-politics-hq

Configure environment

cp .env.example .env
# Edit .env with your configuration
# All values with changeThis need to be changed before the app will start.
# for example with 'openssl rand -base64 14' in your terminal.

Start services

docker compose up

Access the platform

Open your browser and navigate to:

http://localhost:3000

Initial setup may take time depending on your system configuration.

If you are here, we assume you know what you are doing.

Base Helm Chart

We have a base helm chart available here

git clone https://github.com/open-politics/open-politics-hq
cd .deployments/end-to-end-hetzner-k3s-terraform-helm/open-politics-hq-deployment/hq-cluster-chart
cp values.example.yaml values.yaml
# Edit values.yaml with your configuration

Hetzner Kubernetes Stack

Our easiest way to deploy HQ via Kubernetes is to use Hetzner. We provide an end-to-end script that provisions a master and worker nodes via Terraform and installs K3s. We suggest using K9s alongside our scripts to manage and scale the cluster.

Hetzner Kubernetes Stack

HQ on Hetzner (K3s) — End-to-End Deployment Guide

This repository delivers a batteries-included, reproducible way to provision a Hetzner K3s cluster and deploy your application stack with one command.

What This Gives You

3 Hetzner Cloud servers by default: 1 control plane, 2 workers (configurable)
K3s with sensible flags for Hetzner CCM integration
Traefik Ingress with automatic TLS via Let’s Encrypt (ACME)
Persistent storage using Hetzner CSI
Application stack via Helm: frontend, backend API, Celery workers, Redis, optional Postgres/MinIO templates

Quick Start

Configure Hetzner token

cd .deployments/end-to-end-hetzner-k3s-terraform-helm/open-politics-hq-deployment/
cp .tfvars.example .tfvars
cp hq-cluster-chart/values.example.yaml hq-cluster-chart/values.yaml
# Edit .tfvars and values.yaml with your configuration (see below)

Deploy

./deploy.sh

The script is idempotent. Re-running applies updates safely. Typical first deploy time: ~10–15 minutes.

Configuration Checklist

Before running ./deploy.sh, ensure you’ve completed:

Hetzner API Token: Set hcloud_token in .tfvars
Domain: Set domain in .tfvars (must match env.config.DOMAIN in values.yaml)
Application Values: Copy and customize hq-cluster-chart/values.yaml
Secrets: Replace all xxx placeholders with real values
SSH Keys: Run ./scripts/manage-ssh-keys.sh generate
DNS Ready: Have your domain ready for A record creation

Prerequisites

Hetzner Cloud account and API token (Read/Write)
Local tools: terraform, kubectl, helm, jq
An SSH key uploaded to Hetzner; the scripts can rotate/manage keys automatically

Initial Configuration

Infrastructure Configuration (.tfvars)

cp .tfvars.example .tfvars

Required:

hcloud_token: Hetzner API token (get from console)
domain: your public domain for TLS/ingress

Optional (with defaults):

worker_count: number of workers (default: 2)
master_server_type / worker_server_type: server types (default: cx22)
location: Hetzner location (default: fsn1)
cluster_slug: resource naming prefix (default: hq)

Application Configuration (values.yaml)

cp hq-cluster-chart/values.example.yaml hq-cluster-chart/values.yaml

Required customizations:

email: admin email for Let’s Encrypt
env.config.DOMAIN: your domain (must match .tfvars)
env.config.BACKEND_CORS_ORIGINS: update with your domain
Docker image repositories for backend, frontend, and celery-worker

Secrets (replace all xxx placeholders):

SECRET_KEY, FIRST_SUPERUSER_PASSWORD, POSTGRES_PASSWORD
MINIO_ROOT_PASSWORD, MINIO_SECRET_KEY
SMTP_USER, SMTP_PASSWORD, EMAILS_FROM_EMAIL
API keys: OPENAI_API_KEY, TAVILY_API_KEY, GOOGLE_API_KEY, MAPBOX_ACCESS_TOKEN

SSH Key Management

./scripts/manage-ssh-keys.sh generate

This generates key pairs, uploads to Hetzner, and updates cloud-init templates.Manual alternative: Upload your SSH key to Hetzner Console and set ssh_key_name in .tfvars.

DNS Preparation

Have your domain ready. After deployment, create A records pointing to the Load Balancer IP for both your-domain.com and www.your-domain.com.

How It Works

The ./deploy.sh orchestrator performs two phases:

Provision infrastructure: Terraform creates network, firewall, servers; cloud-init installs K3s
Deploy stack: Configures Traefik, installs Hetzner CCM/CSI, deploys the Helm chart

Core commands:

Command	Description
`./deploy.sh`	Full deploy (infra → app)
`./scripts/connect.sh`	Fetch kubeconfig and set kubectl context
`./scripts/status.sh`	Summary of nodes, services, ingress, PVs
`./scripts/logs.sh`	Tail app logs
`./scripts/monitor.sh`	Open k9s
`./scripts/destroy.sh`	Tear everything down

DNS and TLS

Get Load Balancer IP

kubectl get svc traefik -n kube-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

Create DNS A records

Point your domain (and www) to the Load Balancer IP. Traefik will obtain Let’s Encrypt certificates automatically (typically 2-5 minutes after DNS propagation).

Verify deployment

./scripts/test-deployment.sh  # Test DNS, HTTP/HTTPS, and TLS
./scripts/status.sh           # View pods, services, ingress
./scripts/check-ssl.sh        # Check ACME progress

Troubleshooting

Issue	Solution
Workers don’t schedule pods	CCM removes taints automatically; wait or remove manually
No Load Balancer IP	Confirm Traefik is `LoadBalancer` and CCM is Ready
Domain mismatch	Ensure `.tfvars` domain matches `values.yaml`
CORS errors	Verify `BACKEND_CORS_ORIGINS` includes your domain
ACME stuck	Verify DNS A records point to LB IP; run `./scripts/check-ssl.sh`
SSH failures	Run `./scripts/manage-ssh-keys.sh generate`

Cost

Default: 3× cx22 + 1 Load Balancer ≈ €40–45/month. Reduce costs by lowering worker_count or using smaller server types.

Project

Getting Started

Core Concepts

How To

Installation & Architecture

How to set up your HQ

App Setup

Base Helm Chart

Hetzner Kubernetes Stack

HQ on Hetzner (K3s) — End-to-End Deployment Guide

What This Gives You

Quick Start

Configuration Checklist

Prerequisites

Initial Configuration

How It Works

DNS and TLS

Troubleshooting

Cost

Project

Getting Started

Core Concepts

How To

Documentation Index

​How to set up your HQ

App Setup

​Base Helm Chart

​Hetzner Kubernetes Stack

​HQ on Hetzner (K3s) — End-to-End Deployment Guide

​What This Gives You

​Quick Start

​Configuration Checklist

​Prerequisites

​Initial Configuration

​How It Works

​DNS and TLS

​Troubleshooting

​Cost

How to set up your HQ

Base Helm Chart

Hetzner Kubernetes Stack

HQ on Hetzner (K3s) — End-to-End Deployment Guide

What This Gives You

Quick Start

Configuration Checklist

Prerequisites

Initial Configuration

How It Works

DNS and TLS

Troubleshooting

Cost