Migrating from cloud to on-premise

Migrating from cloud to on-premise Device Detection🔗

This guide walks you through migrating from 51Degrees Cloud Device Detection to On-premise deployment. You'll learn when to migrate, how to update your configuration, and what changes to expect.

When to consider on-premise🔗

On-premise deployment works better when you need:

  • Faster response times - No network call, and microseconds per detection when the data file is held in memory
  • Processing on your servers - All processing happens within your infrastructure
  • High-volume processing - Handle millions of detections without API limits
  • Offline capability - No internet connection required
  • Predictable costs - The Bespoke plan has no monthly request allowance, so the fee does not depend on traffic

Migration steps🔗

  1. Get an On-premise license and data file
  2. Update package dependencies (if needed)
  3. Change pipeline configuration
  4. Modify code for file-based detection
  5. Set up data file updates
  6. Test and optimize performance

Step 1: Get a license and data file🔗

For testing:

  • Download the free Lite data file with the scripts in the data repository on GitHub
  • No License Key required, but limited device properties

For production:

  • Contact 51Degrees to purchase the Bespoke plan, the only paid plan that includes on-premise use
  • Includes full data file with all device properties
  • Automatic data file updates included

Step 2: Update dependencies🔗

Most 51Degrees packages already include both Cloud and On-premise capabilities. You typically only need configuration changes.

.NET

<!-- Most users already have this -->
<PackageReference Include="FiftyOne.DeviceDetection" Version="4.x.x" />
<!-- Only if you had Cloud-specific packages -->
<!-- Remove: FiftyOne.DeviceDetection.Cloud -->
<!-- Add: FiftyOne.DeviceDetection -->

Java

<dependency>
<groupId>com.51degrees</groupId>
<artifactId>device-detection</artifactId>
<version>4.x.x</version>
</dependency>

Node.js

npm install fiftyone.devicedetection

Other Languages

Step 3: Update configuration🔗

Replace your Cloud configuration with file-based settings.

Before (Cloud):

{
"Elements": [
{
"elementKey": "device",
"elementParameters": {
"cloudEndpoint": "https://cloud.51degrees.com/api/v4",
"resourceKey": "YOUR_RESOURCE_KEY"
}
}
]
}

After (On-premise):

{
"Elements": [
{
"elementKey": "device",
"elementParameters": {
"dataFilePath": "/path/to/51Degrees-LiteV4.1.hash",
"performanceProfile": "MaxPerformance",
"licenseKey": "YOUR_LICENSE_KEY",
"autoUpdate": true,
"updateOnStart": true,
"fileSystemWatcher": true
}
}
]
}

Step 4: Update code🔗

The Pipeline API keeps most code unchanged. Main differences:

Pipeline Creation

Before:

var pipeline = new DeviceDetectionPipelineBuilder()
.UseCloud(resourceKey)
.Build();

After:

var pipeline = new DeviceDetectionPipelineBuilder()
.UseOnPremise(dataFilePath, licenseKey)
.SetAutoUpdate(true)
.SetPerformanceProfile(PerformanceProfiles.MaxPerformance)
.Build();

Error Handling

  • Handle file system errors instead of network errors
  • Check data file permissions and disk space
  • Monitor data file update failures

Property Access

  • The properties available locally depend on your data file
  • No rate limiting on property requests
  • Response times depend on the properties you request

For complete examples:

Step 5: Set up data file updates🔗

On-premise deployments need regular data file updates to detect new devices.

Automatic Updates (Recommended)

Configure the pipeline to handle updates. See the Data File Updates examples for comprehensive examples of:

  • Update on Startup
  • File System Watcher
  • Polling Interval

Manual Updates

Download new data files from the 51Degrees Distributor using your License Key.

Step 6: Optimize performance🔗

Choose Performance Profile

  • MaxPerformance - Fastest detection, uses more memory (recommended)
  • HighPerformance - Uses about as much memory as MaxPerformance, so it is generally not recommended
  • LowMemory - Slowest but minimal memory usage
  • Balanced - Default middle ground

Deployment Options

  • In-Process - Fastest option, detection in your application
  • Out-of-Process - Separate process for isolation
  • Separate Server - Centralized detection service

See Performance Examples for benchmarking.

Testing your migration🔗

  1. Compare Results - Verify detection matches Cloud results for test cases
  2. Load Testing - Confirm performance under expected traffic
  3. Update Testing - Ensure data file updates work without disruption
  4. Failover Testing - Test what happens if data file becomes unavailable

Common migration patterns🔗

Web Applications

Batch Processing

  • Use offline processing
  • Process large User-Agent lists efficiently
  • Use multi-threading for maximum throughput

Microservices

  • Deploy as sidecar container
  • Share data file via volume mount
  • Use environment variables for configuration

Planning your rollback🔗

Keep Cloud access during migration:

  1. Maintain your Cloud Resource Key
  2. Use feature flags to switch between Cloud and On-premise
  3. Run both implementations in parallel initially
  4. Gradually shift traffic to On-premise

Troubleshooting🔗

Data file not found

  • Check file path is absolute and correct
  • Verify file permissions allow read access
  • Confirm data file downloaded successfully

License Key issues

  • Ensure license is for On-premise (not Cloud)
  • Check license hasn't expired
  • Verify product tier matches your data file

Poor performance

  • Confirm you're using MaxPerformance profile
  • Check you're running in-process (not separate service)
  • Review performance examples

Memory usage too high

  • Switch to the Balanced or LowMemory profile
  • Consider out-of-process deployment
  • Monitor memory usage patterns

Next steps🔗

  1. Review On-premise examples
  2. Set up automatic data file updates
  3. Enable client-side evidence for better accuracy
  4. Monitor match metrics for quality

💬 Get help🔗

Have a data or code question? Get in touch and explore subscription options.