Skip to main content
Version: GAI 26.1

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 should match the values used when installing Keycloak. REALM_INSTALLER_CLIENT_SECRET should be a randomly generated string.

    INITIAL_USER_PASSWORD should be at least 12 characters.

    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

    POSTGRES_USER=postgres
    POSTGRES_PASSWORD=strong_database_password
    POSTGRES_DB=eggplant_skill

    INITIAL_USER_USERNAME=username
    INITIAL_USER_PASSWORD=securepassword2
    INITIAL_USER_GIVEN_NAME=given_name
    INITIAL_USER_FAMILY_NAME=family_name
    INITIAL_USER_EMAIL=email_address

tip

Always set POSTGRES_PASSWORD in the .env file. It is passed to both the PostgreSQL container and the Generator services. The compose file defaults to eggplant if not provided, which is not recommended for production.

  1. 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

  2. Initialize Eggplant Generator by running the following command:

    docker compose --file docker-compose-26.1.0-11.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

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

    docker compose --file docker-compose-26.1.0-11.yaml --profile realm-config up

    Example output:


    [+] Running 4/3
     ✔ Network compose_eggplant_nw                    Created                                                                                                                           0.1s
     ✔ Container kc-realm-config-reset                Created                                                                                                                           0.1s
     ✔ Container kc-realm-config-installer-iam        Created                                                                                                                           0.0s
     ✔ Container kc-realm-config-installer-generator  Created                                                                                                                           0.1s
    Attaching to kc-realm-config-installer-generator, kc-realm-config-installer-iam, kc-realm-config-reset
    kc-realm-config-reset                | reset
    kc-realm-config-reset                | operation: reset
    kc-realm-config-reset                | adding app common...
    kc-realm-config-reset                | inclusions: /config/reset/??_common/*.yaml
    kc-realm-config-reset                | 2026-01-14T12:30:29.116Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigApplication   : Starting KeycloakConfigApplication v6.4.0 using Java 21.0.6 with PID 8 (/app/keycloak-config-cli.jar started by nobody in /)
    kc-realm-config-reset                | 2026-01-14T12:30:29.119Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigApplication   : No active profile set, falling back to 1 default profile: "default"
    kc-realm-config-reset                | 2026-01-14T12:30:29.556Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigApplication   : Started KeycloakConfigApplication in 0.753 seconds (process running for 1.08)
    kc-realm-config-reset                | 2026-01-14T12:30:30.013Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/reset/00_common/01_reset.yaml'
    kc-realm-config-reset                | 2026-01-14T12:30:32.091Z  INFO 8 --- [           main] d.a.k.config.KeycloakConfigRunner        : keycloak-config-cli ran in 00:02.214.
    kc-realm-config-reset exited with code 0
    kc-realm-config-installer-iam        | configure -e dev -e smtp -e initial_user
    kc-realm-config-installer-iam        | operation: configure
    kc-realm-config-installer-iam        | adding app common...
    kc-realm-config-installer-iam        | including extra config for dev...
    kc-realm-config-installer-iam        | path /config/configure/??_common/extras/dev/*.yaml
    kc-realm-config-installer-iam        | including extra config for smtp...
    kc-realm-config-installer-iam        | path /config/configure/??_common/extras/smtp/*.yaml
    kc-realm-config-installer-iam        | including extra config for initial_user...
    kc-realm-config-installer-iam        | path /config/configure/??_common/extras/initial_user/*.yaml
    kc-realm-config-installer-iam        | inclusions: /config/configure/??_common/*.yaml /config/configure/00_common/extras/dev/dev.yaml /config/configure/00_common/extras/smtp/smtp.yaml /config/configure/00_common/extras/initial_user/initial_user.yaml
    kc-realm-config-installer-iam        | 2026-01-14T12:30:33.290Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigApplication   : Starting KeycloakConfigApplication v6.4.0 using Java 21.0.6 with PID 17 (/app/keycloak-config-cli.jar started by nobody in /)
    kc-realm-config-installer-iam        | 2026-01-14T12:30:33.292Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigApplication   : No active profile set, falling back to 1 default profile: "default"
    kc-realm-config-installer-iam        | 2026-01-14T12:30:33.704Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigApplication   : Started KeycloakConfigApplication in 0.72 seconds (process running for 1.061)
    kc-realm-config-installer-iam        | 2026-01-14T12:30:34.190Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/01_master_realm.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:35.209Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/02_customer_realm.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:36.311Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/03_client_scopes.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:36.574Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/04_client.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:36.945Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/05_client_roles.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:37.421Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/06_client_composite_roles.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:38.842Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/07_roles.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:39.144Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/08_service_accts.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:39.434Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/extras/dev/dev.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:39.596Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/extras/smtp/smtp.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:39.800Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/extras/initial_user/initial_user.yaml'
    kc-realm-config-installer-iam        | 2026-01-14T12:30:40.104Z  INFO 17 --- [           main] d.a.k.config.KeycloakConfigRunner        : keycloak-config-cli ran in 00:06.095.
    kc-realm-config-installer-iam exited with code 0
    kc-realm-config-installer-generator  | configure -a generator -e dev -e on_prem
    kc-realm-config-installer-generator  | operation: configure
    kc-realm-config-installer-generator  | adding app common...
    kc-realm-config-installer-generator  | including extra config for dev...
    kc-realm-config-installer-generator  | path /config/configure/??_common/extras/dev/*.yaml
    kc-realm-config-installer-generator  | including extra config for on_prem...
    kc-realm-config-installer-generator  | path /config/configure/??_common/extras/on_prem/*.yaml
    kc-realm-config-installer-generator  | adding app generator...
    kc-realm-config-installer-generator  | including extra config for dev...
    kc-realm-config-installer-generator  | path /config/configure/??_generator/extras/dev/*.yaml
    kc-realm-config-installer-generator  | including extra config for on_prem...
    kc-realm-config-installer-generator  | path /config/configure/??_generator/extras/on_prem/*.yaml
    kc-realm-config-installer-generator  | 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-generator  | 2026-01-14T12:30:41.089Z  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-generator  | 2026-01-14T12:30:41.091Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigApplication   : No active profile set, falling back to 1 default profile: "default"
    kc-realm-config-installer-generator  | 2026-01-14T12:30:41.550Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigApplication   : Started KeycloakConfigApplication in 0.768 seconds (process running for 1.111)
    kc-realm-config-installer-generator  | 2026-01-14T12:30:42.053Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/01_master_realm.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:42.535Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/02_customer_realm.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:43.086Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/03_client_scopes.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:43.361Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/04_client.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:43.670Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/05_client_roles.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:43.908Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/06_client_composite_roles.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:44.819Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/07_roles.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:45.102Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/08_service_accts.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:45.316Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/00_common/extras/dev/dev.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:45.493Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/02_generator/01_generator_clients_core.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:45.718Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/02_generator/02_generator_resource_roles.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:46.416Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/02_generator/03_generator_composites.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:46.982Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : Importing file 'file:/config/configure/02_generator/extras/dev/dev.yaml'
    kc-realm-config-installer-generator  | 2026-01-14T12:30:47.146Z  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-generator  | 2026-01-14T12:30:47.470Z  INFO 20 --- [           main] d.a.k.config.KeycloakConfigRunner        : keycloak-config-cli ran in 00:05.606.
    kc-realm-config-installer-generator exited with code 0

  4. 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-26.1.0-11.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-26.1.0-11.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.266.yml --profile default up -d

    Generator

    docker compose --file docker-compose-26.1.0-11.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.2.0 to 26.1.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-26.1.0-11.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-26.1.0-11.yaml --profile cpu up -d

Uninstall Generator​

You can uninstall by running the command below:

docker compose --file docker-compose-26.1.0-11.yaml --profile init --profile default --profile realm-config down --volumes
Last updated on