Broadleaf Microservices
  • v1.0.0-latest-prod

Evaluation Credentials

Broadleaf’s getting started guides are written for Enterprise License Holders. If you were provisioned developer evaluation credentials, a handful of steps differ, because your credentials resolve against Broadleaf’s evaluation mirror rather than the primary repository.

This page collects every one of those differences in one place. Set up the three items in the Setup Checklist and the rest of the guides on this portal work unchanged.

Do These Steps Apply to Me?

You have evaluation credentials (and this page applies to you) if either of the following is true:

  • You’ve received a username that starts with eval-.

  • You requested a developer evaluation through our contact form and were provisioned limited-term credentials.

When your evaluation is approved, you should receive an email with getting started instructions that include a username, password, and an expiration date.

Note
 As you follow any of the getting started guides on this portal, pay attention to any instructions that call out different steps needed for "Evaluation Credential Holders". Those callouts correspond to the steps documented here.

If you hold a full Enterprise License instead, you can skip this page - except for Converting from Evaluation to Enterprise License Credentials, if you are moving off an evaluation.

What’s Actually Different

The primary difference revolves around: which repositories your credentials are entitled to.

Evaluation Credential Holders only have access to artifacts that reside on Broadleaf’s Evaluation Mirror Repository. Enterprise License Holders have access to the full suite of Broadleaf resources (depending on their license) on Broadleaf’s primary repository.

Enterprise License Credentials Evaluation Credentials

Docker registry

repository.broadleafcommerce.com:5001

https://evaluation.docker.blcdemo.com

Maven repository

https://repository.broadleafcommerce.com

https://evaluation.repository.blcdemo.com

Private NPM Repository (@broadleaf/* packages)

Included

Not included — see NPM Registry Access

Maven settings.xml

Server credentials only

Server credentials plus a <mirror> entry

docker-compose:generate

No extra arguments

Requires -Dmirror=evaluation.docker.blcdemo.com

Term

Per your license

Limited term — see the expiration date in your provisioning email

Setup Checklist for Evaluation Credentials

There are three primary things to configure:

Step What Verify

1

Authenticate to the evaluation Docker registry

docker login reports success

2

Add the evaluation mirror to ~/.m2/settings.xml

Your first ./mvnw build in the manifest project resolves Broadleaf dependencies

3

Pass -Dmirror to the docker-compose Maven goals

Image names in manifest/target/docker/docker-compose.yml point at evaluation.docker.blcdemo.com
Note
 There is deliberately no NPM step here — see NPM Registry Access.

Step 1: Docker Registry Authentication

Authenticate with the Broadleaf Docker registry that matches your credentials. When prompted, enter the username and password you were provisioned.

For Enterprise License Holders:

docker login repository.broadleafcommerce.com:5001

For Evaluation Credential Holders:

docker login https://evaluation.docker.blcdemo.com
Caution
 Logging in to the wrong registry is the most common first-run failure. Evaluation credentials will not authenticate against repository.broadleafcommerce.com:5001, and image pulls will fail even though your credentials are valid.

Step 2: Maven Repository Authentication

To build a Broadleaf Initializr-based project, you will need to have configured authentication to Broadleaf’s private Maven Nexus. The correct ~/.m2/settings.xml configuration depends on the type of credentials you were provisioned.

For Enterprise License Holders:

<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
          xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <servers>
        <server>
            <id>broadleaf-microservices</id>
            <username>username_here</username>
            <password>password_here</password>
        </server>
    </servers>
</settings>

For Evaluation Credential Holders:

You will need to set up a mirror configuration to the broadleaf-microservices server id. Broadleaf projects declare the broadleaf-microservices repository, so the <mirror> entry is what redirects those requests to the evaluation repository, and the matching <server> id is what authenticates against it.

<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
          xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <servers>
        <server>
            <id>broadleaf-microservices-evaluation</id>
            <username>eval_username_here</username>
            <password>eval_password_here</password>
        </server>
    </servers>
    <mirrors>
        <mirror>
            <id>broadleaf-microservices-evaluation</id>
            <mirrorOf>broadleaf-microservices</mirrorOf>
            <url>https://evaluation.repository.blcdemo.com/repository/microservices/</url>
        </mirror>
    </mirrors>
</settings>
Important
 The <server> id and the <mirror> id must both be broadleaf-microservices-evaluation, and <mirrorOf> must be broadleaf-microservices. Maven matches credentials to a mirror by id, so a mismatch here surfaces as an authentication failure rather than a configuration error.
Keeping credentials out of your repository (recommended)

~/.m2/settings.xml lives outside your project, so it is not committed by default — keep it that way rather than moving it into the project tree.

If you prefer not to store the password in plain text, Maven supports encrypted passwords: generate a master password with --encrypt-master-password, store it in ~/.m2/settings-security.xml, then encrypt your Broadleaf password with --encrypt-password and place the resulting {…​} value in the <password> element.

The exact invocation differs across Maven versions, so follow the Maven password encryption guide for the version you are running.

Step 3: Generating the Correct docker-compose.yml

When using Broadleaf’s Maven docker-compose:generate plugin, you will need to specify a mirror param so that the generated demo docker images point to the correct docker registry based on the type of credentials you have.

For Enterprise License Holders:

cd manifest
./mvnw docker-compose:generate
./mvnw docker-compose:up

For Evaluation Credential Holders:

cd manifest
./mvnw docker-compose:generate -Dmirror=evaluation.docker.blcdemo.com
./mvnw docker-compose:up -Dmirror=evaluation.docker.blcdemo.com
Tip
 The generate goal writes a docker-compose.yml file to manifest/target/docker. Open it to confirm the image names point at evaluation.docker.blcdemo.com before running up.
Important

If you are attempting to run an EVAL using the 2.2.1-GA or 2.2.1.1-GA Release Trains, please see this known issue and workaround if you are having issues executing the above docker-compose:up command.

NPM Registry Access (Enterprise License Only)

Broadleaf’s private NPM registry is available to Enterprise License Holders only, and evaluations are excluded from private NPM access.

This does not limit your evaluation of the platform. The full local stack — including the storefront accelerator and the admin console — runs as prebuilt container images pulled from the evaluation Docker registry, so no NPM authentication is involved in getting the ecosystem up and running.

What evaluation credentials do not cover is installing Broadleaf’s @broadleaf/* packages (the Commerce SDK, Auth SDK, admin components, and the Next.js storefront accelerator source) from Broadleaf’s private registry for local frontend development. That requires an Enterprise License.

Tip
 If your evaluation depends on building a frontend against Broadleaf’s packages, contact us — that scenario needs an Enterprise License rather than an evaluation.

Troubleshooting

Symptom Likely Cause Fix

Image pulls are denied or unauthorized during docker-compose:up

Not authenticated to the evaluation registry, or authenticated to the enterprise one

Re-run Step 1 against https://evaluation.docker.blcdemo.com

Maven cannot resolve com.broadleafcommerce artifacts, or returns an authentication error

~/.m2/settings.xml is missing the <mirror> entry, or the server/mirror ids don’t match

Re-check Step 2, including the id matching note

The generated docker-compose.yml references repository.broadleafcommerce.com

docker-compose:generate was run without -Dmirror

Re-run Step 3 with the -Dmirror argument

Setup worked previously and now every registry and repository call fails

Your evaluation term has ended

See When Your Evaluation Expires

docker-compose:up fails on release train 2.2.1-GA / 2.2.1.1-GA

Known issue with those release trains

Apply the documented workaround

Builds or pulls still hit the evaluation mirror after receiving an Enterprise License

Stale docker login and a leftover <mirror> entry

Follow Converting from Evaluation to Enterprise License Credentials

Still stuck? Search the Broadleaf forums — evaluation setup issues and their workarounds are frequently posted there.

When Your Evaluation Expires

Your provisioning email includes an expiration date. Contact us to extend your evaluation or to discuss an Enterprise License.

Converting from Evaluation to Enterprise License Credentials

If you were given full Enterprise License Credentials and were previously using Evaluation Credentials, then you will want to make sure you correct your local environment setup to no longer use the evaluation mirror. There are three things to undo.

1. Authenticate to the Correct Docker Registry

docker logout https://evaluation.docker.blcdemo.com
docker login repository.broadleafcommerce.com:5001

2. Authenticate to the Correct Maven Repository

Make sure to change your ~/.m2/settings.xml credentials to remove the evaluation mirror. Your settings.xml file should now look something like this:

<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd"
          xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <servers>
        <server>
            <id>broadleaf-microservices</id>
            <username>username_here</username>
            <password>password_here</password>
        </server>
    </servers>
</settings>

Note that the <mirrors> block is gone entirely, and the <server> id is back to broadleaf-microservices.

3. Regenerate Your docker-compose.yml

Any docker-compose.yml you generated while on evaluation credentials still references the evaluation registry. Regenerate it without the -Dmirror argument so image names resolve against the primary registry:

cd manifest
./mvnw docker-compose:generate
./mvnw docker-compose:up
Tip
 You may also want to clear previously pulled evaluation images (docker images | grep evaluation.docker.blcdemo.com) so you are certain you are running images from the primary registry.