Deploying and Configuring Solace Schema Registry with Docker or Podman

This section explains how to install and run Solace Schema Registry using either Docker or Podman.

• Understanding the Schema Registry Package
• Prerequisites
• Localhost Deployment
• Custom Hostname Deployment
• Authentication
• Monitoring and Metrics
• Troubleshooting

Prerequisites

Container deployments require adequate host resources and proper configuration to ensure optimal performance. Review the following system and software requirements before proceeding with deployment.

Software Requirements

• You must have either Docker 20.10+ or Podman 3.0+ installed and running on your system.

Downloading and Extracting Solace Schema Registry

Download Solace Schema Registry (schema-registry-v<version>.tar.gz) from the Solace Products website using your Solace Products website account. The schema-registry-v<version>.tar.gz file is a distribution package containing both Docker/Podman and Kubernetes/Helm deployment options.

You must extract the schema-registry-v<version>.tar.gz file and load the Docker images before deployment:

1. Extract the downloaded package and navigate to the extracted directory:

   tar -xzf schema-registry-v<version>.tar.gz
   cd schema-registry-v<version>

2. Load all Docker images following the platform-specific instructions in the README.md file in the root of the extracted package. The README provides commands for:
   • Docker (Linux/Mac and Windows)
   • Podman (Linux/Mac)
   The package contains three separate Docker images that must all be loaded before deployment.
3. Extract the Docker Compose configuration files:

   cd compose-files
   tar -xzf solace-schema-registry-dist.tar.gz

   This extracts the compose.yaml files, .env configuration file, and supporting files needed for deployment.
   For detailed Docker Compose deployment examples and configuration options, see README_FOR_DOCKER.md in the compose-files directory.
4. Configure environment variables in the .env file located in the compose-files directory. The .env file template includes documentation for all available configuration options, including:
   • Protocol and address settings
   • Port configurations
   • Authentication parameters
   • Image version tags
   See Authentication for authentication-specific configuration requirements.

Localhost Deployment

For local development, HTTPS is not required. The UI is accessible at http://localhost:8888 by default when running Docker locally.

1. Navigate to the compose-files directory where you extracted the configuration files:

   cd compose-files

2. (Optional) Configure environment variables by editing the .env file. The default values work for local development, but you can customize passwords and ports as needed. See the .env file for available configuration options.
3. Run one of the following commands to start Solace Schema Registry:
   Docker:

   docker compose -f compose.yaml -f compose.embedded.yaml up -d

   Podman:

   podman-compose -f compose.yaml -f compose.embedded.yaml up -d

4. Access Solace Schema Registry by navigating to http://localhost:8888 and logging in with one of the following credentials:
   • sr-developer:<devPassword>
   • sr-readonly:<roPassword>
   Replace <devPassword> and <roPassword> with the values you set in the .env file. The defaults are devPassword and roPassword respectively.

Custom Hostname Deployment

Custom hostname deployment allows you to access Solace Schema Registry using your organization's domain names instead of default localhost addresses. This deployment method is essential for production environments where you need branded URLs, proper SSL certificate validation, and integration with existing DNS infrastructure.

When using custom hostnames, HTTPS becomes mandatory for the UI to ensure secure communication and proper certificate validation. The Solace Schema Registry deployment includes an Nginx reverse proxy configuration that handles SSL termination and routes traffic to the appropriate services. This setup provides a production-ready foundation that can be customized for your specific networking requirements.

To configure SSL certificates and start Solace Schema Registry with Nginx proxy support, follow these steps:

1. Navigate to the compose-files directory where you extracted the configuration files:

   cd compose-files

2. Place your SSL certificate and key in the keys directory with the following filenames:
   • registry-cert.pem—The public SSL/TLS certificate used to secure HTTPS communication with Solace Schema Registry.
   • registry-key.pem—The private key that pairs with registry-cert.pem.
   This configuration requires a single wildcard SSL certificate and key pair. If you have separate certificates for individual subdomains, please modify the nginx/nginx.conf.template file to accommodate them.
3. Configure the following environment variables in the .env file or export them in your shell:

   export PROTOCOL=https
   export IDP_ADDRESS=<address for the IdP>
   export REGISTRY_UI_ADDRESS=<address for the Registry UI>
   export REGISTRY_API_ADDRESS=<address for the API>

4. Run one of the following commands to start the Solace Schema Registry with Nginx.
   Docker:

   docker compose -f compose.yaml -f compose.nginx.yaml -f compose.nginx.for.embedded.yaml -f compose.embedded.yaml up -d

   Podman:

   podman-compose -f compose.yaml -f compose.nginx.yaml -f compose.nginx.for.embedded.yaml -f compose.embedded.yaml up -d

Authentication

Solace Schema Registry supports two authentication methods: a built-in identity provider for simple deployments and external identity providers for enterprise environments. Choose the method that best fits your security requirements and infrastructure.

• Built-in Identity Provider Configuration
• External Identity Provider Configuration

Built-in Identity Provider Configuration

The built-in identity provider is suitable for development environments and simple deployments where you do not need integration with existing authentication infrastructure.

When to Use Built-in Authentication

• Development and testing environments
• Small deployments with limited users
• Environments without existing identity management systems
• Quick proof-of-concept deployments

Built-in Authentication Variables

Configure the following environment variables when using the built-in identity provider:

Variable Name	Description	Default Value
API_SECRET	Secret key used to secure API communications with the registry	apiSecret
DEVELOPER_PASSWORD	Password for developer-level access to the registry	devPassword
READONLY_PASSWORD	Password for read-only access to the registry	roPassword
IDP_HOST_PORT	Port on which the identity provider service runs	3000
IDP_ADDRESS	Full address of the identity provider service	localhost:3000
IDP_KEY	A Base64-encoded private key for signing JWTs.	<pre-generated key>

External Identity Provider Configuration

External identity provider integration allows you to leverage your existing authentication infrastructure and provides enterprise-grade security features including single sign-on (SSO), multi-factor authentication, and centralized user management.

Prerequisites for using an external IdP include the following:

• An OAuth 2.0/OIDC compatible identity provider
• Administrative access to configure the IdP
• Client credentials (client ID and secret) from your IdP
• Knowledge of your IdP's authorization server URL and endpoints

This section provides comprehensive configuration guidance including general OAuth/OIDC setup and provider-specific instructions.

• External Identity Provider Environment Variables
• Deploying Schema Registry
• Supported Identity Providers and Prerequisites

External Identity Provider Environment Variables

Solace recommends OAuth for most deployments. This configuration works with any OIDC-compliant identity provider and offers the most flexibility.

Basic Configuration

Configure the following core environment variables:

Environment Variable	Description
REGISTRY_OIDC_AUTH_SERVER_URL	The base URL of your OAuth/OIDC provider (for example, https://login.example.com/oauth2/default)
REGISTRY_OIDC_CLIENT_ID	The client ID registered with your OAuth provider
REGISTRY_OIDC_CLIENT_SECRET	The client secret associated with your client ID
REGISTRY_OIDC_REDIRECT_URI	The full URI where users are redirected after authentication. Use your domain and the correct path (for example, https://your-registry.com/explore). This URI must also be registered with your IdP.
REGISTRY_OIDC_ROLE_CLAIM_KEY	The JWT claim key that contains role information (for example, roles, groups)
REGISTRY_AUTH_ROLES_DEVELOPER	The claim value that grants developer access (for example, sr-developer)
REGISTRY_AUTH_ROLES_READONLY	The claim value that grants read-only access (for example, sr-readonly)

Advanced Configuration

For complex deployments that require different settings for UI and API authentication, configure these additional variables:

Environment Variable	Description
REGISTRY_OIDC_UI_TOKEN_ISSUER	The token issuer for UI authentication (if different from API)
REGISTRY_OIDC_UI_ROLES_ROLE_CLAIM_PATH	The JWT claim path for roles in UI authentication
REGISTRY_OIDC_API_TOKEN_ISSUER	The token issuer for API authentication (if different from UI)
REGISTRY_OIDC_API_ROLES_ROLE_CLAIM_PATH	The JWT claim path for roles in API authentication
REGISTRY_AUTHN_BASIC_SCOPE	The OAuth scope(s) to request during authentication (required for some providers like Azure AD)

To configure your OAuth deployment, do the following:

1. Configure your OAuth provider:
   • Create a new client/application in your IdP
   • Set the redirect URI to match your Solace Schema Registry domain
   • Configure the appropriate scopes and claims
   • Note the client ID, client secret, and authorization server URL
2. Set the OAuth environment variables in your .env file:

   REGISTRY_OIDC_AUTH_SERVER_URL=https://your-oauth-provider
   REGISTRY_OIDC_CLIENT_ID=your-client-id
   REGISTRY_OIDC_CLIENT_SECRET=your-client-secret
   REGISTRY_OIDC_REDIRECT_URI=https://your-registry-domain/callback
   REGISTRY_OIDC_ROLE_CLAIM_KEY=roles
   REGISTRY_AUTH_ROLES_DEVELOPER=sr-developer
   REGISTRY_AUTH_ROLES_READONLY=sr-readonly

3. Add advanced configuration if needed (see Advanced Configuration table above)
4. Start Solace Schema Registry with the updated configuration

Deploying Schema Registry

After configuring the required environment variables for your chosen identity provider, you can deploy Schema Registry using Docker Compose or Podman Compose. The specific compose files and options you use may vary depending on your authentication method and deployment scenario.

For example, to deploy Schema Registry with Microsoft Azure Entra ID, use one of the following commands:

Docker:

docker compose -f compose.yaml -f compose.nginx.yaml -f compose.nginx.for.external.yaml -f compose.external.multiple.issuers.yaml up -d

Podman:

podman-compose -f compose.yaml -f compose.nginx.yaml -f compose.nginx.for.external.yaml -f compose.external.multiple.issuers.yaml up -d

Supported Identity Providers and Prerequisites

Solace Schema Registry supports any OAuth 2.0/OpenID Connect (OIDC) compatible identity provider, however some identity providers require additional configuration steps, have specific limitations, or need workarounds. This section provides some detailed guidance for Microsoft Azure Entra ID.

Getting Started with Microsoft Azure Entra ID

When configuring Azure application registrations to interact with the Registry REST API, there are additional configuration requirements and key limitations around role support. For general OAuth/OIDC configuration steps, see External Identity Provider Configuration.

Limitations

1. The REST API only supports one role type (read-only OR developer), not both simultaneously.
2. Users and app registrations cannot share the same role configuration values.

Required Additional Configuration

The following environment variables must be set for Azure Entra ID (subject to change):

REGISTRY_OIDC_RESOLVE_TENANTS_WITH_ISSUER=true
REGISTRY_OIDC_UI_TOKEN_ISSUER=https://login.microsoftonline.com/<tenant ID>/v2.0
REGISTRY_OIDC_API_TOKEN_ISSUER=https://sts.windows.net/<tenant ID>/
REGISTRY_OIDC_UI_ROLES_ROLE_CLAIM_PATH=groups
REGISTRY_OIDC_API_ROLES_ROLE_CLAIM_PATH=roles
REGISTRY_OIDC_AUTH_ROLES_DEVELOPER=<group object ID>
REGISTRY_OIDC_AUTH_ROLES_READONLY=<group object ID>
REGISTRY_AUTHN_BASIC_SCOPE=api://<clientId of app registration>/.default

Deploying with Azure Entra ID

After configuring the required environmental variables, you can deploy Schema Registry with Microsoft Azure Entra ID with the following commands:

Docker:

docker compose -f compose.yaml -f compose.nginx.yaml -f compose.nginx.for.external.yaml -f compose.external.multiple.issuers.yaml up -d

Podman:

podman-compose -f compose.yaml -f compose.nginx.yaml -f compose.nginx.for.external.yaml -f compose.external.multiple.issuers.yaml up -d

Matching Group IDs and App Role Values

Azure Entra ID presents a unique challenge: Solace Schema Registry uses a single set of role configuration values (REGISTRY_OIDC_AUTH_ROLES_DEVELOPER and REGISTRY_OIDC_AUTH_ROLES_READONLY), but Azure handles authentication differently for users versus applications:

• Interactive users—Azure returns group membership IDs in the groups claim. These are fixed Azure group object IDs that you cannot modify.
• App registrations (service principals)—Azure includes custom app role values in the roles claim. These are values you define when creating app roles.

As a workaround, when you create app roles in your Azure app registration, set the app role Value field to match your existing Azure group object IDs. This ensures both users and applications can use the same role configuration values in Solace Schema Registry. For example, if your developer Azure group has object ID 12345678-1234-1234-1234-123456789abc, create an app role with Value = 12345678-1234-1234-1234-123456789abc.

App Role Selection

Because only one scope is supported in REGISTRY_AUTHN_BASIC_SCOPE, you must choose which role your REST API clients will have:

• Choose Developer role if REST clients need to create/modify artifacts (for example, creating schemas with references).
• Choose Read-only role if REST clients should only have read access to the registry.

Monitoring and Metrics

In versions 1.1.0 and later, Solace Schema Registry provides built-in monitoring by exposing Prometheus metrics at the /metrics endpoint of the service. These metrics provide insights into registry performance, health, and operational status.

To access the metrics endpoint:

• Localhost deployment:http://localhost:8081/metrics
• Custom hostname deployment:https://<REGISTRY_API_ADDRESS>/metrics

For information about audit logs and monitoring registry operations, see Monitoring Solace Schema Registry.

Troubleshooting

If you encounter issues during deployment, follow these troubleshooting steps:

General Troubleshooting

• Check container logs:
  • Docker— docker compose logs
  • Podman— podman-compose logs
• Verify port availability—Ensure that the configured Solace Schema Registry ports are not in use by other applications when deploying locally.
• Validate SSL certificates—For custom hostname deployments, confirm your SSL certificates are valid, properly formatted, and correctly referenced in your configuration.
• Review environment variables—Check that all required environment variables are correctly defined in your .env file or command line parameters.
• Inspect network configuration—Verify that your container network settings allow proper communication between services.

Authentication-Specific Troubleshooting

• External IdP issues—Check the IdP logs for authentication failures and verify the client configuration in both the IdP and Solace Schema Registry.
• Role mapping problems—Ensure that the role claim keys and values match between your IdP configuration and Solace Schema Registry environment variables.
• Redirect URI mismatches—Verify that the redirect URI configured in your IdP exactly matches the REGISTRY_OIDC_REDIRECT_URI environment variable.
• Token validation errors—Check that the authorization server URL is correct and accessible from Solace Schema Registry containers.