Start Screening with the Container

Granica Screen can be provided as a container to be hosted by the user, allowing users full control to deploy the solution within their infrastructure according to their needs.

This guide provides instructions for gaining access to the container image, and simple directions to start the container and try out the Screen API.

Get Access to the Container Image

Getting access to the container image is as simple as providing an AWS role to be granted access by the Granica team. This section walks through the steps of creating a role with the minimal necessary permissions. If you already have an EC2 role you wish to use with sufficient permissions, skip straight to requesting access.

Note that this setup requires sufficient IAM permissions to create service roles and policies. See the AWS docs for more details.

Create an IAM Policy

Create a new IAM policy with the following json content. We will refer to this policy as granica-screen-docker-policy for subsequent steps.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ECRToken",
"Effect": "Allow",
"Action": "ecr:GetAuthorizationToken",
"Resource": "*"
},
{
"Sid": "ImageAccess",
"Effect": "Allow",
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:BatchCheckLayerAvailability"
],
"Resource": "arn:aws:ecr:us-east-2:809541265033:repository/screen"
}
]
}

Create an IAM Role

Create a new EC2 role and attach the newly created granica-screen-docker-policy IAM policy to it. We will refer to this role as granica-screen-docker-role for subsequent steps.

Request Access

Contact us to give us the ARN of the IAM role created in the previous step. Our team will grant this role access to pull the docker image from our ECR repository.

If you intend to deploy the container using a different method, simply provide another role which would be the preferred method of access.

Setup EC2 Instance with the Docker Container

System Requirements

Minimum system for the screen container development are as follows:

  • Any 64-bit x86 processor with 28GB RAM
  • NVIDIA GPU with at least 16GB VRAM
  • 128GB disk volume

On AWS, we recommend the g5.xlarge instance, which is a low cost GPU-based instance with the following specs:

  • 2 core 4 vCPU instance with 16 GB RAM
  • NVIDIA A10G Tensor Core GPU with 24GB VRAM
  • 128GB disk volume

Provision the EC2 Instance

  • Choose Deep Learning Base OSS Nvidia Driver GPU AMI (Ubuntu 20.04) 20240308 as the AMI.
  • Select g5.xlarge as the instance type.
  • Make sure to select an EC2 keypair you have access to, or create a new one. You'll need it to access the EC2 instance.
  • Configure a default security group. Allow HTTP traffic to be able to access the screen endpoint from outside the container.
  • Allocate 128 GiB to the EBS gp2 root volume.
  • Within the Advanced Details section, attach the granica-screen-docker-role IAM role.

SSH into the EC2 Instance

SSH into the server using the following command. Replace <KEY_PAIR.pem> and <EC2_ADDRESS> with the location of your SSH keypair file and EC2 Public DNS (domain name), respectively.

ssh -i "<KEY_PAIR.pem>" ubuntu@<EC2_ADDRESS>

Login to Granica's ECR repository

Run the following command on the EC2 instance to login to Granica's ECR repository on the instance:

aws ecr get-login-password --region us-east-2 | docker login --username AWS --password-stdin 809541265033.dkr.ecr.us-east-2.amazonaws.com

Pull and Start the Docker Container

Run the following command to pull and start the Granica Screen API container inside your EC2 instance.

This command will first pull the image from ECR, which may take several minutes due to the size of the image. Afterwards, the command starts a docker container, and makes the Screen API available at port 80 on the host EC2 instance.

docker run -p 80:8080 -d --gpus all 809541265033.dkr.ecr.us-east-2.amazonaws.com/screen:latest

Using the container

Make Your First Screen Request

A simple example CURL request can be made from the host EC2 instance:

curl --location --request POST 'http://localhost:80/screen' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": "Hello, my email is joe@gmail.com and my name is John Smith. My phone is (650) 123-4566."
}'

A CURL request with more parameters can be made as follows:

curl --location --request POST 'http://localhost:80/screen' \
--header 'Content-Type: application/json' \
--data-raw '{
"data": "Hello, my email is joe@gmail.com and my name is John Smith. My phone is (650) 123-4566.",
"classificationTypes": [
{
"classificationType": "EMAIL",
"likelihoodType": "LIKELIHOOD_TYPE_MEDIUM"
},
{
"classificationType": "PHONE_NUMBER",
"likelihoodType": "LIKELIHOOD_TYPE_MEDIUM"
}
],
"transformationParams": {
"transformationType": "TRANSFORMATION_TYPE_SYNTHETIC"
}
}'

This request sends the string passed in the request to Screen for scanning and redacting, using the default settings. You should get a response with the redacted data and metadata about the scan results and transformation process.

Reveal Redacted Data Using the Reveal Request

The Reveal endpoint allows you to unredact the data that was redacted by the Screen API. This is useful for revealing redacted PII when necessary, such as when a user requests access to their own data.

curl --location --request POST 'http://localhost:80/reveal' \
--header 'Content-Type: application/json' \
--data-raw '{
"redactedData": "Hello, my email is [EMAIL_1] and my name is [PERSON_NAME_1] [PERSON_NAME_2]. My phone is [PHONE_NUMBER_1].",
"redactionMaps": [
{
"redactionString": "[EMAIL_1]",
"originalData": "joe@gmail.com"
},
{
"redactionString": "[PERSON_NAME_1]",
"originalData": "John"
},
{
"redactionString": "[PERSON_NAME_2]",
"originalData": "Smith"
},
{
"redactionString": "[PHONE_NUMBER_1]",
"originalData": "(650) 123-4566"
}
],
"transformationType": "TRANSFORMATION_TYPE_NUMBERED"
}'

Note: If transformationType is an encrypted transformation type, you can provide the encryption key in the request JSON encryptionKey field instead of providing the redactionMaps field. Decryption will be performed using the provided encryption key.

The request above will result in this JSON response:

{
"originalData": "Hello, my email is joe@gmail.com and my name is John Smith. My phone is (650) 123-4566."
}

API Docs

The Screen API provides many configuration options, as well as additional endpoints. Detailed API documentation can be found here. To find out about logging, health check and versioning, refer here.

Next steps

At this point, you have a single container running Granica Screen! This may be sufficient for simple tasks or small deployments. Larger and more complex workflows will likely want to integrate with a container orchestration system such as Kubernetes. Granica Screen can also be deployed as a fully managed cluster through the Granica Platform.