Single Server Fresh Install
- 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.1.1 Verified versions
- 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.1 Installing dependencies
- 4 Post-Installation Tasks
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 |
---|---|---|
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 |
---|---|---|
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_VERSION | latest | Docker image version for |
MGR_TENANTS_REPOSITORY | folioci/mgr-tenants | Docker repository for |
MGR_APPLICATIONS_VERSION | latest | Docker image version for |
MGR_APPLICATIONS_REPOSITORY | folioci/mgr-applications | Docker repository for |
MGR_TENANT_ENTITLEMENTS_VERSION | latest | Docker image version for |
MGR_TENANT_ENTITLEMENTS_REPOSITORY | folioci/mgr-tenant-entitlements | Docker repository for |
FOLIO_MODULE_SIDECAR_VERSION | latest | Docker image version for |
FOLIO_MODULE_SIDECAR_REPOSITORY | folioci/folio-module-sidecar | Docker repository for |
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:
Database must be available with configured admin client (credentials:
postgres:{{POSTGRES_PASSWORD}}
):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
Check Kong Manager Dashboard:
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 issueCheck Kafka UI:
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 thedocker/
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 tagssh ./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