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-compose CLI version

Python

Preparing the environment

Setting up credentials

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

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:

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):

Changing module versions

This variables can be overwritten in .env.local:

NOTE: Folio module versions are populated with the following script (based on application descriptor):

Update module versions

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

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:

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:

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:

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

Checklist before going to the next step:

1. Database must be available with configured admin client (credentials: postgres:{{POSTGRES_PASSWORD}}):

2. Check Keycloak admin dashboard (credentials: admin:{{KC_ADMIN_PASSWORD}}):

   NOTE: If keycloak is not available (502 Bad Gateway), try to execute:
   ./dc.sh restart keycloak

3. Check Kong Manager Dashboard:

   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

4. Check Kafka UI:

5. Check Vault:

Unseal token can be retrieved with script:

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:

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:

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)

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

• To expose your pre-defined variables to current terminal

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

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

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):

• Verify that mgr-components are available (Optional)

  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:

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

app-platform-minimal discovery information

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

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

(Optional) Stored application discovery information

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:

Running containers

The following command will run containers that belongs to 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:

Command to get test tenant id:

This command should print tenant identifier

Enable (entitle) app-platform-minimal for tenant

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

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

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:

Create a user: folio

Create folio user credentials

Login folio user