Quick start

The on-prem API runs as a single container image that bundles the API, the processing workers, and the machine learning models. You can deploy it in your own cloud, or on your own hardware, using any OCI-compliant container runtime.

Prerequisites

License

You need a license key and an application ID. Contact sales to get a license.

Only x86-64 ISA

The on-prem API does not support ARM processors, only x86-64 (AMD64) processors.

Resources

Per container:

• Minimum: 2 CPU cores, 4 GB of memory
• Recommended: 4 CPU cores, 8 GB of memory

Docker

This article uses Docker for image and container management, but you can use any other OCI-compliant tool.

Minimum Docker version: >= 20.10.5.

Get the image

docker pull us-docker.pkg.dev/document-verification-public/on-prem/core:4000.0.0

Run the container

docker run -p 8080:8080  \
  -e LICENSE_KEY={your_license_key} \
  -e LICENSE_APPLICATION_ID={your_application_id} \
  us-docker.pkg.dev/document-verification-public/on-prem/core:4000.0.0

Make a request

You can now make your first request:

cURL

curl http://localhost:8080/api/v3/verify \
  --request POST \
  --form 'imageFirstSide=@front_id.jpg' \
  --form 'imageSecondSide=@back_id.png'

JavaScript

const formData = new FormData()
formData.append('imageFirstSide', new Blob([]), 'front_id.jpg')
formData.append('imageSecondSide', new Blob([]), 'back_id.png')

fetch('http://localhost:8080/api/v3/verify', {
  method: 'POST',
  body: formData
})

Python

requests.post("http://localhost:8080/api/v3/verify",
    files=[
      ("imageFirstSide", open("front_id.jpg", "rb")),
      ("imageSecondSide", open("back_id.png", "rb"))
    ]
)

Go

package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
)

func main() {
	requestUrl := "http://localhost:8080/api/v3/verify"

	payload := &bytes.Buffer{}
	writer := multipart.NewWriter(payload)

	part, _ := writer.CreateFormFile("imageFirstSide", "front_id.jpg")

	f, _ := os.Open("front_id.jpg")
	defer f.Close()

	_, _ = io.Copy(part, f)

	part, _ = writer.CreateFormFile("imageSecondSide", "back_id.png")

	f, _ = os.Open("back_id.png")
	defer f.Close()

	_, _ = io.Copy(part, f)
	writer.Close()

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Set("Content-Type", writer.FormDataContentType())

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

See how to configure your requests, and learn how to interpret the response.

Going to production

The single docker run above is enough to get started. For production, use the reference Docker Compose or Kubernetes deployment and:

• Set a memory limit. Overload protection is a percentage of the cgroup memory limit, and it's disabled when there is no limit, so the container can't reject requests before it runs out of memory.
• Run the container under a restart policy. It runs the API, the workers, and the model server as separate processes, and nothing restarts inside the container: if any of them exits, the whole container exits and needs to be brought back as one unit.
• Route traffic only after /health/ready succeeds.
• Add replicas when representative load testing shows that one container doesn't provide enough capacity.

See Environment variables for the settings that control capacity, memory limits, and shutdown.