Getting the Container Image

Before deploying the Hiya Voice Verification engine, you need to authenticate with our private registry and pull the container image.

Prerequisites

• Docker version 20.10 or later (or any OCI-compatible tool such as Podman, nerdctl, or crane)
• Registry credentials — a JSON key file provided by your Hiya account team
• Network access — outbound HTTPS connectivity to europe-docker.pkg.dev on port 443

The JSON key file grants pull-only access to the Hiya image repository. It is separate from the API key used at runtime for usage metering. Keep both credentials secure and do not commit them to version control.

Authenticating with the Registry

You must authenticate with Google Artifact Registry before you can pull the image. Choose whichever method fits your environment.

Method A — Docker login (recommended)

cat key.json | docker login -u _json_key --password-stdin europe-docker.pkg.dev

The username _json_key is a literal string required by Google Artifact Registry — it is not a placeholder. Use it exactly as shown.

Method B — Using gcloud

If your environment already has the Google Cloud CLI installed:

gcloud auth activate-service-account --key-file=key.json
gcloud auth configure-docker europe-docker.pkg.dev

This configures Docker's credential helper so that subsequent docker pull commands authenticate automatically.

Pulling the Image

docker pull europe-docker.pkg.dev/loccus-platform/onpremise-images/engine-api-standalone:<version>

Replace <version> with the specific tag provided by the Hiya team. Always pin to an explicit version — do not use latest.

The image is approximately 4 GB due to bundled ML models. Ensure adequate bandwidth and consider pulling during off-peak hours.

Credential Rotation

Hiya may periodically rotate your registry credentials. When this happens:

1. You will receive a new JSON key file from your Hiya account team.
2. The previous key will stop working after a short grace period.
3. Re-authenticate using the new key by re-running docker login as described above.
4. If using Kubernetes, update your image pull secret — see the Kubernetes deployment guide.

Troubleshooting

Symptom	Cause	Resolution
UNAUTHORIZED error on pull	Key file is expired or incorrect	Re-run docker login with a valid key file. Contact Hiya if the issue persists.
MANIFEST_UNKNOWN error	Wrong version tag	Verify the tag with your Hiya account team.
Connection timeouts	Firewall blocking outbound traffic	Allow outbound HTTPS (port 443) to europe-docker.pkg.dev.

Next Steps

Once you have the image, choose a deployment method:

Deployment Overview

Compare deployment options and choose the right one for your environment.