Azure

Deploy Hyperterse on Microsoft Azure using Azure Container Apps (recommended) or Azure Kubernetes Service (AKS). Container Apps provides the simplest serverless container experience, while AKS offers full Kubernetes control.

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

Azure Container Apps Recommended

Azure Container Apps is the simplest way to deploy Hyperterse on Azure. 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. Create resource group

   Create a resource group to organize your Azure resources:

   az group create --name hyperterse-rg --location eastus

   Choose a location close to your users for better performance.

4. Create Azure Container Registry

   Create a private container registry to store your Docker images:

   az acr create \
     --name hyperterseregistry \
     --resource-group hyperterse-rg \
     --sku Basic \
     --admin-enabled true

   The Basic SKU is sufficient for most deployments. Enable admin user for easier authentication.

5. Authenticate Docker with Azure Container Registry

   Log in to your registry:

   az acr login --name hyperterseregistry

   Alternatively, use admin credentials:

   az acr credential show --name hyperterseregistry --query "passwords[0].value" -o tsv | \
     docker login hyperterseregistry.azurecr.io -u hyperterseregistry --password-stdin

6. Build and push Docker image

   Build your image and push it to the registry:

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

7. Create Azure Key Vault

   Store your database credentials securely in Azure Key Vault:

   # Create key vault
   az keyvault create \
     --name hyperterse-vault \
     --resource-group hyperterse-rg \
     --location eastus
   
   # Add database connection string as secret
   az keyvault secret set \
     --vault-name hyperterse-vault \
     --name DATABASE-URL \
     --value "postgresql://user:pass@host:5432/db"

   Security best practice: Never hardcode credentials. Always use Key Vault or environment variables.

8. Create Container Apps environment

   Create an environment for your container apps:

   az containerapp env create \
     --name hyperterse-env \
     --resource-group hyperterse-rg \
     --location eastus

9. Create Container App

   Deploy your Hyperterse app:

   az containerapp create \
     --name hyperterse \
     --resource-group hyperterse-rg \
     --environment hyperterse-env \
     --image hyperterseregistry.azurecr.io/hyperterse:latest \
     --target-port 8080 \
     --ingress external \
     --registry-server hyperterseregistry.azurecr.io \
     --secrets database-url=keyvault:hyperterse-vault/DATABASE-URL \
     --env-vars DATABASE_URL=secretref:database-url \
     --cpu 0.5 \
     --memory 1.0Gi

   This command:

   • Creates a container app named hyperterse
   • Uses your image from the registry
   • Exposes port 8080 with external ingress (public HTTPS)
   • Pulls the database URL from Key Vault
   • Sets CPU and memory limits

10. Get your app URL

    Retrieve your app’s public URL:

    az containerapp show \
      --name hyperterse \
      --resource-group hyperterse-rg \
      --query "properties.configuration.ingress.fqdn" \
      -o tsv

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

Azure Database integration

Connect Hyperterse to Azure Database for PostgreSQL or MySQL:

1. Create Azure Database instance

   Create a managed database instance:

   # For PostgreSQL
   az postgres flexible-server create \
     --resource-group hyperterse-rg \
     --name hyperterse-db \
     --location eastus \
     --admin-user adminuser \
     --admin-password YourSecurePassword \
     --sku-name Standard_B1ms \
     --tier Burstable \
     --version 14
   
   # For MySQL
   az mysql flexible-server create \
     --resource-group hyperterse-rg \
     --name hyperterse-db \
     --location eastus \
     --admin-user adminuser \
     --admin-password YourSecurePassword \
     --sku-name Standard_B1ms \
     --tier Burstable \
     --version 8.0.21

2. Configure firewall rules

   Allow Container Apps to access the database:

   # Get Container Apps outbound IPs (or use 0.0.0.0/0 for testing)
   az postgres flexible-server firewall-rule create \
     --resource-group hyperterse-rg \
     --name hyperterse-db \
     --rule-name AllowContainerApps \
     --start-ip-address 0.0.0.0 \
     --end-ip-address 255.255.255.255

   Production: Use private endpoints and VNet integration instead of public firewall rules.

3. Update Key Vault secret

   Update your database connection string with the Azure Database endpoint:

   az keyvault secret set \
     --vault-name hyperterse-vault \
     --name DATABASE-URL \
     --value "postgresql://adminuser:YourSecurePassword@hyperterse-db.postgres.database.azure.com:5432/postgres"

Azure Kubernetes Service (AKS)

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

1. Create AKS cluster

   az aks create \
     --resource-group hyperterse-rg \
     --name hyperterse-cluster \
     --node-count 3 \
     --enable-managed-identity \
     --generate-ssh-keys

2. Get cluster credentials

   az aks get-credentials \
     --resource-group hyperterse-rg \
     --name hyperterse-cluster

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

Scaling and monitoring

Auto-scaling: Container Apps automatically scales based on HTTP traffic. Configure scaling rules:

az containerapp update \
  --name hyperterse \
  --resource-group hyperterse-rg \
  --min-replicas 1 \
  --max-replicas 10

Monitoring: View logs and metrics in the Azure Portal or using Azure CLI:

az containerapp logs show \
  --name hyperterse \
  --resource-group hyperterse-rg \
  --follow

Troubleshooting

Container won’t start: Check logs using az containerapp logs show. Common issues include incorrect DATABASE_URL or registry authentication problems.

Can’t connect to database: Verify firewall rules allow traffic from Container Apps, and that the connection string is correct in Key Vault.

Image pull errors: Ensure your Container App has proper registry credentials configured.