Google Cloud

Deploy Hyperterse on Google Cloud Platform using Cloud Run (recommended for serverless containers) or Google Kubernetes Engine (GKE). Cloud Run provides automatic scaling, SSL, and pay-per-use pricing.

These instructions are a work in progress. Please report any issues or suggestions to the GitHub repository.

Cloud Run (recommended)

Cloud Run is the simplest way to deploy Hyperterse on GCP. It provides serverless containers with automatic scaling and built-in HTTPS.

1. Export your Hyperterse bundle

   Create a deployment-ready bundle from your configuration:

   hyperterse export -f config.terse -o dist

   This creates a self-contained script in the dist/ directory. The script name matches your config file name (without the .terse extension).

2. Create a Dockerfile

   Create a Dockerfile in your project root:

   Dockerfile

   FROM alpine:3.19
   
   # Install bash and ca-certificates for HTTPS database connections
   RUN apk --no-cache add bash ca-certificates
   
   WORKDIR /app
   
   # Copy the exported script (replace 'config' with your actual script name)
   COPY dist/config /app/config
   
   # Make script executable
   RUN chmod +x /app/config
   
   EXPOSE 8080
   
   # Run the script
   CMD ["/app/config"]

   Note: Replace config with the actual name of your exported script (it matches your config filename without the .terse extension).

3. Set up GCP project

   Set your project ID and enable required APIs:

   # Set project
   gcloud config set project PROJECT_ID
   
   # Enable required APIs
   gcloud services enable run.googleapis.com
   gcloud services enable cloudbuild.googleapis.com
   gcloud services enable secretmanager.googleapis.com

   Replace PROJECT_ID with your GCP project ID.

4. Configure Docker authentication

   Authenticate Docker to push images to Google Container Registry:

   gcloud auth configure-docker

5. Build and push Docker image

   Build your image and push it to Google Container Registry:

   # Build the image
   docker build -t gcr.io/PROJECT_ID/hyperterse:latest .
   
   # Push to registry
   docker push gcr.io/PROJECT_ID/hyperterse:latest

   Alternatively, use Cloud Build:

   gcloud builds submit --tag gcr.io/PROJECT_ID/hyperterse:latest

6. Store database credentials in Secret Manager

   Store your database connection string securely:

   echo -n "postgresql://user:pass@host:5432/db" | \
     gcloud secrets create hyperterse-db --data-file=-

   Security best practice: Never hardcode credentials. Always use Secret Manager.

7. Grant Cloud Run access to secrets

   Grant your Cloud Run service account permission to access the secret:

   # Get project number
   PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
   
   # Grant secret accessor role
   gcloud secrets add-iam-policy-binding hyperterse-db \
     --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"

8. Deploy to Cloud Run

   Deploy your Hyperterse service:

   gcloud run deploy hyperterse \
     --image gcr.io/PROJECT_ID/hyperterse:latest \
     --platform managed \
     --region us-central1 \
     --port 8080 \
     --set-secrets DATABASE_URL=hyperterse-db:latest \
     --allow-unauthenticated \
     --memory 512Mi \
     --cpu 1

   This command:

   • Deploys your container to Cloud Run
   • Sets port 8080
   • Injects the database URL from Secret Manager
   • Makes the service publicly accessible
   • Allocates 512MB memory and 1 CPU

9. Get your service URL

   After deployment, Cloud Run provides a public URL:

   gcloud run services describe hyperterse \
     --platform managed \
     --region us-central1 \
     --format="value(status.url)"

   Your Hyperterse API will be available at https://<service-url>/query/<query-name>.

Cloud SQL integration

Connect Hyperterse to Cloud SQL for managed PostgreSQL or MySQL:

1. Create Cloud SQL instance

   Create a Cloud SQL database instance:

   # For PostgreSQL
   gcloud sql instances create hyperterse-db \
     --database-version=POSTGRES_14 \
     --tier=db-f1-micro \
     --region=us-central1
   
   # Create database
   gcloud sql databases create hyperterse --instance=hyperterse-db
   
   # Create user
   gcloud sql users create hyperterse-user \
     --instance=hyperterse-db \
     --password=YourSecurePassword

2. Enable Cloud SQL Admin API

   gcloud services enable sqladmin.googleapis.com

3. Connect Cloud Run to Cloud SQL

   Update your Cloud Run service to connect to Cloud SQL:

   gcloud run services update hyperterse \
     --add-cloudsql-instances PROJECT_ID:us-central1:hyperterse-db \
     --region us-central1

4. Update connection string

   Use Unix socket connection for Cloud SQL:

   # Update secret with socket connection
   echo -n "postgresql://hyperterse-user:YourSecurePassword@/hyperterse?host=/cloudsql/PROJECT_ID:us-central1:hyperterse-db" | \
     gcloud secrets versions add hyperterse-db --data-file=-

   The socket path format is /cloudsql/PROJECT_ID:REGION:INSTANCE_NAME.

Google Kubernetes Engine (GKE)

For Kubernetes deployments, see the Kubernetes deployment guide. To set up GKE:

1. Create GKE cluster

   gcloud container clusters create hyperterse-cluster \
     --num-nodes=3 \
     --region=us-central1 \
     --machine-type=e2-medium

2. Get cluster credentials

   gcloud container clusters get-credentials hyperterse-cluster \
     --region=us-central1

3. Deploy using Kubernetes manifests

   Follow the Kubernetes deployment guide to create deployment manifests and apply them:

   kubectl apply -f deployment.yaml
   kubectl apply -f service.yaml

Custom domain and SSL

Cloud Run automatically provides HTTPS. To use a custom domain:

1. Map custom domain

   gcloud run domain-mappings create \
     --service hyperterse \
     --domain api.example.com \
     --region us-central1

2. Update DNS

   Add the CNAME record provided by Cloud Run to your DNS provider.

3. SSL certificate

   Cloud Run automatically provisions and manages SSL certificates for your custom domain.

Scaling and performance

Automatic scaling: Cloud Run automatically scales based on incoming requests:

• Scales to zero when no traffic
• Scales up to handle traffic spikes
• Configure min/max instances:

gcloud run services update hyperterse \
  --min-instances=1 \
  --max-instances=10 \
  --region us-central1

Concurrency: Control how many requests each instance handles:

gcloud run services update hyperterse \
  --concurrency=80 \
  --region us-central1

Monitoring and logging

View logs:

gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=hyperterse" --limit 50

Monitor metrics: Use Cloud Console → Cloud Run → hyperterse → Metrics to view:

• Request count
• Latency
• Error rate
• Instance count

Cost optimization

• Use Cloud Run: Pay only for requests processed (scales to zero)
• Right-size resources: Start with minimal CPU/memory and scale up as needed
• Use Cloud SQL: Managed databases reduce operational overhead
• Set max instances: Prevent runaway costs during traffic spikes

Troubleshooting

Service won’t start: Check logs using gcloud logging read. Common issues include incorrect DATABASE_URL or missing secret permissions.

Can’t connect to Cloud SQL: Verify Cloud SQL connection is added to the service and that the connection string uses the socket path format.

High latency: Consider increasing CPU allocation or using a region closer to your users.