🔐 Production Deployment (Enabling HTTPS) & Documentation

[maryamv]

@s1monj @ryanlovett and Eric (don't know his GitHub handle)

As we continue refining our deployment setup for JupyterHealth Exchange (JHE), we should also tighten our production deployment documentation to reflect real-world production needs. To ensure proper security and compatibility — especially for OAuth2 + PKCE — we need to document how to serve Django securely behind HTTPS.

In our documentation site, we should provide examples in both Kubernetes-based and non-Kubernetes environments.

⚠️ Context

Modern browsers restrict use of sensitive cryptographic APIs (like Crypto.subtle) to secure contexts (HTTPS), with the one exception being development over localhost. Since Django does not support HTTPS directly, we’ll need to use a reverse proxy like nginx in front of Django to terminate HTTPS. This is a standard production deployment pattern, and it ensures that browser-based workflows (like OAuth2 + PKCE) function correctly and securely.

Recommended Non-Kubernetes Production Setup

1. Provision a Linux Server
2. Install and Configure PostgreSQL
3. Install the Application (JHE)
4. Run Database Migrations
5. Run Gunicorn Application Server
6. Configure systemd Service
7. Set Up Nginx as Reverse Proxy
8. Configure HTTPS with certbot
9. Set Up DNS
10. Test Deployment

Post-Deployment: Administering JHE

• Run Database Migrations
• Seed Initial Data
• Create a Django Admin User
• Configure OAuth Application
• Integrate JupyterHub Authentication
• Enable Group-Based Access

---

Recommended Kubernetes-Based Production Setup

(via AWS EKS, ingress-nginx, and cert-manager)

1. Create the Kubernetes Cluster
2. Install ingress-nginx with AWS NLB support
3. Install cert-manager for HTTPS
4. Deploy JupyterHealth Exchange
5. Set up DNS and expose JHE endpoint
6. Connect a PostgreSQL database

Post-Deployment: Administering JHE

• Migrate the database
• Seed initial data
• Configure OAuth client in Django Admin
• Integrate JupyterHub authentication
• Group-based access control

---

For Local Development

HTTPS is not required if you’re running on localhost. Modern browsers allow insecure HTTP access on localhost for development purposes.

If you're seeing Crypto.subtle errors on localhost, verify:

• You're using localhost, not a LAN IP or hostname
• You're not forcing HTTPS-only mode in the browser

---

[maryamv]

@ryanlovett -- Could you confirm this is correct?

Recommended Kubernetes-Based Production Setup

This documentation replaces the original deployment guide by Ryan Lovett and provides a more detailed, modular, and explanatory approach to deploying JupyterHealth Exchange (JHE) on Kubernetes using AWS EKS, ingress-nginx, and cert-manager.

This guide assumes you're starting from scratch and will:

• Provision a new EKS cluster
• Set up all necessary services and configurations
• Deploy JHE securely over HTTPS

✅ Goal: Make this guide accessible to all experience levels by explaining why each step is necessary and how it fits into a secure, scalable production setup.

💡 Note: If you're working with a pre-existing Kubernetes cluster, you can skip the cluster provisioning step and begin with the component installation.

---

Step 1: Create Kubernetes Cluster (via eksctl)

Kubernetes needs a cluster to run workloads — EKS (Elastic Kubernetes Service) is AWS's managed offering.

🔍 Why EKS? It's a production-grade, scalable, and secure option managed by AWS. eksctl simplifies provisioning.

Define the cluster configuration in a file called cluster.yml:

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: jhe-example
  region: us-east-2
  version: '1.30'

vpc:
  clusterEndpoints:
    publicAccess: true
    privateAccess: true
  nat:
    gateway: Single

nodeGroups:
  - name: public-nodes
    instanceType: t2.micro
    desiredCapacity: 2
    privateNetworking: false

managedNodeGroups:
  - name: system-nodes
    instanceType: t2.small
    privateNetworking: true
    minSize: 1
    maxSize: 3

📌 Tip: Choose instance types and sizes based on expected load. These can be scaled later.

Export AWS credentials as environment variables:

export AWS_SECRET_ACCESS_KEY=...
export AWS_ACCESS_KEY_ID=...
export AWS_DEFAULT_REGION=us-east-2

Create the cluster:

eksctl create cluster -f cluster.yml

🛠️ This may take 15–20 minutes.

---

Step 2: Install ingress-nginx (for HTTPS routing)

A reverse proxy (like ingress-nginx) routes incoming traffic to the right service and enables HTTPS.

🔐 Why ingress-nginx? It’s flexible, open-source, and supports AWS load balancers with TLS termination.

Prepare your values in a file named ingress-nginx.yml:

controller:
  service:
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-type: nlb
      service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true"
  config:
    use-forwarded-headers: "true"

Install ingress-nginx:

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
helm install nginx-ingress ingress-nginx/ingress-nginx -f ingress-nginx.yml

🧠 Did You Know? ingress-nginx sits at the edge of your infrastructure — all external web requests pass through it.

---

Step 3: Install cert-manager (for TLS/HTTPS)

This tool automates certificate provisioning and renewal via Let’s Encrypt or other issuers.

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.15.4 \
  --set crds.install=true \
  --set installCRDs=true \
  --wait

🔒 This is what makes HTTPS automatic and secure for your deployment.

---

Step 4: Deploy JupyterHealth Exchange

Prepare your Kubernetes manifests (e.g., jhe-example.yml). Ensure secrets (like DB passwords, Django settings) are injected securely.

📎 You can use Kubernetes Secrets, external secrets manager, or ConfigMaps depending on your setup.

Apply to the cluster:

kubectl apply -f jhe-example.yml

📌 Caution: Make sure your deployment references the correct domain, secret names, and container image.

---

Step 5: Register DNS

Find the public endpoint of your ingress controller:

kubectl get service nginx-ingress-ingress-nginx-controller -o jsonpath="{.status.loadBalancer.ingress[0].hostname}"

Use your DNS provider to create a CNAME record (e.g., jhe.yourdomain.org) pointing to the above hostname.

🌐 This allows your service to be reachable via a friendly domain name and secured via HTTPS.

---

Step 6: Create PostgreSQL Database (e.g., Amazon RDS)

Use AWS RDS to provision a PostgreSQL database that JHE will connect to. Typical configuration:

Parameter	Value
Engine	PostgreSQL 17.4
Multi-AZ	Yes (recommended)
DB instance class	db.t3.small
Storage type	General Purpose SSD (gp2)
Allocated storage	100 GiB
VPC	eksctl-jhe-example-cluster/VPC
Public access	No
Authentication	Password
Initial database name	jhe

🔐 Don’t forget to update your jhe-config Kubernetes secret with these credentials.

You can test connectivity from the cluster:

kubectl run postgres-test -it --rm --image=postgres:17.4 -- bash
psql -h <endpoint> -U postgres -d jhe

---

Post-Deployment: Administering JHE

After your app is deployed and DNS is set:

1. Run migrations:

kubectl exec -it <django-pod> -- python manage.py migrate

2. Seed initial data:

# Assuming seed.sql is mounted or baked into the container
kubectl exec -it <django-pod> -- python manage.py loaddata seed.sql

3. Create Django admin user:

kubectl exec -it <django-pod> -- python manage.py createsuperuser

4. Configure OAuth application in Django Admin
5. Integrate JupyterHub authentication (via OAuth2 + PKCE)
6. Set up group-based access controls

🧩 These are key to making JHE usable, secure, and multi-tenant-ready.

---

Notes on HTTPS and PKCE

Modern browsers restrict use of sensitive cryptographic APIs (like window.crypto.subtle) to HTTPS contexts. This impacts OAuth2 + PKCE.

Since Django doesn’t serve HTTPS directly, ingress-nginx (with cert-manager) is essential.

🚫 Never disable SECURE_CROSS_ORIGIN_OPENER_POLICY in production — this breaks PKCE and weakens browser security.

---

Local Development (for comparison)

• HTTPS is not required on localhost
• Use Django’s runserver for local testing
• Avoid production secrets in local setups

Troubleshooting local issues:

• Use localhost only (not LAN IPs)
• Disable browser HTTPS-only modes temporarily

---

Next Steps

For deploying in non-Kubernetes environments, see the companion guide: Non-Kubernetes Production Setup.

🧠 This modular design helps contributors and ops teams adopt JHE in any environment — cloud-native or not.

---

[ryanlovett]

@maryamv The original documentation was correct -- I developed it when I was deploying. It'd be easier/safer for me to validate smaller changes to the docs. Can you make a series of smaller PRs?

If you haven't changed any command sequences and are just elaborating on "why each step is necessary and how it fits into a secure, scalable production setup," then it should still be correct.