Deploying Eggplant Generator with Docker

This page describes how to deploy Eggplant Generator in a Docker container. Before proceeding with the steps on this page, be sure to complete the pre-deployment steps for Windows or Linux. You will also need to install Eggplant IAM (Keycloak), which is Eggplant Generator's user identity and access manager.

Deploy Eggplant Generator with Docker

info

Eggplant Generator container images are large. Please be sure to allow time to pull them during deployment.

Please ensure you have installed Eggplant IAM (Keycloak) and that it is up and running before proceeding.

1. Create a directory named generator.

2. Download the Eggplant Generator Docker Compose file here into the generator directory.

3. Create a file called .env in the generator directory with the content below, updating the values to suit your installation:

   info

   The values for KC_ADMIN_USER, KC_ADMIN_PASSWORD and REALM_INSTALLER_CLIENT_SECRET should match the values used when installing Keycloak.

   GENERATOR_URL=https://generator.example.com:8443
   KEYCLOAK_BASE_URL=https://keycloak.example.com/auth/
   KEYCLOAK_FRONTEND_URL=https://keycloak.example.com/auth/
   KC_ADMIN_USER=admin
   KC_ADMIN_PASSWORD=securepassword
   REALM_INSTALLER_CLIENT_SECRET=realm_installer_client_secret

4. Eggplant Generator requires Transport Layer Security (TLS) / HTTPS and will not function correctly using plain HTTP.

   tip

   Any public TLS certificates can be used. If you do not have a preferred TLS certificate provider we suggest Lets Encrypt which provides free TLS certs. Please refer to the documentation on options for obtaining and automatically renewing certificates though Lets Encrypt.

   Add the location of your TLS certificate and key files to the .env file created in the previous step:

   TLS_CERT=path/to/cert/file
   TLS_KEY=path/to/key/file

5. Initialize Eggplant Generator by running the following command:

   docker compose --file docker-compose-1.2.1-1.yaml --profile init up

   tip

   You only need to run the command above once to initialize Generator (the first time you run Generator).

   Example output:

   [+] Running 2/2
   ✔ gai-init Pulled                                                                                                                                                                                            1.7s
      ✔ 90b9666d4aed Pull complete                                                                                                                                                                               0.4s
   [+] Running 2/2
   ✔ Network gai_default       Created                                                                                                                                                                          0.0s
   ✔ Container gai-gai-init-1  Created                                                                                                                                                                          0.1s
   Attaching to gai-init-1
   gai-init-1  | Creating required folders
   gai-init-1  | Created folders successfully
   gai-init-1 exited with code 0

6. Configure Keycloak for Eggplant Generator by running the following command:

   docker compose --file docker-compose-1.2.1-1.yaml --profile realm-config up

   Example output:

   [+] Running 2/2
   ✔ Network compose_eggplant_nw          Created                                                                                                                                                               0.0s
   ✔ Container kc-realm-config-installer  Created                                                                                                                                                               2.3s
   Attaching to kc-realm-config-installer
   kc-realm-config-installer  | configure -a generator -e dev -e on_prem
   kc-realm-config-installer  | operation: configure
   kc-realm-config-installer  | adding app common...
   kc-realm-config-installer  | including extra config for dev...
   kc-realm-config-installer  | path /config/configure/??_common/extras/dev/*.yaml
   kc-realm-config-installer  | including extra config for on_prem...
   kc-realm-config-installer  | path /config/configure/??_common/extras/on_prem/*.yaml
   kc-realm-config-installer  | adding app generator...
   kc-realm-config-installer  | including extra config for dev...
   kc-realm-config-installer  | path /config/configure/??_generator/extras/dev/*.yaml
   kc-realm-config-installer  | including extra config for on_prem...
   kc-realm-config-installer  | path /config/configure/??_generator/extras/on_prem/*.yaml
   kc-realm-config-installer  | inclusions: /config/configure/??_common/*.yaml /config/configure/00_common/extras/dev/dev.yaml /config/configure/??_generator/*.yaml /config/configure/02_generator/extras/dev/dev.yaml /config/configure/02_generator/extras/on_prem/on_prem.yaml
   kc-realm-config-installer  | 2025-06-13T15:36:34.233Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigApplication   : Starting KeycloakConfigApplication v6.4.0 using Java 21.0.6 with PID 20 (/app/keycloak-config-cli.jar started by nobody in /)
   kc-realm-config-installer  | 2025-06-13T15:36:34.239Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigApplication   : No active profile set, falling back to 1 default profile: "default"
   kc-realm-config-installer  | 2025-06-13T15:36:35.128Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigApplication   : Started KeycloakConfigApplication in 1.627 seconds (process running for 2.403)
   kc-realm-config-installer  | 2025-06-13T15:36:36.267Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/01_master_realm.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:37.329Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/02_customer_realm.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:38.207Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/03_client_scopes.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:38.518Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/04_client.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:38.912Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/05_client_roles.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:39.207Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/06_client_composite_roles.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:40.265Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/07_roles.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:40.610Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/08_service_accts.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:40.891Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/extras/dev/dev.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:41.081Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/02_generator/01_generator_clients_core.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:41.381Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/02_generator/02_generator_resource_roles.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:42.132Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/02_generator/03_generator_composites.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:42.821Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/02_generator/extras/dev/dev.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:43.024Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/02_generator/extras/on_prem/on_prem.yaml'
   kc-realm-config-installer  | 2025-06-13T15:36:43.393Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : keycloak-config-cli ran in 00:07.535.
   kc-realm-config-installer exited with code 0

7. Start Eggplant Generator with GPU support using the following command:

   tip

   With access to a GPU, Eggplant Generator can generate test assets much faster, so we strongly recommend a GPU-based deployment whenever possible.

   docker compose --file docker-compose-1.2.1-1.yaml --profile default up -d

   If your machine does not have a GPU available, start Eggplant Generator with GPU support disabled using the following command:

   docker compose --file docker-compose-1.2.1-1.yaml --profile cpu up -d

   info

   Other useful Docker commands:

   • docker-compose --profile name logs shows logs from all containers.

   • docker logs container_name shows logs from selected container.

   • docker-compose --profile name stop to stop running containers.

   • docker-compose --profile name down to tear down all deployed resources.

Launch Generator in Docker

See Launching Eggplant Generator for information about how to launch Eggplant Generator.

Backup and Restore

You must regularly back up configuration and results data from your Generator installation. Data that needs to be backed up is stored in PostgreSQL as well as a volume attached to the gai deployment.

How you back up this data will depend on how you've configured your deployment, but here we provide an example of how both can be backed up in the default installation shown at the start of this document.

Backup Generator data

1. Create a backup of the Keycloak database.

   docker exec -i \
     $(docker ps \
       --filter label=com.docker.compose.project=keycloak \
       --filter label=com.docker.compose.service=postgres \
       --format '{{.ID}}') \
     sh -c 'export PGPASSWORD=$POSTGRES_PASSWORD && pg_dump --username postgres -d keycloak --clean --create' \
     > keycloak.dump

2. Create a backup of the Eggplant skill database.

   docker exec -i \
     $(docker ps \
       --filter label=com.docker.compose.project=gai \
       --filter label=com.docker.compose.service=postgres-db \
       --format '{{.ID}}') \
     sh -c 'export PGPASSWORD=$POSTGRES_PASSWORD && pg_dump --username postgres -d eggplant_skill --clean --create' \
     > eggplant_skill.dump

3. Create a backup of all the Generator asset files.

   docker exec -i \
     $(docker ps \
       --filter label=com.docker.compose.project=gai \
       --filter label=com.docker.compose.service=gai-api-server \
       --format '{{.ID}}') \
       tar czf - -C /etc/sde downloads requirement spacy upload_docs >assets.tar.gz

Restore Generator data

info

The commands below assume you have the three files (keycloak.dump, eggplant_skill.dump and assets.tar.gz) generated as part of the backup procedure above in your working directory.

1. Stop services to clear the database connections.

   docker ps \
     --filter label=com.docker.compose.project=keycloak \
     --format '{{.ID}} {{.Label "com.docker.compose.service"}}' \
   | awk '$2 != "postgres" {print $1}' \
   | xargs -r docker stop
   
   docker ps \
     --filter label=com.docker.compose.project=gai \
     --format '{{.ID}} {{.Label "com.docker.compose.service"}}' \
   | awk '$2 != "postgres-db" {print $1}' \
   | xargs -r docker stop
   

2. Restore the keycloak database.

   docker exec -i \
     $(docker ps \
       --filter label=com.docker.compose.project=keycloak \
       --filter label=com.docker.compose.service=postgres \
       --format '{{.ID}}') \
     sh -c 'export PGPASSWORD=$POSTGRES_PASSWORD && psql --username=postgres --dbname=postgres --file=-' \
     < keycloak.dump

3. Restore the eggplant_skill database.

   tip

   This database can take a very long time to restore.

   docker exec -i \
     $(docker ps \
       --filter label=com.docker.compose.project=gai \
       --filter label=com.docker.compose.service=postgres-db \
       --format '{{.ID}}') \
     sh -c 'export PGPASSWORD=$POSTGRES_PASSWORD && psql --username=postgres --dbname=postgres --file=-' \
     < eggplant_skill.dump

4. Bring the service back up by rerunning the docker compose up command for both Eggplant IAM (Keycloak) and Generator.

   tip

   The commands below must be run from the directories where you originally downloaded the Docker Compose file and configured the .env file. This will be a different directory for Keycloak and Generator.

   Keycloak

   docker compose --file docker-compose-6.3.247.yml --profile default up -d

   Generator

   docker compose --file docker-compose-1.2.1-1.yaml --profile default up -d

5. Restore assets to gai PVC.

   docker exec -i \
     $(docker ps \
       --filter label=com.docker.compose.project=gai \
       --filter label=com.docker.compose.service=gai-api-server \
       --format '{{.ID}}') \
     sh -c "tar -xzv -C /etc/sde --file -" <./assets.tar.gz

Upgrade Generator in Docker Deployments

info

Unless stated otherwise, the general procedure for upgrading is to preserve the existing installation and deploy using a new Docker Compose file.

Each release may have specific additional steps. So before applying this procedure, please review the notes below for the upgrade you're performing.

Upgrading 1.1.0 to 1.2.0

1. Download the Eggplant Generator Docker Compose file here into the generator directory.

2. Upgrade Eggplant Generator by running the following command:

   docker compose --file docker-compose-1.2.1-1.yaml --profile default up -d

   If your machine does not have a GPU available, start Eggplant Generator with GPU support disabled using the following command:

   docker compose --file docker-compose-1.2.1-1.yaml --profile cpu up -d

Uninstall Generator

You can uninstall by running the command below:

docker compose --file docker-compose-1.2.1-1.yaml --profile init --profile default --profile realm-config down --volumes