Single Server Fresh Install

Owned by Ievgeniia Lymar
Last updated: Nov 14, 2024 by Mykola Makhin
7 min read

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:

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:

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

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 manag