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.

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.
  • Set your environmental variables. See the .env file for a complete example. The following table shows the general configuration variables that are always required:
    Variable NameDescriptionDefault Value
    PROTOCOLProtocol used for communication with the registryhttp
    REGISTRY_UI_HOST_PORTPort on which the web UI runs8888
    REGISTRY_UI_ADDRESSFull address to access the web interfacelocalhost:8888
    REGISTRY_API_HOST_HTTP_PORTPort on which the registry API service runs8081
    REGISTRY_API_ADDRESSFull address for API calls to the registrylocalhost:8081

Loading Solace Schema Registry Container Image

Download Solace Schema Registry as a tarball package from the Solace Products website. A Solace Products website account is required to access these products. Once you have obtained the tarball package, load the image:

Docker:

docker load -i /path/to/solace-registry-<version>.tar.gz

Podman:

To load a Docker image archive into Podman, first ensure the image is in uncompressed .tar format.

podman load -i /path/to/solace-registry-<version>.tar

Localhost Deployment

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

  1. Run one of the following commands to start Solace Schema Registry:
    Docker: Podman:
    docker compose -f compose.yaml -f compose.embedded.yaml up -d
    podman-compose -f compose.yaml -f compose.embedded.yaml up -d
  2. 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 environment variables. 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. 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.
  2. Configure the following environment variables:
    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>
  3. 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.

The built-in and external identity provider configurations are mutually exclusive. You must choose one authentication method and configure only the variables for that method.

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.

When using an external IdP, the default credentials (sr-developer and sr-readonly) will no longer work. Users must authenticate through the configured IdP.

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)

Only one claim value can be specified for each role (developer and read-only). If your IdP uses different group/role claim values for interactive and non-interactive authentication, you must configure them to match.

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_OIDC_AUTH_ROLES_DEVELOPER=sr-developer
    REGISTRY_OIDC_AUTH_ROLES_READONLY=sr-readonly
  3. Add advanced configuration if needed (see Advanced OAuth Configuration table above)
  4. Start Solace Schema Registry with the updated configuration

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

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.
This role selection limitation only affects REST API clients. Web UI users can still use different roles and access the registry without issue.

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.