Skip to main content

​
Prerequisites

  • A deployed CVM on Phala Cloud
  • Docker image with gRPC service
  • gRPC client tools for testing
This guide shows you how to deploy gRPC services with native HTTP/2 support and automatic TLS encryption.

​
How gRPC Works Through the Gateway

gRPC services get special HTTP/2 treatment:
  1. Add a g suffix to your port: <app-id>-<port>g.<cluster>.phala.network
  2. Gateway detects the g suffix and enables HTTP/2 via ALPN negotiation
  3. gRPC traffic flows over HTTP/2 with automatic TLS termination
  4. Your service handles standard gRPC calls without TLS configuration
Note: The g suffix enables HTTP/2 for any service, not just gRPC. You can use it for any HTTP/2-compatible application that benefits from multiplexing, server push, or header compression.

​
Deploy Your gRPC Service

services:
  grpc-server:
    image: your-grpc-service:latest
    ports:
      - "50051:50051"  # Standard gRPC port
    environment:
      GRPC_PORT: 50051
      # No TLS config needed - gateway handles it
Access your gRPC service at: <app-id>-50051g.dstack-prod5.phala.network:443 Note the g suffix - this tells the gateway to enable HTTP/2.

​
Connect from Clients

// Go client
conn, err := grpc.Dial(
    "<app-id>-50051g.dstack-prod5.phala.network:443",
    grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{
        ServerName: "<app-id>-50051g.dstack-prod5.phala.network",
    })),
)

​
gRPC with Custom Domains

Use dstack-ingress for custom domains: 
services:
  dstack-ingress:
    image: dstacktee/dstack-ingress:2.2@sha256:d05a7b343c37c1cca1bba8dbf7e8f3c6d2118158af2d41c455103796db4f67f0
    ports:
      - "443:443"
    environment:
      - DOMAIN=api.mycompany.com
      - TARGET_ENDPOINT=grpc-server:50051
      - ALPN=h2  # Allow gRPC clients to negotiate HTTP/2
      - CLOUDFLARE_API_TOKEN=${CLOUDFLARE_API_TOKEN}
      - GATEWAY_DOMAIN=_.${DSTACK_GATEWAY_DOMAIN}
      - CERTBOT_EMAIL=${CERTBOT_EMAIL}
    volumes:
      - /var/run/dstack.sock:/var/run/dstack.sock
      - /var/run/tappd.sock:/var/run/tappd.sock
      - cert-data:/etc/letsencrypt
      - evidences:/evidences

  grpc-server:
    image: your-grpc-service:latest

volumes:
  cert-data:
  evidences:
Then connect to: api.mycompany.com. Learn more details at Set up custom domains. dstack-ingress terminates TLS and forwards raw TCP to the backend. For gRPC custom domains, set ALPN=h2 so clients can negotiate HTTP/2 over TLS; your backend should accept cleartext HTTP/2 on TARGET_ENDPOINT.

​
Testing with grpcurl

# List services
grpcurl <app-id>-50051g.dstack-prod5.phala.network:443 list

# Call a method
grpcurl -d '{"name": "world"}' \
    <app-id>-50051g.dstack-prod5.phala.network:443 \
    your.service.v1.YourService/SayHello

​
Key Differences

gRPC (with g suffix):
  • Native HTTP/2 with ALPN negotiation
  • Optimal performance for gRPC protocols
  • Proper streaming support
Regular HTTP:
  • Standard HTTP/1.1 or HTTP/2
  • Best for REST APIs and web applications
  • No gRPC-specific optimizations

​
Internal vs External

services:
  grpc-client:
    environment:
      GRPC_SERVER: grpc-server:50051  # Internal: direct connection
      
  grpc-server:
    ports:
      - "50051:50051"  # External: HTTP/2 via gateway

​
Troubleshooting

No HTTP/2 negotiation? Use the g suffix and verify ALPN support. Connection refused? Check port mapping and service status. TLS errors? Connect to port 443 with correct hostname.

​
Next Steps