Infrastructure Setup¶

This document explains how to set up the infrastructure for hosting txpark documentation and install script.

Kubernetes Deployment (Recommended)¶

The documentation and install script are hosted in a pod within the GKE cluster. This approach provides:

HTTPS via cluster ingress
Simple deployment workflow
No external dependencies
Consistent with other cluster services

Quick Setup¶

# 1. Set up Python venv for building docs
python -m venv .venv
source .venv/bin/activate
pip install mkdocs-material

# 2. Build, push, and deploy
make doc-deploy

This single command will:

Build the MkDocs documentation
Build a Docker image with nginx, docs, and install script
Push the image to the container registry
Deploy to the cluster using Helm

Accessing Content¶

Content is accessible via the cluster ingress with HTTPS:

Documentation: https://doc.txpark.nomadic-labs.com/
Install script: https://doc.txpark.nomadic-labs.com/install.sh

DNS Configuration¶

Configure an A record in your DNS provider:

doc.txpark.nomadic-labs.com     A  <cluster-ingress-ip>

Get the ingress IP:

kubectl get ingress -n txpark-system txpark-docs

For more details, see the Helm chart documentation at helm/txpark-docs/README.md.

Manual Setup (Alternative)¶

If you prefer to set up the infrastructure manually or need to understand what the Terraform module creates, follow the steps below.

Prerequisites¶

Access to GCP project nl-tezos-x-alpha-infra
gcloud CLI configured with appropriate permissions
DNS access to configure nomadic-labs.com domain

Google Cloud Storage Buckets¶

The following GCS buckets need to be created and configured for static website hosting:

1. txpark.nomadic-labs.com¶

This bucket hosts the install script.

# Create bucket
gsutil mb -p nl-tezos-x-alpha-infra \
  -c STANDARD \
  -l europe-west1 \
  gs://txpark.nomadic-labs.com

# Configure for static website hosting
gsutil web set -m index.html -e 404.html gs://txpark.nomadic-labs.com

# Make bucket publicly readable
gsutil iam ch allUsers:objectViewer gs://txpark.nomadic-labs.com

# Set CORS for install script
cat > cors.json <<EOF
[
  {
    "origin": ["*"],
    "method": ["GET"],
    "responseHeader": ["Content-Type"],
    "maxAgeSeconds": 3600
  }
]
EOF
gsutil cors set cors.json gs://txpark.nomadic-labs.com

2. doc.txpark.nomadic-labs.com¶

This bucket hosts the MkDocs documentation site.

# Create bucket
gsutil mb -p nl-tezos-x-alpha-infra \
  -c STANDARD \
  -l europe-west1 \
  gs://doc.txpark.nomadic-labs.com

# Configure for static website hosting
gsutil web set -m index.html -e 404.html gs://doc.txpark.nomadic-labs.com

# Make bucket publicly readable
gsutil iam ch allUsers:objectViewer gs://doc.txpark.nomadic-labs.com

DNS Configuration¶

Configure DNS records to point to the GCS buckets:

# CNAME records (assuming Cloud Load Balancer is configured)
txpark.nomadic-labs.com     CNAME  c.storage.googleapis.com
doc.txpark.nomadic-labs.com CNAME  c.storage.googleapis.com

Alternative: Using Google Cloud Load Balancer with SSL

For HTTPS support, set up a load balancer:

Reserve a static IP address
Create backend buckets pointing to the GCS buckets
Create URL map routing to backend buckets
Create HTTPS target proxy with SSL certificate
Create forwarding rule
Point DNS A records to the static IP

See: https://cloud.google.com/storage/docs/hosting-static-website

GitLab CI/CD Variables¶

Add the following CI/CD variable in GitLab project settings:

Variable name: GCP_SERVICE_ACCOUNT_KEY Type: File Protected: Yes Masked: No (it's a JSON file, can't be masked)

Value: JSON key file for a GCP service account with permissions: - Storage Object Admin on both buckets - Storage Bucket Get on both buckets

Creating the Service Account¶

# Create service account
gcloud iam service-accounts create txpark-ci-deployer \
  --display-name="TxPark CI/CD Deployer" \
  --project=nl-tezos-x-alpha-infra

# Grant permissions on txpark.nomadic-labs.com bucket
gsutil iam ch \
  serviceAccount:txpark-ci-deployer@nl-tezos-x-alpha-infra.iam.gserviceaccount.com:objectAdmin \
  gs://txpark.nomadic-labs.com

# Grant permissions on doc.txpark.nomadic-labs.com bucket
gsutil iam ch \
  serviceAccount:txpark-ci-deployer@nl-tezos-x-alpha-infra.iam.gserviceaccount.com:objectAdmin \
  gs://doc.txpark.nomadic-labs.com

# Create and download key
gcloud iam service-accounts keys create txpark-ci-key.json \
  --iam-account=txpark-ci-deployer@nl-tezos-x-alpha-infra.iam.gserviceaccount.com

# Copy the contents of txpark-ci-key.json to GitLab CI/CD variable
cat txpark-ci-key.json

SSL Certificates¶

For HTTPS access, configure SSL certificates:

Option 1: Let's Encrypt with Cloud Load Balancer¶

Use Google-managed SSL certificates through Cloud Load Balancer.

Option 2: Cloud CDN¶

Enable Cloud CDN on the load balancer for better performance and global distribution.

Verification¶

After deploying, verify the content is accessible:

# Test install script
curl -I https://doc.txpark.nomadic-labs.com/install.sh

# Test documentation site
curl -I https://doc.txpark.nomadic-labs.com/

Troubleshooting¶

Deployment fails with "Access Denied"¶

Check that: - Your gcloud credentials are active: gcloud auth list - You have write permissions to the GCS buckets - Bucket names match exactly

install.sh returns 404¶

Check that: - File was uploaded successfully: gsutil ls gs://txpark.nomadic-labs.com/install.sh - Bucket IAM allows public read access

Documentation site shows "AccessDenied"¶

Check that: - Bucket IAM allows allUsers:objectViewer - All files in site/ directory were uploaded - index.html exists in the root

Maintenance¶

Update install script¶

Edit install.sh and deploy manually:

gsutil cp install.sh gs://txpark.nomadic-labs.com/install.sh

Update documentation¶

Edit files in docs/ directory or mkdocs.yml, then build and deploy:

mkdocs build
gsutil -m rsync -r -d site/ gs://doc.txpark.nomadic-labs.com/

Cost Estimation¶

GCS storage: ~$0.02/GB/month (Standard class, Europe)
Network egress: ~$0.12/GB (within Europe), $0.23/GB (intercontinental)
Operations: Minimal cost for GET requests

Expected monthly cost for typical usage: < $5/month

Security Considerations¶

Buckets are publicly readable (required for static hosting)
No sensitive data should be stored in these buckets
CORS configured to allow install script downloads from any origin
Content served over HTTPS via storage.googleapis.com