Deploy on AWS ECS

This guide covers deploying the Hiya Voice Verification engine on Amazon Elastic Container Service (ECS). ECS supports both Fargate (serverless) and EC2 launch types.

Prerequisites

An ECS cluster configured with either Fargate or EC2 capacity
Container image pulled and authenticated — see Getting the Container Image
A valid API_KEY from your Hiya account team
AWS CLI installed and configured

Fargate vs EC2 Launch Type

	Fargate	EC2
Infrastructure management	Fully managed by AWS	You manage the instances
tmpfs support	Limited — use `ephemeralStorage`	Full tmpfs support
Instance type control	No	Yes — use Emerald Rapids instances
Best for	Simpler operations	Performance-optimized deployments

For production workloads where ML inference performance is critical, we recommend the EC2 launch type with Intel Emerald Rapids instances (e.g., i7i, m7i families). See AWS EKS for the full instance recommendation table.

Step 1 — Store Credentials in AWS Secrets Manager

Store the registry credentials and API key:

# Store the registry key for image pulls
aws secretsmanager create-secret \
  --name hiya/registry-key \
  --secret-string file://key.json

# Store the runtime API key
aws secretsmanager create-secret \
  --name hiya/api-key \
  --secret-string '<your-api-key>'

Step 2 — Create a Task Definition

{
  "family": "hiya-voice-verification",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "4096",
  "memory": "8192",
  "ephemeralStorage": {
    "sizeInGiB": 30
  },
  "executionRoleArn": "<your-execution-role-arn>",
  "taskRoleArn": "<your-task-role-arn>",
  "containerDefinitions": [
    {
      "name": "hiya-voice-verification",
      "image": "europe-docker.pkg.dev/loccus-platform/onpremise-images/engine-api-standalone:<version>",
      "essential": true,
      "portMappings": [
        {
          "containerPort": 8080,
          "protocol": "tcp"
        },
        {
          "containerPort": 8081,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {
          "name": "API_KEY",
          "value": "<your-api-key>"
        }
      ],
      "linuxParameters": {
        "tmpfs": [
          {
            "containerPath": "/opt/loccus/models",
            "size": 4096,
            "mountOptions": ["rw", "noexec", "nosuid"]
          }
        ]
      },
      "healthCheck": {
        "command": ["CMD-SHELL", "grpcurl -plaintext localhost:8080 grpc.health.v1.Health/Check || exit 1"],
        "interval": 10,
        "timeout": 5,
        "retries": 3,
        "startPeriod": 30
      },
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/hiya-voice-verification",
          "awslogs-region": "<your-region>",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}

The tmpfs option under linuxParameters is only available with the EC2 launch type. For Fargate, models are loaded into the container's writable layer backed by ephemeralStorage, which is not persisted beyond the task lifecycle.

aws ecs register-task-definition --cli-input-json file://task-definition.json

Step 3 — Configure Registry Authentication

To pull from Google Artifact Registry, configure a private registry authentication secret in your task execution role. Create a Secrets Manager secret with the registry credentials:

aws secretsmanager create-secret \
  --name hiya/docker-registry \
  --secret-string '{"username":"_json_key","password":"<contents-of-key.json>"}'

Then reference it in the task definition's repositoryCredentials:

{
  "containerDefinitions": [
    {
      "name": "hiya-voice-verification",
      "repositoryCredentials": {
        "credentialsParameter": "arn:aws:secretsmanager:<region>:<account-id>:secret:hiya/docker-registry"
      }
    }
  ]
}

Ensure your task execution role has secretsmanager:GetSecretValue permission for this secret.

Step 4 — Create the Service

aws ecs create-service \
  --cluster <your-cluster> \
  --service-name hiya-voice-verification \
  --task-definition hiya-voice-verification \
  --desired-count 1 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[<subnet-ids>],securityGroups=[<sg-id>],assignPublicIp=DISABLED}"

Network Configuration

The ECS tasks need outbound access to:

Destination	Port	Protocol	Purpose
`europe-docker.pkg.dev`	443	HTTPS	Image pulls (via NAT Gateway or VPC endpoint)
`api.hiya.com`	443	HTTPS	License verification and billing

Ensure your security group allows inbound TCP on ports 8080 and 8081 from your client applications.

Scaling

Configure ECS Service Auto Scaling to scale based on CPU utilization:

aws application-autoscaling register-scalable-target \
  --service-namespace ecs \
  --resource-id service/<cluster-name>/hiya-voice-verification \
  --scalable-dimension ecs:service:DesiredCount \
  --min-capacity 1 \
  --max-capacity 10

aws application-autoscaling put-scaling-policy \
  --service-namespace ecs \
  --resource-id service/<cluster-name>/hiya-voice-verification \
  --scalable-dimension ecs:service:DesiredCount \
  --policy-name cpu-scaling \
  --policy-type TargetTrackingScaling \
  --target-tracking-scaling-policy-configuration "TargetValue=50.0,PredefinedMetricSpecification={PredefinedMetricType=ECSServiceAverageCPUUtilization}"

Prerequisites​

Fargate vs EC2 Launch Type​

Step 1 — Store Credentials in AWS Secrets Manager​

Step 2 — Create a Task Definition​

Step 3 — Configure Registry Authentication​

Step 4 — Create the Service​

Network Configuration​

Scaling​