1 Overview
2 System Requirements
3 Installation Steps
- 3.1 Installing dependencies
  - 3.1.1 Verified versions
    - 3.1.1.1 Docker version
    - 3.1.1.2 Docker-compose CLI version
    - 3.1.1.3 Python
- 3.2 Preparing the environment
  - 3.2.1 Setting up credentials
  - 3.2.2 Changing module versions
  - 3.2.3 Update module versions
  - 3.2.4 Hosts file configuration
  - 3.2.5 Additional images build
- 3.3 Setting up core services: DB, Kafka, Keycloak, Kong
- 3.4 Deploying mgr-components
- 3.5 Deploying FOLIO modules
  - 3.5.1 app-platform-minimal application registration
  - 3.5.2 Registration of application descriptor
    - 3.5.2.1 app-platform-minimal discovery information
  - 3.5.3 app-platform-minimal deployment
    - 3.5.3.1 Running containers
4 Post-Installation Tasks
- 4.1 Verifying installation
- 4.2 Create a tenant
  - 4.2.1 Enable (entitle) app-platform-minimal for tenant
- 4.3 Creating a user
  - 4.3.1 Generate a module-to-module client secret
    - 4.3.1.1 Vault service client secret retrieval
    - 4.3.1.2 Keycloak service client retrieval
    - 4.3.1.3 Generating service access token
  - 4.3.2 Create a user: folio
  - 4.3.3 Create folio user credentials
  - 4.3.4 Login folio user

Overview

This document explains how to setup a Folio environment on a single machine using Docker.

System Requirements

Memory and CPU:
Minimum 16GB RAM, Core i7 quadcore CPU.
Recommended: 32GB RAM, Core i7 quadcore+/Apple Silicon M2+.
Disk Space: minimum 32 GB

Installation Steps

Installing dependencies

Setup required tools:

Docker
Python v3.10+ and pip
Java 17
Maven

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

Preparing the environment

Setting up credentials

Use file .env.local.credentials to override these variables:

Variable	Default value	Description

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	keycloak_system_admin	Keycloak admin password
KC_ADMIN_CLIENT_SECRET	be-admin-client-secret	Keycloak admin client secret

It is recommended to generate your own set of credentials for a new deployment instead of using default values.

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 are 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

Changing module versions

This variables can be overwritten in .env.local:

Variable	Default value	Description

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

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

Hosts file configuration

Keycloak and Kafka use specific settings in this deployment that prevent them from being accessed 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

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

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

cd docker

Setting up core services: DB, Kafka, Keycloak, Kong

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-gatewayand 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

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

Deploying FOLIO modules

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)

Post-Installation Tasks

Verifying installation

In order to verify manager components deployment, see “Verify that mgr-components are available (Optional)” step above.

For module and sidecar deployments, verify manually that all containers have been started without any errors - by checking logs of each container for modules 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": "test_user@example.com",
        "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

Single Server Fresh Install