elm-sync Installation

Please note: elm-sync is a stateful app that can only be run as a single node per CDCM <> ELM instance, but it can sync N configuration areas from CDCM to N ELM Project Areas.

This guide provides detailed instructions for installing and configuring the Smartfacts ELM Sync application using Docker.

Prerequisites

• Docker and Docker Compose

• Access to a Keycloak instance for authentication

Installation

1. Create a directory for ELM Sync:

   mkdir elmsync cd elmsync

2. Create a data directory for the SQLite database:

   mkdir data

3. Create an application.yml file using the example provided in example-application.yml

   • Modify all necessary configuration parameters

4. Create or modify docker-compose.yaml:

   version: '3.8' services: elmsync: image: ${your_docker_registry}/elmsync:latest ports: - "8080:8080" volumes: - ./data:/opt/elmsync/data - ./application.yml:/opt/elmsync/application.yml restart: unless-stopped

5. Start the container:

   docker compose up -d

6. Verify the installation:

   docker compose logs -f

Configuration Reference

See elm-sync Configuration for details on elm-sync configuration parameters. The essential parameters that need to be set in application.yml are summarized here.

Essential Configuration Parameters

• elm-sync.instance.name: Unique identifier for your sync instance

• elm-sync.max-number-of-retries: Number of retry attempts (default: 100)

• elm-sync.retry-backoff: Delay between retries in milliseconds (default: 100)

Security Configuration

Configure the OAuth2/Keycloak settings under spring.security.oauth2:

• client.registration.custom.client-id

• client.registration.custom.client-secret

• client.provider.custom.issuer-uri

Database Configuration

The application uses SQLite which is automatically managed in the Docker container:

• Database path is configured as /opt/elmsync/data/elmsync.db

• Data persistence is handled through the Docker volume mount

Troubleshooting

1. Container Won't Start

   • Check Docker logs: docker compose logs -f

   • Verify Docker volume permissions

   • Ensure all required ports are available

2. Authentication Issues

   • Verify Keycloak configuration in application.yml

   • Check client credentials

   • Ensure the Keycloak instance is accessible from the container

3. Database Issues

   • Check Docker volume mount permissions

   • Verify the data directory exists and is writable

   • Ensure the Docker container has proper permissions

Support

For additional support or to report issues, please contact your Smartfacts representative or visit our support portal.

Updating Settings Guide: elm-sync update settings guide