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 - Loads the data into memory, and when you name only some properties it leaves out the values they don't read
  • LowMemory - Slowest but minimal memory usage
  • Balanced - Default middle ground

See choosing a profile for which one suits your service.

In PHP, the engine built when PHP starts always uses MaxPerformance, so there is no profile to choose. See Performance options for the reason.

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.