eureka-platform-bootstrap

Provides docker-based minimal eureka platform

Run applications in docker

Required tools:

Docker
Python v3.10+ and pip
Java 17
Maven

Script environment variables

This variables can be overwritten in .env.local.credentials

Variable	Default value	Description
POSTGRES_PASSWORD	postgres_admin	Postgres Database password
KC_DB_PASSWORD	keycloak_admin	Keycloak database password
KONG_DB_PASSWORD	kong_admin	Kong database password
OKAPI_DB_PASSWORD	okapi_admin	Okapi database password (all modules will use this database to create tenant specific schemas)
MGR_APPLICATIONS_DB_PASSWORD	mgr_applications_admin	mgr-applications database password
MGR_TENANTS_DB_PASSWORD	mgr_tenants_admin	mgr-tenants database password
MGR_TENANT_ENTITLEMENTS_DB_PASSWORD	mgr_tenant_entitlements_admin	mgr-tenant-entitlements database password
KC_ADMIN_PASSWORD	admin	Keycloak admin password
KC_ADMIN_CLIENT_SECRET	be-admin-client-secret	Keycloak admin client secret

NOTE: It is recommended to generate your own set of credentials for a new deployment instead of using default values, see how to generate deployment credentials.

This variables can be overwritten in .env.local:

Module versions

Variable	Default value	Description
KC_LOGIN_CLIENT_SUFFIX	-login-app	a suffix for a tenant client that will perform all authentication and authorization requests
KC_SERVICE_CLIENT_ID	m2m-client	Name of service client (participated in module-to-module requests)
KC_ADMIN_CLIENT_ID	be-admin-client	Keycloak admin client id
MGR_TENANTS_VERSION	latest	Docker image version for `mgr-tenants`
MGR_TENANTS_VERSION	latest	Docker image version for `mgr-tenants`
MGR_TENANTS_REPOSITORY	folioci/mgr-tenants	Docker repository for `mgr-tenants`
MGR_APPLICATIONS_VERSION	latest	Docker image version for `mgr-applications`
MGR_APPLICATIONS_REPOSITORY	folioci/mgr-applications	Docker repository for `mgr-applications`
MGR_TENANT_ENTITLEMENTS_VERSION	latest	Docker image version for `mgr-tenant-entitlements`
MGR_TENANT_ENTITLEMENTS_REPOSITORY	folioci/mgr-tenant-entitlements	Docker repository for `mgr-tenant-entitlements`
FOLIO_MODULE_SIDECAR_VERSION	latest	Docker image version for `folio-module-sidecar`
FOLIO_MODULE_SIDECAR_REPOSITORY	folioci/folio-module-sidecar	Docker repository for `folio-module-sidecar`

NOTE: Folio module versions are populated with the following script (based on application descriptor):
python ./misc/docker-module-updater/run.py

Hosts file configuration

Keycloak and kafka uses specific settings in this deployment that prevents them accessing locally. To make it possible, hosts file must be updated with following lines:

127.0.0.1     keycloak
127.0.0.1     kafka

Additional images build

Additional images are required to built before running eureka-platform-bootstrap in docker.

This command will build custom vault image, with autoconfiguration for initial credentials:

sh ./misc/build-images.sh

Before all the steps, make sure that you are in the docker directory:

cd docker

Generate local credentials and configuration

To set local credentials and configuration a following script must be executed:

sh ./set-local-credentials.sh

NOTE: This step is optional, however it will provide more secure deployment for local development In addition, once credentials is set and core profile is running - changing them will break deployment, and the workaround is to manually update them in .env.local.crendentials and in corresponding container or to start deployment from scratch by removing docker volumes (before executing a script - deployment must be stopped with ./stop-docker-containers.sh):
docker volume rm -f folio-platform-minimal_db folio-platform-minimal_kafka-data folio-platform-minimal_vault-data

Update module versions

NOTE: This step is optional, execute the following command only if you have modified app-platform-miniaml module descriptor

python ../misc/docker-module-updater/run.py

Deploying core services

Executing the following command will run containers for core infrastructure for Eureka deployment:

Database (PosgreSQL with configured databases and credentials)
api-gateway: Kong
Keycloak (cluster deployment 1 node + load balancer (nginx))
Apache Kafka + Kafka UI

./start-docker-containers.sh -p core

Checklist before going to the next step:

Database must be available with configured admin client (credentials: postgres:{{POSTGRES_PASSWORD}}):
```
jdbc:postgresql://localhost:5432/postgres
```
Check Keycloak admin dashboard (credentials: admin:{{KC_ADMIN_PASSWORD}}):
```
http://localhost:8080
```
NOTE: If keycloak is not available (502 Bad Gateway), try to execute:
./dc.sh restart keycloak
Check Kong Manager Dashboard:
```
http://localhost:8002
```
NOTE: If kong is not available, removing it by ./dc.sh down api-gateway and then enabling it again with ./dc.sh up --data api-gateway should resolve this issue
Check Kafka UI:
```
http://localhost:9080
```
Check Vault:

http://localhost:8200/

Unseal token can be retrieved with script:

sh ./misc/get-vault-token.sh

Deploying mgr-components

Before initializing mgr-components, Vault access must be provided via env variable - SECRET_STORE_VAULT_TOKEN. The following script will populate it in .env.local:

sh ./misc/populate-vault-token.sh

NOTE: All local configuration lives in .env.local file, in the docker/ directory, if you want to customize deployment - use this file, it is excluded from git, so pulling latest changes from master or other branches will be simple.

NOTE: mgr-components versions can be re-configured with following env variables in .env.local:
export MGR_TENANTS_VERSION={{newVersion}}
export MGR_TENANTS_REPOSITORY={{newRepositoryName}}
export MGR_APPLICATIONS_VERSION={{newVersion}}
export MGR_APPLICATIONS_REPOSITORY={{newRepositoryName}}
export MGR_TENANT_ENTITLEMENTS_VERSION={{newVersion}}
export MGR_TENANT_ENTITLEMENTS_REPOSITORY={{newRepositoryName}}
eureka-platform-bootstrap uses the latest tag from folioci docker public registry, to update and pull the latest tags sh ./docker/dc.sh pull can be used.

Executing this command will run containers for:

mgr-tenants (tenant management)
mgr-applications (application management + discovery management)
mgr-tenant-entitlements (tenant application management)

./start-docker-containers.sh -p mgr-components

Wait until they are available:

curl -w"\n\n" -sS --retry-all-errors --retry 10 -D - http://localhost:9901/admin/health
curl -w"\n\n" -sS --retry-all-errors --retry 8 -D - http://localhost:9902/admin/health
curl -w"\n\n" -sS --retry-all-errors --retry 8 -D - http://localhost:9903/admin/health

Adding a new application to mgr-applications will require following steps:

To expose your pre-defined variables to current terminal
```
source .env.local
```

Get system access token:
This token is used to communicate with mgr-components

export KC_ADMIN_CLIENT_ID={{value from .env.local, if not defined - from .env}}
export KC_ADMIN_CLIENT_SECRET={value from .env.local.credentials, if not defined - from .env}

If you have not set up local credentials, you can use default values:

export KC_ADMIN_CLIENT_ID=be-admin-client
export KC_ADMIN_CLIENT_SECRET=be-admin-client-secret

systemAccessToken=$(curl -X POST --silent \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=${KC_ADMIN_CLIENT_ID}" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_secret=${KC_ADMIN_CLIENT_SECRET}" \
  "http://keycloak:8080/realms/master/protocol/openid-connect/token" \
  | jq -r ".access_token")

NOTE: Access token lifespan can be increased in Keycloak to 30 minutes:

Login to keycloak

Select master realm

Then go to Realm Settings -> Tokens -> Access Tokens

Increase the value of Access Token Lifespan

The following command will print access token value (Optional):

echo "$systemAccessToken"

Verify that mgr-components are available (Optional)

curl -X GET --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  "http://localhost:8000/tenants" | jq

curl -X GET --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  "http://localhost:8000/applications" | jq

curl -X GET --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  "http://localhost:8000/entitlements" | jq

NOTE: Responses must be 200 OK, if not - check the container logs to find the issue

app-platform-minimal application registration

app-platform-minimal contains basic functionality for Eureka platform:

User and AuthUsers management (mod-users-keycloak + mod-users + mod-users-bl)
Authentication and authorization (keycloak + mod-login-keycloak + sidecars)
Capability/Role/Policy management (mod-roles-keycloak)
Scheduled timers support (mod-scheduler)
Notes (mod-notes)
Tenant settings management (mod-settings)

When the previous step is finished, mgr-applications is ready to accept applications, and sidecars will require pre-defined application to load bootstrap information.

Registration of application descriptor

This command adds app-platform-minimal to mgr-applications:

curl -X POST --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  --data "@../descriptors/app-platform-minimal/descriptor.json" \
  "http://localhost:8000/applications" | jq

NOTE: Created application can be retrieved using the following command:

curl -X GET --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  "http://localhost:8000/applications/app-platform-minimal-0.0.17-SNAPSHOT.2?full=true" | jq

app-platform-minimal discovery information

This command will provide discovery information for all modules in app-platform-minimal:

curl -X POST --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  --data "@../descriptors/app-platform-minimal/discovery.json" \
  "http://localhost:8000/modules/discovery" | jq

NOTE: Created application discovery data can be retrieved using the following command:

(Optional) Stored application discovery information
curl -X GET --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  "http://localhost:8000/applications/app-platform-minimal-0.0.17-SNAPSHOT.2/discovery?limit=100" | jq

app-platform-minimal deployment

NOTE: it's also possible to run native image build by following the instruction in folio-module-sidecar project, image values can be customized in .env.local:
export FOLIO_MODULE_SIDECAR_VERSION={{folio-module-sidecar-version}}
export FOLIO_MODULE_SIDECAR_REPOSITORY={{folio-module-sidecar-repostitory}}

Running containers

The following command will run containers that belongs to app-platform-minimal:

./start-docker-containers.sh -p app-platform-minimal

NOTE: Verify manually that all containers started without any errors by checking logs of each container and sidecars (mod- and sc- prefixes in search)

Create a tenant

The following command will create and save tenant id as variable:

curl -X POST --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  --data '{"name": "test", "description": "Test Tenant"}' \
  "http://localhost:8000/tenants" | jq

Command to get test tenant id:

testTenantId=$(curl -X GET --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  "http://localhost:8000/tenants?query=name==test" | jq -r ".tenants[0].id")

This command should print tenant identifier

echo "${testTenantId}"

Enable (entitle) app-platform-minimal for tenant

The following command will install app-platform-minimal for prepared test tenant:

curl -X POST --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  --data '{"tenantId": "'"${testTenantId}"'", "applications": [ "app-platform-minimal-0.0.17-SNAPSHOT.2" ] }' \
  "http://localhost:8000/entitlements?ignoreErrors=true" | jq

Await for successful result, entitlements for tenant can be checked with command

curl -X GET --silent \
  --header "Content-Type: application/json" \
  --header "x-okapi-token: ${systemAccessToken}" \
  "http://localhost:8000/entitlements?query=tenantId=${testTenantId}" | jq

Creating a user

Generate a module-to-module client secret

This JWT token provides admin access to folio system (all permissions included)

NOTE: By default name of client is: sidecar-module-access-client, but it can be redefined by variable: KC_SERVICE_CLIENT_ID

{{KC_SERVICE_CLIENT_SECRET}} can be obtained from Vault or from Keycloak.

Vault service client secret retrieval

To retrieve service client secret from vault

Open Vault at http://localhost:8200/ui/vault/secrets
Open following folder in sequence: secret/ -> folio/ -> test/
Copy data from ${KC_SERVICE_CLIENT_ID} field (m2m-client by default)

Keycloak service client retrieval

To retrieve service token from Keycloak:

Login to keycloak
Select test realm
Then go to Clients -> ${KC_SERVICE_CLIENT_ID} Client (m2m-client by default) -> Credentials
Copy value from Client Secret field

Generating service access token

export environment variables:

export KC_SERVICE_CLIENT_ID={{value from .env.local, if not defined - from .env}}
export KC_SERVICE_CLIENT_SECRET={{value from previous step}}

accessToken=$(curl -X POST --silent \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=${KC_SERVICE_CLIENT_ID}" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_secret=${KC_SERVICE_CLIENT_SECRET}" \
  "http://keycloak:8080/realms/test/protocol/openid-connect/token" \
  | jq -r ".access_token")

Create a user: folio

user=$(curl -X POST --silent \
  --header 'x-okapi-tenant: test' \
  --header 'Content-Type: application/json' \
  --header "x-okapi-token: ${accessToken}" \
  --data-raw '{
      "active": true,
      "departments": [],
      "proxyFor": [],
      "type": "patron",
      "username": "folio",
      "personal": {
        "lastName": "Test",
        "firstName": "Test",
        "email": "[email protected]",
        "addresses": []
      }
    }' \
  'http://localhost:8000/users-keycloak/users')

echo $user | jq

Create folio user credentials

user_id=$(echo $user | jq -r ".id")

curl -X POST --silent  \
  --header 'x-okapi-tenant: test' \
  --header 'Content-Type: application/json' \
  --header "x-okapi-token: ${accessToken}" \
  --data '{ "username": "folio", "userId": "'${user_id}'", "password": "folio" }' \
  'http://localhost:8000/authn/credentials' | jq

Login folio user

curl -X POST --silent  \
  --header 'x-okapi-tenant: test' \
  --header 'Content-Type: application/json' \
  --data '{ "username": "folio", "password": "folio" }' \
  'http://localhost:8000/authn/login' | jq

Additional images

Additional images are build with the following command:

sh ./misc/build-images.sh

This image provides HashiCorp Vault container (with some automation) to store secret for Folio platform

folio-module-sidecar

Miscellaneous scripts

module-updater

Updates docker deployment and discovery information versions according to the Application Descriptor

python ./misc/docker-module-updater/run.py

images-builder

Run the following command to build the images for you current platform architecture from the eureka-platform-bootstrap folder: More: Images Builder

./misc/images-builder/build.sh

Remove all docker volumes related to the deployment

Run the following command to remove all docker volumes related to the deployment:

./docker/remove-folio-platform-volumes.sh

Module version actualizer

This script updates module versions in the application descriptor (descriptor.json) to the latest SNAPSHOT or release versions available in the FOLIO Registry. Choose whether to use SNAPSHOT versions (y) or stable releases (n).

python3 misc/module-version-actualizer/run.py

Single command to deploy local environment

The script deploys local environment with default settings. Covered steps:

Start core services
Start mgr-components
Register app-platform-minimal application
Deploy app-platform-minimal
Create a test tenant
Enable app-platform-minimal application for tenant

Run the following command to deploy local environment:

./start.sh

Verified versions

Docker version

> docker version

Client: Docker Engine - Community
 Version:           27.1.1

Server: Docker Engine - Community
 Engine:
  Version:          27.1.1
  API version:      1.46 (minimum version 1.24)

Docker-compose CLI version

> docker compose version
Docker Compose version v2.29.1

Python

> python --version
Python 3.10.12

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github		.github
descriptors/app-platform-minimal		descriptors/app-platform-minimal
docker		docker
misc		misc
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
NEWS.md		NEWS.md
README.md		README.md
start.sh		start.sh

License

folio-org/eureka-platform-bootstrap

Folders and files

Latest commit

History

Repository files navigation