Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

Custom images

tip

This feature is only available to users in a single-tenant environment. Additionally, teams will need to contact [email protected] to get this configured.

By default, Hex is set up with images for multiple versions of Python, each of which contain many pre-installed packages. These images are often sufficient for most projects, and are designed to get users off the ground quickly.

In addition to these options, Hex supports custom images. Custom images give you significantly more control over what is included in the images accessible to users, allowing you to tailor an environment to suite your needs.

Create an image​

Custom images are built using Docker inside of Amazon Elastic Container Registry (ECR). Hex will provide the ECR, and you will need access to AWS and familiarity with Docker and Python environments in order to build images.

Prerequisites​

  • AWS credentials
  • A Docker environment to build the image

Your AWS credentials will require permission to perform a number of actions in order to push to the ECR repository Hex provides:

"Action": [
                "ecr:PutImage",
                "ecr:InitiateLayerUpload",
                "ecr:UploadLayerPart",
                "ecr:CompleteLayerUpload",
                "ecr:GetAuthorizationToken",
                "ecr:BatchCheckLayerAvailability"
            ]

Prepare your image​

To ensure a fast, stable build, it is advised to build your image from python:3.9.12-bullseye. There are certain Python packages core to Hex's functionality which will be installed on top of your image at specific versions that cannot be altered. For more information see our docs on fixed package versions.

warning

Custom images currently only support Python 3.9.

Push your image to the Hex repository​

Once you have built the Docker image, you can push this to Hex by doing the following:

  1. Log in to AWS ECR
  2. Tag your image appropriately for the AWS ECR
  3. Push to the ECR in Docker

For example:

aws ecr get-login-password --region <region provided by hex> | docker login --username AWS --password-stdin <account id provided by hex>.dkr.ecr.us-west-2.amazonaws.com
docker build -t my-custom-image:latest .
docker tag my-custom-image:latest <ECR repo provided by Hex>:<your-image-tag>
docker push <ECR repo provided by Hex>:your-tag

For more information, see the AWS documentation on pushing a Docker image to an Amazon ECR repository.

Once the push is complete, Hex will install its required Python packages and dependencies on top of the image and make it available in your Hex workspace. This process takes should take 10-20 minutes. You can view the status of the build in the custom kernels section of your workspace assets page.

Checking logs​

Logs from the Hex's docker build can be downloaded from the workspace assets page. Once an image build has succeeded or failed, the image will contain a link to download the latest build logs.

Manage existing images​

Images that have already been pushed to the ECR can be managed from the workspace assets page. There you will see the current build status of your images, the number of projects they are used in, and the build date. You can also rename, see previous versions of, or delete images from the three-dot menu to the right of the image.

Rename an image​

By default, image names are inherited from the docker tag attached to the image when it is initially pushed to the ECR. The image name can be altered by selecting Edit... from the three-dot menu to the right of the image. The name selected will display for developers when they select an image for their project.

View image versions​

Hex tracks version history when new images are pushed with the same tag and overwrites the existing image with the new image. You can view the date when a previous version was pushed as well as the build logs for a previous version by selecting See versions from the three-dot menu to the right of the image.

Delete an image​

Images can be deleted if they are no longer necessary. Beware that deleting an image will leave any projects with the image currently selected in a broken state where they must select a new image before they are usable again. To delete an image, select Delete kernel image from the three-dot menu to the right of the image.

warning

Deleting an image will immediately break any published apps that utilize the image, until they select a new image and republish.

On this page