Deploy with Docker

This guide covers running the Hiya Voice Verification engine on a single host using Docker. This is suitable for development, testing, or low-traffic production workloads.

Prerequisites

• Container image pulled and authenticated — see Getting the Container Image
• Docker version 20.10 or later
• A valid API_KEY from your Hiya account team
• At least 8 GB of available RAM (4 GB for the tmpfs model mount, plus engine overhead)

Running the Container

docker run -d \
  --name hiya-voice-verification \
  -e API_KEY=<your-api-key> \
  -p 8080:8080 \
  -p 8081:8081 \
  --tmpfs /opt/loccus/models:rw,noexec,nosuid,size=4g \
  europe-docker.pkg.dev/loccus-platform/onpremise-images/engine-api-standalone:<version>

The --tmpfs flag mounts a RAM-backed filesystem at /opt/loccus/models. The engine loads its ML models into this path at startup, keeping model data in memory rather than on persistent disk.

See Deployment Overview for a full list of environment variables.

Health Check

The container implements the gRPC Health Check protocol on port 8080. You can verify the engine is running with:

grpcurl -plaintext localhost:8080 grpc.health.v1.Health/Check

Or add a health check to your Docker run command:

docker run -d \
  --name hiya-voice-verification \
  -e API_KEY=<your-api-key> \
  -p 8080:8080 \
  -p 8081:8081 \
  --tmpfs /opt/loccus/models:rw,noexec,nosuid,size=4g \
  --health-cmd="grpcurl -plaintext localhost:8080 grpc.health.v1.Health/Check || exit 1" \
  --health-interval=10s \
  --health-start-period=30s \
  europe-docker.pkg.dev/loccus-platform/onpremise-images/engine-api-standalone:<version>

Docker Compose

For easier management, use Docker Compose:

# docker-compose.yml
services:
  hiya-voice-verification:
    image: europe-docker.pkg.dev/loccus-platform/onpremise-images/engine-api-standalone:<version>
    ports:
      - "8080:8080"
      - "8081:8081"
    environment:
      - API_KEY=<your-api-key>
    tmpfs:
      - /opt/loccus/models:rw,noexec,nosuid,size=4g
    restart: unless-stopped

Start the service:

docker compose up -d

Running as a systemd Service

For production single-host deployments, you can manage the container with systemd:

# /etc/systemd/system/hiya-voice-verification.service
[Unit]
Description=Hiya Voice Verification Engine
After=docker.service
Requires=docker.service

[Service]
Type=simple
Restart=always
RestartSec=10
ExecStartPre=-/usr/bin/docker rm -f hiya-voice-verification
ExecStart=/usr/bin/docker run \
  --name hiya-voice-verification \
  -e API_KEY=<your-api-key> \
  -p 8080:8080 \
  -p 8081:8081 \
  --tmpfs /opt/loccus/models:rw,noexec,nosuid,size=4g \
  europe-docker.pkg.dev/loccus-platform/onpremise-images/engine-api-standalone:<version>
ExecStop=/usr/bin/docker stop hiya-voice-verification

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now hiya-voice-verification

Upgrading

To upgrade to a new version:

docker pull europe-docker.pkg.dev/loccus-platform/onpremise-images/engine-api-standalone:<new-version>
docker stop hiya-voice-verification
docker rm hiya-voice-verification
# Re-run with the new version tag

If using Docker Compose, update the image tag in docker-compose.yml and run:

docker compose up -d