DevServices

DevServices is a Quarkus feature that automatically starts and configures external services during development and testing. The Quarkus LangChain4j Chroma extension includes DevServices support to automatically manage a Chroma database container.

Overview

When DevServices is enabled (the default), the extension automatically:

• Detects if you're running in dev or test mode
• Checks if Docker is available
• Starts a Chroma container using TestContainers
• Configures quarkus.langchain4j.chroma.url automatically
• Manages the container lifecycle (start/stop)
• Supports container sharing across multiple dev sessions

Key Benefits:

• Zero configuration needed for local development
• Automatic cleanup when stopping the application
• Shared containers reduce resource usage
• Consistent test environments

Capabilities

ChromaBuildConfig Interface

The build-time configuration interface defines all DevServices settings. This interface is not directly used in application code but defines the available configuration properties.

package io.quarkiverse.langchain4j.chroma.deployment;

import java.util.Map;
import java.util.OptionalInt;

/**
 * Build-time configuration for Chroma DevServices.
 * Configured via application.properties with prefix: quarkus.langchain4j.chroma.devservices
 */
interface ChromaBuildConfig {
    ChromaDevServicesBuildTimeConfig devservices();

    interface ChromaDevServicesBuildTimeConfig {
        /**
         * Enable or disable DevServices.
         * @return True to enable DevServices (default: true)
         */
        boolean enabled();

        /**
         * Docker image name to use for the Chroma container.
         * @return Image name (default: "ghcr.io/chroma-core/chroma:1.3.0")
         */
        String imageName();

        /**
         * Optional fixed port for the container.
         * @return Fixed port or empty for random port
         */
        OptionalInt port();

        /**
         * Enable container sharing across dev sessions.
         * @return True to share containers (default: true)
         */
        boolean shared();

        /**
         * Service name for container discovery when sharing.
         * @return Service name (default: "chroma")
         */
        String serviceName();

        /**
         * Environment variables to pass to the container.
         * @return Map of environment variables
         */
        Map<String, String> containerEnv();
    }
}

Note: This is a build-time configuration interface. All properties are configured via application.properties and are only read during the build/startup phase.

Enabling/Disabling DevServices

Control whether DevServices automatically starts a Chroma container.

# Enable or disable DevServices (default: true)
quarkus.langchain4j.chroma.devservices.enabled=true

Behavior:

• DevServices is enabled by default
• Automatically disabled when quarkus.langchain4j.chroma.url is explicitly configured
• Only active in dev and test modes (never in production)
• Requires Docker to be running

Usage Examples:

# Disable DevServices (use manually configured Chroma)
quarkus.langchain4j.chroma.devservices.enabled=false
quarkus.langchain4j.chroma.url=http://my-chroma-server:8000

# Enable only for dev mode, disable for tests
%dev.quarkus.langchain4j.chroma.devservices.enabled=true
%test.quarkus.langchain4j.chroma.devservices.enabled=false
%test.quarkus.langchain4j.chroma.url=http://test-chroma:8000

Default Value: true

Container Image Configuration

Specify which Chroma Docker image to use for the DevServices container.

# Docker image name (default: ghcr.io/chroma-core/chroma:1.3.0)
quarkus.langchain4j.chroma.devservices.image-name=ghcr.io/chroma-core/chroma:1.3.0

Usage Examples:

# Use a specific Chroma version
quarkus.langchain4j.chroma.devservices.image-name=ghcr.io/chroma-core/chroma:1.2.0

# Use latest version (not recommended for reproducibility)
quarkus.langchain4j.chroma.devservices.image-name=ghcr.io/chroma-core/chroma:latest

# Use a custom registry
quarkus.langchain4j.chroma.devservices.image-name=my-registry.com/chroma:1.3.0

Default Value: ghcr.io/chroma-core/chroma:1.3.0

Note: The image must be compatible with the ChromaDB API. Version 1.3.0 supports the V2 API (recommended).

Port Configuration

Optionally specify a fixed port for the Chroma container.

# Fixed exposed port (default: random port)
quarkus.langchain4j.chroma.devservices.port=8000

Behavior:

• If not specified, DevServices uses a random available port
• If specified, DevServices attempts to bind to the specified port
• Port conflicts cause startup failure

Usage Examples:

# Use default Chroma port
quarkus.langchain4j.chroma.devservices.port=8000

# Use custom port
quarkus.langchain4j.chroma.devservices.port=9000

# Let DevServices choose random port (default behavior)
# Don't set quarkus.langchain4j.chroma.devservices.port

Default Value: Random available port

When to Use Fixed Ports:

• Integration with external tools that need a known port
• Local development with browser-based Chroma clients
• Debugging with tools that require fixed endpoints

When to Use Random Ports:

• CI/CD environments where port conflicts are common
• Running multiple Quarkus applications simultaneously
• Automatic test environments

Container Sharing

Enable sharing of the Chroma container across multiple Quarkus dev sessions.

# Enable container sharing (default: true)
quarkus.langchain4j.chroma.devservices.shared=true

# Service name for shared container discovery (default: "chroma")
quarkus.langchain4j.chroma.devservices.service-name=chroma

How Container Sharing Works:

1. When starting dev mode, DevServices looks for existing containers with label quarkus-dev-service-chroma=<service-name>
2. If a matching container exists and is running, it reuses that container
3. If no matching container exists, it starts a new container with the label
4. Multiple applications with the same service name share the same container
5. The container remains running until all applications stop

Benefits:

• Faster startup for subsequent applications
• Reduced resource usage (memory, CPU)
• Shared data across development sessions

Usage Examples:

# Default sharing with service name "chroma"
quarkus.langchain4j.chroma.devservices.shared=true
quarkus.langchain4j.chroma.devservices.service-name=chroma

# Disable sharing (each app gets its own container)
quarkus.langchain4j.chroma.devservices.shared=false

# Multiple shared instances with different service names
# Application 1 - production-like data
quarkus.langchain4j.chroma.devservices.service-name=chroma-prod
# Application 2 - development data
quarkus.langchain4j.chroma.devservices.service-name=chroma-dev

Default Values:

• shared: true
• service-name: "chroma"

Note: Container sharing only works in development mode, not in test mode.

Container Environment Variables

Pass environment variables to the Chroma container.

# Set environment variables for the container
quarkus.langchain4j.chroma.devservices.container-env.CHROMA_ENV_VAR=value
quarkus.langchain4j.chroma.devservices.container-env.ANOTHER_VAR=another_value

Usage Examples:

# Configure Chroma server settings
quarkus.langchain4j.chroma.devservices.container-env.ANONYMIZED_TELEMETRY=false
quarkus.langchain4j.chroma.devservices.container-env.ALLOW_RESET=true

# Set authentication (if using a custom Chroma build)
quarkus.langchain4j.chroma.devservices.container-env.CHROMA_SERVER_AUTH_PROVIDER=token
quarkus.langchain4j.chroma.devservices.container-env.CHROMA_SERVER_AUTH_TOKEN_TRANSPORT_HEADER=X-Chroma-Token

Default Value: Empty map (no environment variables)

Common Chroma Environment Variables:

• ANONYMIZED_TELEMETRY: Enable/disable telemetry (true/false)
• ALLOW_RESET: Allow database reset via API (true/false)
• CHROMA_SERVER_AUTH_PROVIDER: Authentication provider (token, basic, etc.)

Refer to Chroma documentation for the complete list of supported environment variables.

Complete DevServices Configuration Example

# Comprehensive DevServices configuration

# Enable DevServices
quarkus.langchain4j.chroma.devservices.enabled=true

# Use specific Chroma version
quarkus.langchain4j.chroma.devservices.image-name=ghcr.io/chroma-core/chroma:1.3.0

# Use fixed port
quarkus.langchain4j.chroma.devservices.port=8000

# Enable container sharing
quarkus.langchain4j.chroma.devservices.shared=true
quarkus.langchain4j.chroma.devservices.service-name=my-chroma

# Configure container environment
quarkus.langchain4j.chroma.devservices.container-env.ANONYMIZED_TELEMETRY=false
quarkus.langchain4j.chroma.devservices.container-env.ALLOW_RESET=true

Profile-Specific DevServices Configuration

Configure different DevServices behavior for dev and test modes:

# Development mode - shared container with UI access
%dev.quarkus.langchain4j.chroma.devservices.enabled=true
%dev.quarkus.langchain4j.chroma.devservices.shared=true
%dev.quarkus.langchain4j.chroma.devservices.port=8000
%dev.quarkus.langchain4j.chroma.devservices.service-name=chroma-dev

# Test mode - isolated containers for each test run
%test.quarkus.langchain4j.chroma.devservices.enabled=true
%test.quarkus.langchain4j.chroma.devservices.shared=false
# Don't set port for tests - use random ports to avoid conflicts

DevServices Lifecycle

Development Mode (quarkus dev):

1. DevServices checks if quarkus.langchain4j.chroma.url is configured
2. If not configured and DevServices is enabled:
   • Checks if Docker is available
   • Looks for shared container (if sharing is enabled)
   • Starts new container if needed
   • Configures quarkus.langchain4j.chroma.url automatically
3. Container runs until dev mode is stopped
4. If using shared container, it remains running for other applications

Test Mode (mvn test or ./gradlew test):

1. DevServices starts a container before tests run
2. Container is isolated per test run (sharing disabled)
3. Container automatically stops after tests complete
4. Fresh container for each test run ensures test isolation

Production Mode (java -jar app.jar):

• DevServices is never active
• Must configure quarkus.langchain4j.chroma.url explicitly

Disabling DevServices for Production Builds

DevServices is automatically disabled in production mode. No special configuration needed.

# Production configuration - DevServices ignored
%prod.quarkus.langchain4j.chroma.url=http://production-chroma:8000
%prod.quarkus.langchain4j.chroma.collection-name=production-embeddings

Troubleshooting DevServices

Container Fails to Start:

• Verify Docker is running: docker ps
• Check image is available: docker pull ghcr.io/chroma-core/chroma:1.3.0
• Look for port conflicts if using fixed port
• Check Docker logs: docker logs <container-id>

DevServices Not Starting:

• Ensure quarkus.langchain4j.chroma.url is not configured
• Verify quarkus.langchain4j.chroma.devservices.enabled=true
• Confirm you're running in dev or test mode
• Check Quarkus logs for DevServices messages

Shared Container Issues:

• Verify service names match across applications
• Check for stale containers: docker ps -a
• Clean up old containers: docker rm -f $(docker ps -aq -f label=quarkus-dev-service-chroma)

Performance Issues:

• Consider using shared containers to reduce startup time
• Use fixed ports to avoid port scanning overhead
• Ensure Docker has sufficient resources allocated

Manual Container Management

To manually manage a Chroma container outside of DevServices:

# Start Chroma container
docker run -d \
  --name chroma \
  -p 8000:8000 \
  ghcr.io/chroma-core/chroma:1.3.0

# Configure Quarkus to use the container
# In application.properties:
quarkus.langchain4j.chroma.devservices.enabled=false
quarkus.langchain4j.chroma.url=http://localhost:8000

This approach gives you full control over the container lifecycle and configuration.

Default Values Summary