Single Server Install with Containers

This guide explains how to start a small Eureka-based FOLIO environment on one machine using Docker Compose. It is intended for development, demos, and platform exploration. It is not a production deployment guide.

The setup is provided by the eureka-platform-bootstrap repository https://github.com/folio-org/eureka-platform-bootstrap . The normal installation path is the repository's ./start.sh script, which performs the bootstrap steps for you.

Overview

The local container environment includes:

• PostgreSQL for platform and module databases

• Kong as the API gateway

• Keycloak for identity and access management

• Kafka and Kafka UI

• Vault for local secret storage

• Eureka manager components:

  • mgr-applications

  • mgr-tenants

  • mgr-tenant-entitlements

• app-platform-minimal, a small application set that includes users, login, roles, settings, notes, scheduler, and supporting sidecars

The bootstrap script starts the required services, registers the application, deploys the minimal module set, creates a test tenant, and entitles that tenant to the application.

System Requirements

Use a machine that can comfortably run a local multi-container Java stack. If containers are killed by Docker, fail health checks, or restart repeatedly, increase the CPU and memory available to Docker before debugging individual services.

Install these tools before starting:

• Docker

• Docker Compose v2

• docker-compose compatibility command

• Python 3.10 or later

• Java 21 or later

• Maven

• jq

• curl

The bootstrap script checks for both docker compose and the older docker-compose command. If your Docker installation only provides docker compose, install the compatibility command before using ./start.sh.

On macOS with Apple Silicon, the script may offer to build ARM-compatible images locally. Use that option if the published images do not run cleanly on your machine.

Installation Steps

Setting up Docker

Clone the repository and enter it:

Make sure Docker is running:

The local Keycloak and Kafka configuration expects these host names to resolve to the local machine:

The ./start.sh script can add these entries for you. If you prefer to manage the hosts file yourself, add them before starting the containers.

Configuring Docker Compose

Most users do not need to edit Docker Compose files before the first run.

The main configuration files are in the docker directory:

• docker/.env contains default image names, versions, credentials, service URLs, and Compose settings.

• docker/.env.local is for local overrides such as image versions or repositories.

• docker/.env.local.credentials is for local database and Keycloak secrets.

• docker/dc.sh loads local configuration and runs Docker Compose with the repository's Compose files.

For the normal ./start.sh path, use the default local credentials that the script creates. Those defaults are intended for disposable local environments only.

The main Compose profiles are:

Deploying FOLIO containers

From the repository root, run:

The script performs the local bootstrap flow:

1. Checks required tools.

2. Prepares local configuration and credentials.

3. Builds the local Vault image.

4. Starts the core services.

5. Starts the manager components.

6. Registers app-platform-minimal and its discovery data.

7. Starts the application modules and sidecars.

8. Creates a test tenant.

9. Entitles app-platform-minimal to test tenant.

During startup the script may ask whether to update module versions in the application descriptor. On Apple Silicon, it may also ask whether to build ARM-compatible images locally.

If you need to run the same process step by step, use the manual flow in the repository README: Run applications in docker https://github.com/folio-org/eureka-platform-bootstrap#run-applications-in-docker .

Post-Installation Tasks

Verifying the deployment

After ./start.sh finishes, check the manager component health endpoints:

The responses should be successful HTTP responses.

Useful local URLs:

To inspect the running containers:

To check logs for a service:

Managing containers

Run these commands from the root project directory.

Stop containers:

Remove local deployment volumes when you need a clean restart:

Start the configured profiles again:

Troubleshooting common issues

Keycloak is not available

Confirm that the keycloak host name resolves locally:

If Keycloak is not reachable or the browser shows 502 Bad Gateway, restart the Keycloak load balancer container:

Then check the logs:

Kong is not available

Check the gateway container and logs:

If the container is unhealthy, recreate it after the database is healthy:

Manager components cannot read secrets

The manager components need a Vault token in local configuration. After the core profile is running, populate the token and restart the manager components:

Requests fail through the gateway

If containers are running but gateway requests fail, check that application and discovery data were registered. The sidecars use discovery data from mgr-applications; routing will not work correctly if that data is missing.

For detailed registration commands, see the repository README: app-platform-minimal application registration https://github.com/folio-org/eureka-platform-bootstrap#registration-of-application-descriptor .

Apple Silicon image problems

If a Java module image fails immediately on Apple Silicon, build local images for the current architecture:

Then override the affected image repository or tag in docker/.env.local and start the relevant profile again.

A clean restart is needed

Stop the containers and remove deployment volumes:

Then run the normal startup flow again: