Deploy with custom images

Deploying ZenML with custom Docker images.

In most cases, deploying ZenML with the default zenmlhub/zenml-server Docker image should work just fine. However, there are some scenarios when you might need to deploy ZenML with a custom Docker image:

• You have implemented a custom artifact store for which you want to enable artifact visualizations or step logs in your dashboard.

• You have forked the ZenML repository and want to deploy a ZenML server based on your own fork because you made changes to the server / database logic.

Deploying ZenML with custom Docker images is only possible for Docker or Helm deployments.

Build and Push Custom ZenML Server Docker Image

Here is how you can build a custom ZenML server Docker image:

1. Set up a container registry of your choice. E.g., as an indivial developer you could create a free Docker Hub account and then set up a free Docker Hub repository.

2. Clone ZenML (or your ZenML fork) and checkout the branch that you want to deploy, e.g., if you want to deploy ZenML version 0.41.0, run

   git checkout release/0.41.0

3. Copy the ZenML base.Dockerfile, e.g.:

   cp docker/base.Dockerfile docker/custom.Dockerfile

4. Modify the copied Dockerfile:

   • Add additional dependencies:

   RUN pip install <my_package>

   • (Forks only) install local files instead of official ZenML:

   RUN pip install -e .[server,secrets-aws,secrets-gcp,secrets-azure,secrets-hashicorp,s3fs,gcsfs,adlfs,connectors-aws,connectors-gcp,connectors-azure]

5. Build and push an image based on your Dockerfile:

   docker build -f docker/custom.Dockerfile . -t <YOUR_CONTAINER_REGISTRY>/<IMAGE_NAME>:<IMAGE_TAG> --platform linux/amd64
   docker push <YOUR_CONTAINER_REGISTRY>/<IMAGE_NAME>:<IMAGE_TAG>

If you want to verify your custom image locally, you can follow the Deploy a custom ZenML image via Docker section below to deploy the ZenML server locally first.

Deploy ZenML with your custom image

Next, adjust your preferred deployment strategy to use the custom Docker image you just built.

Deploy a custom ZenML image via CLI

You can deploy your custom image via the zenml deploy CLI command by setting the --config argument to a custom configuration file that has both zenmlserver_image_repo and zenmlserver_image_tag set:

1. Define a custom config.yaml based on the base deployment configuration file and set zenmlserver_image_repo and zenmlserver_image_tag according to the custom image you built:

   zenmlserver_image_repo: <YOUR_CONTAINER_REGISTRY>/<IMAGE_NAME>
   zenmlserver_image_tag: <IMAGE_TAG>

2. Run zenml deploy with the custom config file:

   zenml deploy --config=/PATH/TO/FILE

See the general ZenML CLI Deployment Guide for more information on how to use the zenml deploy CLI command and what other options can be configured.

Deploy a custom ZenML image via Docker

To deploy your custom image via Docker, first familiarize yourself with the general ZenML Docker Deployment Guide.

To use your own image, follow the general guide step by step but replace all mentions of zenmldocker/zenml-server with your custom image reference <YOUR_CONTAINER_REGISTRY>/<IMAGE_NAME>:<IMAGE_TAG>. E.g.:

• To run the ZenML server with Docker based on your custom image, do

docker run -it -d -p 8080:8080 --name zenml <YOUR_CONTAINER_REGISTRY>/<IMAGE_NAME>:<IMAGE_TAG>

• To use docker-compose, adjust your docker-compose.yml:

services:
  zenml:
    image: <YOUR_CONTAINER_REGISTRY>/<IMAGE_NAME>:<IMAGE_TAG>

Deploy a custom ZenML image via Helm

To deploy your custom image via Helm, first familiarize yourself with the general ZenML Helm Deployment Guide.

To use your own image, the only thing you need to do differently is to modify the image section of your values.yaml file:

zenml:
  image:
    repository: <YOUR_CONTAINER_REGISTRY>/<IMAGE_NAME>
    tag: <IMAGE_TAG>