eureka-cli

Eureka CLI

Table of Contents

• Eureka CLI
  • Table of Contents
  • Purpose
  • Architecture
  • Prerequisites
  • Monitor system components
  • Commands
    • Build the binary
    • Install binary
    • (Optional) Enable autocompletion
    • Deploy the combined application
    • Undeploy the combined application
    • Deploy the combined application from AWS ECR
    • Deploy the ecs application
    • Undeploy the ecs application
    • Deploy the ecs-single application
    • Undeploy the ecs-single application
    • Deploy the ecs-migration application
    • Undeploy the ecs-migration application
    • Run IDP migration
    • Deploy the import application
    • Undeploy the import application
    • Deploy child applications
      • Deploy the export application
      • Deploy the search application
      • Deploy the edge application
    • Undeploy child applications
    • Intercept a module
    • Create a port proxy
    • Upgrade a module
    • Other commands
  • Using a custom folio-module-sidecar
  • Using a native folio-module-sidecar
  • Using local backend module images
  • Using local frontend module descriptors
  • Using the UI
  • Using Single Tenant UX
  • Using the environment
  • Troubleshooting
    • General
    • Command-based
  • Additional Resources

Purpose

• A CLI to orchestrate the deployment of a local Eureka-based development environment

Architecture

• The CLI is organized into layers: actions handle commands, services talk to external systems (Keycloak, Kong, Docker, Vault), and run configs manage profile-specific settings
• Commands like interceptModule and upgradeModule coordinate these layers to streamline local development — you can reroute traffic to your local IntelliJ instance for live debugging, or build and deploy new module versions in one go. No more switching between terminals or remembering multi-step procedures

For detailed workflows and examples, check out the Module Development Guide.

Prerequisites

Install dependencies:

• Go compiler: last development-tested version is go1.25.3 windows/amd64
• Rancher Desktop container daemon: last development-tested version is v1.20.1
  • Enable dockerd (Moby) container engine
  • Disable Check for updates automatically

On Windows, it is recommended to work exclusively in Windows Terminal running Git Bash:

• Windows Terminal: Install for better shell experience when paired with Git Bash
• Git Bash: Add to Windows Terminal as new default profile & Unix-like shell environment that supports Bash commands

Configure hosts (add entries to /etc/hosts or C:\Windows\System32\drivers\etc\hosts):

• Option 1 - Automated (recommended):
  • Linux/macOS: sudo ./misc/add-hosts.sh
  • Windows: Open PowerShell as Administrator and run: Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process; .\misc\add-hosts.ps1
• Option 2 - Manual: Add the following entries:
  • 127.0.0.1 postgres.eureka
  • 127.0.0.1 kafka.eureka
  • 127.0.0.1 vault.eureka
  • 127.0.0.1 keycloak.eureka
  • 127.0.0.1 kong.eureka

Monitor system components

• Keycloak Admin Console: admin/admin
• Vault UI (Userpass method): admin/admin
• Kafka UI: No auth
• Kong Admin GUI: No auth
• MinIO Console: minioadmin/minioadmin
• Kibana UI: No auth

Commands

Build the binary

mkdir -p ./bin
go build -o ./bin/ .

# Or pass GOOS and GOARCH to specify the platform and architecture explicitly
env GOOS=windows GOARCH=amd64 go build -ldflags="-s -w" -o ./bin/ .

For more details, check out the Build Binary Guide to build a platform-specific binary

Install binary

• After building and installing, the binary can be used from any directory

go install
eureka-cli deployApplication

If you wish to avoid the binary installation please use the relative path of the CLI binary, e.g. ./bin/eureka-cli with the correct path to the config

(Optional) Enable autocompletion

• Command autocompletion can be enabled in the shell of your choice. Below is an example for the Bash shell (.bash_profile is preferred on Windows because it is auto-sourced)

go install
echo "source <(eureka-cli completion bash)" >> ~/.bash_profile
source ~/.bash_profile

Type eureka-cli and hit TAB to see the available suggestions or full autocompletion

Flags with smart autocompletion:

Long	Short	Completion Source	Command(s)
--profile	-p	Available profiles from config	All commands (global flag)
--moduleName	-n	Backend modules from config	interceptModule, listModules, listModuleVersions,
			undeployModule, updateModuleDiscovery
--moduleType	-y	Container types (module, sidecar, etc)	listModules

Deploy the combined application

By default, public images from DockerHub (folioci & folioorg namespaces) will be used.

Available flags:

Global flags (available for all commands):

Long	Short	Description
--buildImages	-b	Build Docker images
--configFile	-c	Specify config file path
--enableDebug	-d	Enable debug mode
--onlyRequired	-q	Use only required system containers (deploySystem, deployApplication)
--overwriteFiles	-o	Overwrite files in .eureka home directory
--profile	-p	Select profile (combined, combined-native, export, search, edge, ecs, ecs-single import)

Command-specific flags:

Long	Short	Description	Command(s)
--all	-a	All modules for all profiles	listModules
--apps		Application names	purgeTenants
--cleanup		Perform a cleanup operation	deployApplication, upgradeModule
--defaultGateway	-g	Use default gateway in URLs	interceptModule
--enableEcsRequests		Enable ECS requests	deployUi, buildAndPushUi
--gatewayHostname		Gateway Hostname	createPortProxy
--gatewayURL		Gateway URL	purgeTenants
--id	-i	Module ID (e.g. mod-orders:13.1.0-SNAPSHOT.1021)	listModuleVersions
--ids		Tenant ids	purgeTenants
--length	-l	Salt length for edge API key	getEdgeApiKey
--moduleName	-n	Module name (e.g. mod-orders)	interceptModule, listModules,
			listModuleVersions,
			undeployModule, updateModuleDiscovery,
			upgradeModule
--modulePath		Module path (e.g. path to module in IntelliJ)	upgradeModule
--moduleType	-y	Filter by module type	listModules
--moduleUrl	-m	Module URL	interceptModule
--moduleVersion		Module version (e.g. 13.1.0-SNAPSHOT.1093)	upgradeModule
--namespace		DockerHub namespace	buildAndPushUi, upgradeModule
--platformCompleteURL		Platform Complete UI URL	buildAndPushUi
--privatePort		Private port	updateModuleDiscovery
--purgeSchemas		Purge PostgreSQL schemas on uninstallation	removeTenantEntitlements,
			undeployApplication
--removeApplication		Remove application from the DB	undeployApplication
--restore	-r	Restore module & sidecar	interceptModule, updateModuleDiscovery
--sidecarUrl	-s	Sidecar URL	interceptModule, updateModuleDiscovery
--singleTenant		Use for Single Tenant workflow	deployUi, buildAndPushUi
--skipApplication		Skip application operations	upgradeModule
--skipCapabilitySets		Skip refreshing capability sets	undeployApplication
--skipModuleArtifact		Skip building module artifact (jar and module descriptor)	upgradeModule
--skipModuleDeployment		Skip module & sidecar deployment	upgradeModule
--skipModuleDiscovery		Skip module discovery update	upgradeModule
--skipModuleImage		Skip building module Docker image	upgradeModule
--skipRegistry		Skip retrieving latest registry module versions	interceptModule, deployApplication,
			deployManagement, deployModules
--skipTenantEntitlement		Skip tenant entitlement operations	upgradeModule
--tenant	-t	Tenant name	getKeycloakAccessToken, getEdgeApiKey,
			buildAndPushUi
--tokenType		Token type	getKeycloakAccessToken
--updateCloned	-u	Update Git cloned projects	buildSystem, deployApplication,
			deployUi, buildAndPushUi
--user	-x	User for edge API key generation	getEdgeApiKey
--versions	-v	Number of versions to display	listModuleVersions

eureka-cli -c ./config.combined.yaml deployApplication

If no profile or config file is passed, the combined profile will be inferred and used

• Use the debug -d flag to troubleshoot your environment deployment and see how the CLI interacts with services by logging in verbose mode

eureka-cli deployApplication -d

• For resource-constrained environments, use the -q flag to deploy only the required system containers

eureka-cli deployApplication -q

• The profile -p flag eliminates the need to define a config file path by relying on the default configs that are automatically created in the .eureka home directory

eureka-cli -p combined deployApplication

Available profiles are: combined, combined-native, export, search, edge, ecs, ecs-single, ecs-migration and import (combined, combined-native, ecs, ecs-single, ecs-migration and import are standalone applications)

• It can be combined with the -o flag to overwrite all existing files in the .eureka home directory to receive changes from upstream

eureka-cli -p combined deployApplication -oq

# Can be simplified without specifying the profile (combined is the default profile)
eureka-cli deployApplication -oq 

Deploys the system without optional containers depending on the profile, such as netcat, kafka-ui, minio, createbuckets, elasticsearch, kibana and ftp-server

• In case you want to update your local repositories of folio-kong, folio-keycloak and platform-complete (UI), you can do so with the combined -bu flags

eureka-cli deployApplication -bu

This will update the cloned projects and force-build Docker images locally before deploying the environment

• System containers can also be built or rebuilt separately from environment deployment. This is particularly useful if you want to verify the images without a full deployment

# Build from the local repositories
eureka-cli buildSystem

# Build from the Git updated local repositories
eureka-cli buildSystem -u

Undeploy the combined application

eureka-cli undeployApplication

Deploy the combined application from AWS ECR

To use AWS ECR as your container registry instead of the public Folio DockerHub, set AWS_ECR_FOLIO_REPO in your environment. When this environment variable is defined, it is assumed that this repository is private and you have also defined credentials in your environment. The value of this variable should be the URL of your repository.

• Set AWS credentials explicitly

export AWS_ACCESS_KEY_ID=<access_key>
export AWS_SECRET_ACCESS_KEY=<secret_key>
export AWS_ECR_FOLIO_REPO=<repository_url>
eureka-cli deployApplication

• Reuse stored AWS credentials found in ~/.aws/config

export AWS_ECR_FOLIO_REPO=<repository_url>
AWS_SDK_LOAD_CONFIG=true eureka-cli deployApplication

See docs/AWS_CLI.md to prepare AWS CLI beforehand

Deploy the ecs application

The ecs application is a standalone application that deploys a UI container for each consortium. By default, it creates 3 tenants for the first consortium (ecs) and 2 tenants for the second one (ecs2). This profile also deploys mod-okapi-facade and mod-search modules along with the elasticsearch system container.

eureka-cli -p ecs deployApplication -oq

Undeploy the ecs application

eureka-cli -p ecs undeployApplication

Deploy the ecs-single application

We can use the ecs-single profile to deploy an environment with just a single consortium. This profile will provision only 3 tenants (i.e. ecs, university and college) with just a single UI container. This profile is preferred over the ecs when there is an obvious resource constraint on the host machine because of how many Kafka topics need to be maintained during and after tenant entitlement.

eureka-cli -p ecs-single deployApplication -oq

Undeploy the ecs-single application

eureka-cli -p ecs-single undeployApplication

Deploy the ecs-migration application

The ecs-migration profile deploys a single consortium with one central and eight member tenants. This profile is primarily used to cross-check production workflows when there are issues reported with the migration to ECS. Because of the number of tenants involved, it is advised to run this profile with the maximum amount of resources to avoid frequent restarts on failure.

eureka-cli -p ecs-migration deployApplication -oq

Undeploy the ecs-migration application

eureka-cli -p ecs-migration undeployApplication

Run IDP migration

# Create/remove IDP users in Keycloak
./migrate_users.sh -a {{create OR delete}} --consortium-id {{consortium uuid}}

The migration progress can be monitored from the federated_identity table in the Keycloak DB

Deploy the import application

The import application is another standalone application that contains a combination of modules required by the team responsible for data-import functionality in FOLIO.

eureka-cli -p import deployApplication -oq

Undeploy the import application

eureka-cli -p import undeployApplication

Deploy child applications

The CLI also supports deploying child applications on top of existing ones. The deployApplication command behaves differently when application.dependencies is set in the config file.

Deploy the export application

• This application contains modules and system containers required for data export functionality that relies on MinIO and FTP

eureka-cli -p export deployApplication

Deploy the search application

• The search application provides Elasticsearch capabilities required by the Inventory App and ECS setup

eureka-cli -p search deployApplication

Deploy the edge application

• The edge application provides modules with an included mod-okapi-facade to work with the Edge API, Karate tests, or with Mosaic integration

eureka-cli -p edge deployApplication

Undeploy child applications

• All child applications can be undeployed with the same undeployApplication command, which will remove both the modules and system containers used by the app

eureka-cli -p {{profile}} undeployApplication

Replace {{app}} or {{profile}} with either of the supported child profiles: export, search or edge

Intercept a module

The Intercept command allows rerouting traffic from a Kong service to a custom sidecar before reaching your local instance started in IntelliJ.

• Start your local module instance in IntelliJ with correct environment variables and JVM flags

• Enable interception to instance in IntelliJ by deploying a custom sidecar

# With custom module and sidecar URLs
eureka-cli interceptModule -n mod-orders -m http://host.docker.internal:36002 -s http://host.docker.internal:37002

# With default module and sidecar URLs (i.e. only with ports)
eureka-cli interceptModule -n mod-orders -gm 36002 -s 37002

# With a different profile, e.g. using the import profile
eureka-cli -p import interceptModule -n mod-orders -gm 36002 -s 37002

• Create and open a new order in the Orders app

• Check the logs of the instance started in IntelliJ; it should now be receiving traffic from the custom sidecar

• Disable interception by redeploying the default containers of both the module and the sidecar into the environment

eureka-cli interceptModule -n mod-orders -r

# With a different profile, e.g. using the import profiles
eureka-cli -p import interceptModule -n mod-orders -r

# Restore using the locally built module image, saved with foliolocal namespace
eureka-cli interceptModule -n mod-orders -r --namespace foliolocal

To intercept multiple modules, make sure to use the right set of environment variables, JVM flags and instance ports for each target module.

Create a port proxy

Create a port proxy (Windows only) to route traffic to a specific deployed sidecar container. This command can help resolve some HTTP client issues in some modules when intercepted by the interceptModule command.

• To create a proxy between your instance deployed in IntelliJ and some sidecar in the environment, pass the module name to which the sidecar is associated with (e.g. mod-inventory-storage), and the external port number of the HTTP server on the sidecar

# Route the traffic from mod-inventory-storage-sc.eureka:8082 on the host network to host.docker.internal:37002 deployed as a container
# both the gateway hostname, i.e. host.docker.internal as well as the sidecar internal port 8082 can be overridden by the command
eureka-cli createPortProxy -n mod-inventory-storage -s 37002

This command assumes that the host, e.g. mod-inventory-storage-sc.eureka is added to /etc/hosts beforehand, because on some corporate machines scripted addition of hosts can be banned by group policies

Upgrade a module

The upgrade command opens up the possibility to either upgrade or downgrade a particular module to a specific SNAPHOT or other versions, including the released ones. In order for it to work, we need to have the Maven CLI configured globally (see how to install and configure Maven for your OS).

• To upgrade a module, pass the module name together with the path to the cloned repository, which we will be use to build the artifact before making the container image

# Here we upgrade mod-orders from 13.1.0-SNAPSHOT.1093 to 13.1.0-SNAPSHOT.1094
eureka-cli -p combined-native upgradeModule -n mod-orders --modulePath ~/Folio/folio-modules/mod-orders

The version is automatically resolved and incremented; image will be built with foliolocal namespace

• If you want to downgrade back to an already prebuilt version (i.e. those that were downloaded from the Docker Hub or AWS ECR), set the desired version together with the correct namespace (e.g. folioci)

# Here we downgrade mod-orders from 13.1.0-SNAPSHOT.1094 back to 13.1.0-SNAPSHOT.1093
eureka-cli -p combined-native upgradeModule -n mod-orders --moduleVersion 13.1.0-SNAPSHOT.1093 --namespace folioci --modulePath ~/Folio/folio-modules/mod-orders

We set namespace to folioci in order to use the existing Docker Hub image

In both cases, the application patch version will be incremented, as this does not have any functional reason for the CLI to roll back. Additionally, if the application is associated with multiple tenant entitlements, all of them will be upgraded to the latest version.

• The upgrade command also has other flags that can be passed in order to skip a certain step in the process.

Other commands

The CLI includes several useful commands to enhance developer productivity. Here are the most important ones that can be used independently.

• List deployed system containers

eureka-cli listSystem

• List deployed modules

# Using the current profile
eureka-cli listModules

# For a particular module and its sidecar in a profile
eureka-cli listModules -n mod-orders

# For only modules in a profile
eureka-cli listModules -y module

# For only sidecars in a profile
eureka-cli listModules -y sidecar

# For only management modules
eureka-cli listModules -y management

# Using all modules for all profiles including mgr-*
eureka-cli listModules -a

• List the available module versions in the registry or fetch a specific module descriptor by version

# List versions for a module
eureka-cli listModuleVersions -n edge-orders

# Get module descriptor for a particular version
eureka-cli listModuleVersions -n edge-orders -i edge-orders-3.3.0-SNAPSHOT.88

# Get module descriptor for a particular version but specify the number of versions to display (the default value is 5) 
eureka-cli listModuleVersions -n edge-orders -i edge-orders-3.3.0-SNAPSHOT.88 -v 10

• Get current Vault Root Token used by the modules

eureka-cli getVaultRootToken

• Get Keycloak Access Token for a tenant

eureka-cli getKeycloakAccessToken -t diku

• Get an Edge API key for a user and tenant

eureka-cli getEdgeApiKey -t diku -x diku_admin

• Reindex inventory and instance record Elasticsearch indices

eureka-cli -p {{profile}} reindexElasticsearch

This command assumes that mod-search module and elasticsearch system container are deployed or if {{profile}} is being replaced by either search, ecs, ecs-single or ecs-migration profiles

• Check if module internal ports are accessible

eureka-cli checkPorts

The CLI also exposes an internal port 5005 for all modules and sidecars that can be used for remote debugging in IntelliJ

Using a custom folio-module-sidecar

If your workflow relies on a custom implementation of folio-module-sidecar, the CLI also supports deploying an environment with sidecars using a custom Docker image.

• Git clone folio-module-sidecar from GitHub

git clone https://github.com/folio-org/folio-module-sidecar.git

• Apply your changes locally & build a custom local image

cd folio-module-sidecar
mvn clean package -DskipTests
docker build --tag custom-folio-module-sidecar:1.0.0 .

This example uses a non-native image build, see https://github.com/folio-org/folio-module-sidecar/blob/master/README.md for how to build a native Docker image

• Use the newly built custom-folio-module-sidecar:1.0.0 local image in your config by setting sidecar-module.custom-namespace to true

sidecar-module:
  image: custom-folio-module-sidecar
  version: 1.0.0
  custom-namespace: true

The version must be set explicitly

• Deploy the environment with this config, in our example we deploy an edge application with custom-folio-module-sidecar:1.0.0 sidecars

eureka-cli -p edge deployApplication

• Check the sidecar image version after application deployment

eureka-cli -p edge listModules

Using a native folio-module-sidecar

The CLI also supports using native sidecars built with GraalVM. These sidecars have a different and lighter resource profile, making them ideal for deployments with only a few resources to spare.

• Git clone folio-module-sidecar from GitHub

git clone https://github.com/folio-org/folio-module-sidecar.git

• Build the artifact locally

cd folio-module-sidecar
mvn clean install -Pnative -DskipTests \
  -Dquarkus.native.remote-container-build=true \
  -Dquarkus.native.builder-image=quay.io/quarkus/ubi-quarkus-mandrel-builder-image:jdk-21

This builds a native binary using a container-based GraalVM with a Linux toolchain

• Build a custom local Docker image

docker build -f docker/Dockerfile.native-micro -t folio-module-sidecar-native .

• Use the newly built folio-module-sidecar-native:latest local image in your config by setting sidecar-module.custom-namespace to true and sidecar-module.native-binary-cmd with valid args

sidecar-module:
  image: folio-module-sidecar-native
  version: latest
  custom-namespace: true
  native-binary-cmd: [
    "./application", "-Dquarkus.http.host=0.0.0.0", "-Dquarkus.log.category.'org.apache.kafka'.level=INFO"
  ]

The version must be set explicitly

• Deploy the environment using the combined-native profile that already has JAVA_OPTIONS env var removed from the sidecar-module in the config, as this is not interpreted by the substrate VM in the image

eureka-cli -p combined-native deployApplication

Using local backend module images

When developing backend modules locally, you can deploy them with custom module descriptors without pushing to a registry.

• Build your module locally and generate a module descriptor

cd <module-directory>
mvn clean package -DskipTests
docker build --tag <module-name>:<version> .

• Configure the module to use the local descriptor in your config file

backend-modules:
  <module-name>:
    version: "<version>"
    local-descriptor-path: "/path/to/module/target/ModuleDescriptor.json"

When local-descriptor-path is specified, the Docker image will not be pulled from a registry and the descriptor will be loaded from the local filesystem

• Deploy the environment with your local module

eureka-cli deployApplication

Using local frontend module descriptors

• To use a local frontend module descriptor, add local-descriptor-path to the module config

frontend-modules:
  folio_users:
    version: "<version>"
    local-descriptor-path: "/path/to/ui-module/module-descriptor.json"

• Deploy the environment with your local module

eureka-cli deployApplication

Using the UI

The environment depends on the platform-complete project to combine and assemble frontend and backend modules into a single UI package. By default, the CLI uses a pre-built Docker image of platform-complete from DockerHub to deploy the UI container.

• If there is a need to use a different namespace, override the namespaces.platform-complete-ui key in the config, for example in config.combined.yaml

namespaces:
  platform-complete-ui: bkadirkhodjaev # Change to pull from a different namespace if necessary

• If you haven't built the image yet, the CLI has a dedicated command to build the UI image separately from the deployment lifecycle

eureka-cli buildAndPushUi -n {{namespace}} -t diku -u

Replace {{namespace}} with your DockerHub namespace of choice, and use -u flag only if you want to update your local repository with upstream changes

• To use the newly built image, remove the old container and create a new one

eureka-cli undeployUi
eureka-cli deployUi

This will pull the latest Docker image from the registry and create a UI container out of it

The CLI also supports building and deploying the UI image in-place, during either deployApplication execution or with deployUi command.

# Will build and deploy every image including folio-kong, folio-keycloak and platform-complete itself
eureka-cli deployApplication -b -u

# Will only build and deploy the platform-complete image
eureka-cli deployUi -b -u

Using Single Tenant UX

Single tenant UX is by default enabled for both ecs, ecs-single and ecs-migration profiles. This functionality allows users in member tenants to automatically log in to their respective tenant spaces from a single user login form configured for the central tenant. Under the hood, the implementation behind Single Tenant UX uses shadow users created in the central tenant and the Keycloak realm to perform authentication using the correct member tenant identity provider.

• To disable this functionality from running automatically during the deployment, set SINGLE_TENANT_UX from true to false for both mod-users-keycloak and mod-consortia-keycloak backend modules

Using the environment

• Access the UI from http://localhost:3000 using diku_admin username and admin password

• After successful login, the UI can be used like any other FOLIO application

If your environment was deployed using the ecs profile, your consortiums are represented by two different UI instances.

• The first instance can be accessed from http://localhost:3000 using ecs_admin username and admin password

It contains 3 tenants, ecs central tenant and university and college member tenants

• And the second one can be accessed from http://localhost:3001 (via an incognito Chrome browser) using ecs_admin2 username and admin password

It contains 2 tenants, ecs2 central tenant and university2 member tenant

• Kong gateway is available at http://localhost:8000 and can be used to get an access token directly from the backend

# Admin user: diku_admin
curl --request POST \
  --url http://localhost:8000/authn/login-with-expiry \
  --header 'Content-Type: application/json' \
  --header 'X-Okapi-Tenant: diku' \
  --data '{"username":"diku_admin","password": "admin"}' \
  --verbose

# Limited user: diku_user
curl --request POST \
  --url http://localhost:8000/authn/login-with-expiry \
  --header 'Content-Type: application/json' \
  --header 'X-Okapi-Tenant: diku' \
  --data '{"username":"diku_user","password": "user"}' \
  --verbose

Using combined, combined-native or import standalone profiles, because these profiles create diku_admin and diku_user users

# Admin user: ecs_admin
curl --request POST \
  --url http://localhost:8000/authn/login-with-expiry \
  --header 'Content-Type: application/json' \
  --header 'X-Okapi-Tenant: ecs' \
  --data '{"username":"ecs_admin","password": "admin"}' \
  --verbose

# Admin user: ecs_admin2
curl --request POST \
  --url http://localhost:8000/authn/login-with-expiry \
  --header 'Content-Type: application/json' \
  --header 'X-Okapi-Tenant: ecs2' \
  --data '{"username":"ecs_admin2","password": "user"}' \
  --verbose

• Using an ecs profile that creates ecs_admin and ecs_admin2 users in different consortiums

Troubleshooting

General

If there are multiple instances of a container daemon (e.g. Rancher Desktop, Docker Desktop, Podman) running on the host machine:

• Verify that DOCKER_HOST is set to point to the correct daemon (otherwise /var/run/docker.sock will be used)

Vault UI does not have a Userpass sign-in method or login fails with admin/admin credentials

• Your local Vault image is outdated, update the git repository of the CLI, rebuild the binary for your platform of choice and run eureka-cli buildSystem -u once before deploying any application

Command-based

Shell commands are failing to execute

• Verify that all shell scripts located under ~/eureka/misc folder are saved using the LF (Line Feed) line break

Module readiness checks are failing

• Verify that host.docker.internal is set in /etc/hosts and accessible on the host network
• Or set application.gateway-hostname in the config to either your physical network IP or some locally accessible hostname

"Bind for 0.0.0.0:XXXXX failed: port is already allocated."

• Verify that the config port range is free from running processes (e.g. from some opened Kubernetes NodePort on port 30102)
• Or reassign application.port-start and application.port-end in the config to a different range, e.g. to 20000-20999

"Failed to load module descriptor by url: <https://folio-registry.dev.folio.org/_/proxy/modules/mod-XXX>"

• Verify that the module descriptor for the latest snapshot version already exists in the registry (can check with eureka-cli listModuleVersions command)
• Or set a fixed module version in the config (i.e. using <module>.version)

"The module is not entitled on tenant ..."

• Rerun the deployment again with more available RAM

When trying to deploy with eureka-cli deployApplication -bu or building with eureka-cli buildSystem -u (retry if fails on Error: worktree contains unstaged changes):

ERROR: unable to select packages:
  bind-tools-9.18.41-r0:
    breaks: world[bind-tools=9.18.39-r0]

• Update your local CLI git repository and rebuild the binary; our Dockerfiles in the misc folder are no longer dependent on pinned and non-deterministic package versions of Alpine Linux

---

Additional Resources

• Module Development Guide - Comprehensive guide for using interceptModule and upgradeModule commands with workflows, examples, and troubleshooting
• Build Binary Guide - Instructions for building platform-specific binaries
• CLI Development Setup Guide - Live compilation and VSCode debugging setup for CLI development
• AWS CLI Setup Guide - Using AWS ECR as container registry
• Windows WSL Guide - Configuring WSL2 on Windows