Install server-side SDKs

Install and configure server-side SDKs to enable centralized feature flag evaluation and management in backend services, APIs, and server applications. Server-side SDKs provide advanced targeting capabilities, enhanced security for sensitive flags, and can handle high-volume flag evaluations efficiently through periodic refresh and caching mechanisms.

For conceptual information about server-side vs client-side architecture, refer to Understanding feature management.

CloudBees Unify requires SDK version 6.x or later. Ensure you have access to your server application’s source code, appropriate package management tools, and network connectivity for the SDK to reach CloudBees services.

Choose your server-side platform

Identify the appropriate server-side SDK based on your application platform and verify platform-specific requirements.

Server-side SDKs are designed for backend applications where flags are evaluated in controlled server environments with enhanced security and performance characteristics:

Enterprise backends: Java applications with Maven or Gradle
Modern services: Go microservices and APIs
Web frameworks: Node.js with Express, Python with Django/Flask
Legacy systems: C/C++ applications and .NET/C# services
Dynamic platforms: PHP web applications and Ruby on Rails

Server-side SDKs offer advantages over client-side SDKs including secure flag storage, advanced targeting rules, and optimized performance for high-volume applications.

To select your platform:

Determine your server platform from the supported server-side languages.
Verify you have the appropriate build tools and package managers installed.
Confirm your server environment can establish outbound network connections to CloudBees services.

Install the SDK package

Add the CloudBees Unify server-side SDK to your application using platform-specific package managers and build systems.

You must have an existing feature management application and environment set up in CloudBees Unify before installing the SDK.

To install the server SDK package:

Access the installation instructions in CloudBees Unify:
1. Navigate to Feature management Flags.
2. Select the installation instructions icon to open the guided setup.
3. Select your target environment or create a new server environment if needed.
Choose your server platform and package manager:
1. Select your platform from the language options.
2. Choose the appropriate package manager for your build system.
Install the SDK using platform-specific dependency management:

For Java applications:

Maven dependency in pom.xml:

<dependency>
    <groupId>io.rollout.rox</groupId>
    <artifactId>rox-java-server</artifactId>
    <version>6.0.0</version>
</dependency>▼

Gradle dependency in build.gradle:

implementation 'io.rollout.rox:rox-java-server:6.0.0'▼

For Go applications:

go get -u github.com/rollout/rox-go/v6/server▼

For Python applications:

pip install rox▼

For Node.js applications:

# npm
npm install rox-node --save

# yarn
yarn add rox-node

# TypeScript projects also need:
npm install @types/rox-node --save▼

For C/C++ applications:

git clone https://github.com/cloudbees/rox-cpp-sdk.git
cd rox-cpp-sdk
mkdir build && cd build
cmake ..
make
sudo make install▼

For .NET/C# applications: Install via NuGet Package Manager or Package Manager Console.

For PHP applications: Install via Composer package manager.

For Ruby applications: Install via RubyGems package manager.

After installation, the server SDK package appears in your project dependencies and is ready for configuration.

Configure server SDK initialization

Set up the SDK in your server application with proper flag definitions and initialization patterns.

Import required SDK modules

Import the necessary SDK classes and modules for your server platform:

Java example:

import io.rollout.rox.server.Rox;
import io.rollout.rox.server.RoxFlag;
import io.rollout.rox.server.RoxString;
import io.rollout.rox.server.RoxInt;▼

Go example:

import (
    "github.com/rollout/rox-go/v6/server"
)▼

Python example:

from rox.server.rox_server import Rox
from rox.server.flags.rox_flag import RoxFlag
from rox.core.entities.rox_string import RoxString▼

Node.js example:

import Rox from 'rox-node';
// or using CommonJS: const Rox = require('rox-node');▼

Define flag container with typed flags

Create strongly-typed flag definitions that specify default values and available variations for server-side evaluation:

Java flag container:

public class ServerFlags {
    // Boolean flag for feature toggles
    public RoxFlag enableAdvancedAuth = new RoxFlag();

    // String flag with predefined options
    public RoxString apiVersion = new RoxString("v1",
        Arrays.asList("v1", "v2", "v3"));

    // Integer flag for numeric configuration
    public RoxInt maxRetries = new RoxInt(3,
        Arrays.asList(1, 3, 5, 10));
}▼

Go flag container:

type ServerFlags struct {
    EnableAdvancedAuth server.RoxFlag
    ApiVersion         server.RoxString
    MaxRetries         server.RoxInt
}

func NewServerFlags() *ServerFlags {
    return &ServerFlags{
        EnableAdvancedAuth: server.NewRoxFlag(false),
        ApiVersion: server.NewRoxString("v1", []string{"v1", "v2", "v3"}),
        MaxRetries: server.NewRoxInt(3, []int{1, 3, 5, 10}),
    }
}▼

Python flag container:

class ServerFlags:
    def __init__(self):
        self.enable_advanced_auth = RoxFlag(False)
        self.api_version = RoxString('v1', ['v1', 'v2', 'v3'])
        self.max_retries = RoxInt(3, [1, 3, 5, 10])▼

Node.js flag container:

const serverFlags = {
    enableAdvancedAuth: new Rox.Flag(false),
    apiVersion: new Rox.RoxString('v1', ['v1', 'v2', 'v3']),
    maxRetries: new Rox.RoxNumber(3, [1, 3, 5, 10])
};▼

Register flag container

Java registration:

ServerFlags flags = new ServerFlags();
Rox.register("server", flags);▼

Go registration:

flags := NewServerFlags()
rox := server.NewRox()
rox.Register("server", flags)▼

Python registration:

flags = ServerFlags()
Rox.register(flags)▼

Node.js registration:

Rox.register('server', serverFlags);▼

Set up SDK connection and authentication

Configure the SDK key and establish the connection to CloudBees Unify with proper error handling for server environments.

Configure SDK key securely

Retrieve your server environment’s SDK key from CloudBees Unify and configure it securely:

Navigate to Feature management Flags and select your application.
Copy the SDK key displayed for your server environment.
Configure the key using environment variables or secure configuration management:

Environment variable approach (recommended):

export ROX_SDK_KEY="your-server-sdk-key-here"▼

Application configuration: Store the SDK key in your application’s secure configuration system rather than hardcoding it in source files.

Initialize SDK connection

Complete the SDK setup with platform-specific connection patterns and error handling:

Java synchronous setup:

public class ServerApplication {
    public static void main(String[] args) {
        ServerFlags flags = new ServerFlags();
        Rox.register("server", flags);

        try {
            // Synchronous setup with timeout
            Rox.setup(System.getenv("ROX_SDK_KEY")).get();

            // Use flags after successful setup
            if (flags.enableAdvancedAuth.isEnabled()) {
                // Advanced authentication logic
            }

        } catch (Exception e) {
            System.err.println("Failed to initialize feature flags: " + e.getMessage());
            // Handle graceful degradation
        }
    }
}▼

Go asynchronous setup:

func main() {
    flags := NewServerFlags()
    rox := server.NewRox()
    rox.Register("server", flags)

    // Asynchronous setup with error handling
    errChan := rox.Setup(os.Getenv("ROX_SDK_KEY"),
        server.NewRoxOptions(server.RoxOptionsBuilder{}))

    if err := <-errChan; err != nil {
        log.Printf("Error during Rox setup: %v", err)
        return
    }

    // Use flags after successful setup
    if flags.EnableAdvancedAuth.IsEnabled(nil) {
        // Advanced authentication logic
    }

    // Graceful shutdown
    defer rox.Shutdown()
}▼

Python async setup:

import asyncio
import os

async def initialize_flags():
    flags = ServerFlags()
    Rox.register(flags)

    try:
        # Asynchronous setup
        await Rox.setup(os.getenv('ROX_SDK_KEY'))

        # Use flags after setup
        if flags.enable_advanced_auth.is_enabled():
            print("Advanced auth enabled")

    except Exception as e:
        print(f"Failed to initialize feature flags: {e}")

# Run the async initialization
asyncio.run(initialize_flags())▼

Node.js async setup:

async function initializeFeatureFlags() {
    Rox.register('server', serverFlags);

    try {
        await Rox.setup(process.env.ROX_SDK_KEY);

        // Use flags after successful setup
        if (serverFlags.enableAdvancedAuth.isEnabled()) {
            console.log('Advanced authentication enabled');
        }

    } catch (error) {
        console.error('Failed to initialize feature flags:', error);
        // Implement graceful degradation
    }
}

initializeFeatureFlags();▼

Test server integration

Verify the server SDK installation and connection to CloudBees Unify with comprehensive integration testing.

To test your server integration:

Start your server application with the SDK initialization code.
Monitor application logs for successful SDK connection messages.
Return to the CloudBees Unify installation interface and select Test Integration.
Confirm the connection status shows as successful for your server environment.

If the test integration succeeds, your server flags automatically appear in the CloudBees Unify feature flag list with server-specific metadata.

Server-specific integration verification:

Verify flag synchronization: Confirm that all flags defined in your server code appear in the CloudBees Unify interface with correct default values and variation options.

Test flag evaluation: Modify flag values in CloudBees Unify and verify that your server application reflects the changes within the configured refresh interval.

Monitor performance: Check that flag evaluations perform efficiently under your application’s expected load.

Handle server-specific considerations

Address performance, security, and operational requirements specific to server-side deployments.

Performance optimization

Configure the SDK for optimal performance in server environments:

Caching and refresh intervals: - Server SDKs cache flag configurations locally for fast evaluation - Default refresh intervals balance freshness with performance - Configure refresh intervals based on your application’s requirements

Memory management: - Server SDKs maintain flag configurations in memory - Monitor memory usage in high-scale applications - Consider flag cleanup for temporary or experimental flags

Security considerations

Implement proper security practices for server-side flag management:

SDK key protection: - Store SDK keys in secure configuration systems - Use environment variables rather than hardcoding keys - Implement key rotation procedures for production environments

Network security: - Ensure server environments can establish outbound HTTPS connections - Configure firewalls and proxy settings as needed - Verify TLS certificate validation for secure communication

Operational monitoring

Set up monitoring and logging for production server deployments:

Connection health monitoring: - Monitor SDK connection status and refresh success rates - Set up alerting for SDK connectivity failures - Implement graceful degradation when flags are unavailable

Flag evaluation logging: - Log flag evaluations for debugging and audit purposes - Monitor flag usage patterns and performance metrics - Track feature rollout progress and user impact

Common server integration issues:

Problem: SDK setup timeout or connection failures

Solution: Verify network connectivity, firewall rules, and proxy configuration. Check that your server can reach CloudBees services on required ports.

Problem: Flags not updating after configuration changes

Solution: Verify SDK refresh intervals and network connectivity. Check application logs for SDK refresh errors or warnings.

Problem: High memory usage or performance impact

Solution: Review flag definitions and cleanup unused flags. Consider optimizing refresh intervals and caching strategies for your application’s scale.