Comprehensive Guide to Migrating JFrog Artifactory

Artifactory migration

The goal of this guide is to provide instructions on how to migrate your Artifactory instance from one server to another correctly.

Understanding Artifactory's Core Components

Before diving into the migration process, it's essential to understand the foundational components that make up a JFrog Artifactory instance.
Artifactory consists of three core components:

 
 
Application Server (Artifactory Application)

This refers to the Artifactory application itself. It handles all Artifactory activities, including REST API requests, maintenance tasks, and replication. It requires a connection to a Database and filestore to operate. 
Two key configuration files are saved on the server. The first is system.yaml, which defines the database connection (among other things). The second is the master.key, which is used to encrypt sensitive data in the database.

Database

Stores all Artifactory-related data, such as user details, groups, permissions, repository configurations, and metadata for each artifact, including names and full paths. It also stores all the configuration information relating to application settings. 

Filestore (Binary Store)

Stores the actual binaries, organized by their SHA-1 checksum. Only the file itself is saved here; details like artifact name, path, and creation date are stored exclusively in the database.

Artifactory checksum-based Storage

Each unique binary file is stored only once, identified and located by its SHA-1 checksum.
Each binary is located in the filestore (local disk by default) and identified by its checksum (SHA-1), with all the metadata (such as package metadata, artifact names, sizes, creation dates, repo locations, SHA-256 values, and signatures) saved in the database.
Therefore, if the same binary is deployed multiple times or referenced from different repositories, Artifactory does not create redundant physical copies. Instead, the database stores multiple metadata entries that all point to the single binary file in the filestore via its checksum.

 


Migration Goal

A full migration necessitates a new application server and transferring both:

• The complete Database (all metadata and configuration information).
• The complete Filestore (all binary files) to the new environment. 

The specific method used for this transfer can vary, but the goal is always to ensure that the target instance, running the same version of Artifactory, becomes an exact operational replica of the source.

Getting Started

Note
This guide focuses on Artifactory 7.x migrations. While the fundamental principles are also relevant to Artifactory 6.x, users of older versions should note that certain file paths, screenshots, and specific information might vary.

Warning 
It is NOT recommended to migrate between different versions of Artifactory. 
Migration between different versions should be considered a last resort.

Migration vs. Upgrade

It is important to understand the difference between migrating and upgrading Artifactory:

• Migration: The process of moving an Artifactory instance from one server, data center, or cloud environment to another, while keeping the same Artifactory version.
• Upgrade: The process of updating an Artifactory instance from an older version to a newer version.
   

JFrog strongly recommends performing these operations separately. 

This document describes the process of migration.

If you want to both migrate and upgrade, then:

First, complete and verify the migration of your Artifactory instance to the new environment, ensuring it runs the exact same version as your source. 

Only after a successful migration should you proceed with upgrading the Artifactory version on the new instance.

If you desire to migrate to be able to upgrade Artifactory version, please head to this guide:
(For example, if you currently run Artifactory on Cent Os 7 and need to move to RedHat 8):

Migrate to a supported Operating System

Important Considerations

1. We highly recommend testing processes in a test environment to fully familiarize yourself with your chosen process before proceeding with a migration.
2. Data Delta: It is important to keep in mind data deltas. If we move artifact data from Server A to B whilst A is still receiving data, we will create a data delta of all Artifacts uploaded to A whilst the migration was in progress to B. This can be mitigated by 1 of 2 approaches:
   
   Downtime Approach:
   Stop traffic to the source Artifactory server during the migration,  preventing new data creation that won't exist on the target server.
   
   Continuous Migration Approach:
   Some migrations allow for continuous data transfer through the migration process allowing for a zero downtime migration.
   
   Each migration method will specify what approach is appropriate for it.

Prerequisite Steps 

It is required to provision a Target Artifactory instance as follows:

Step 1: Install Artifactory

Install the exact same version of Artifactory that's running on your Source server on the Target server (It may be a different install type). Do not start the Artifactory service yet.

Step 2: Copy The Master Key

1. Navigate to $JFROG_HOME/artifactory/var/etc/
2. Create a security folder if it doesn't already exist
3. Inside the security folder, create a file named master.key if it doesn't exist
4. Copy the master key content from your Source server located at: $JFROG_HOME/artifactory/var/etc/security/master.key
5. Set appropriate file permissions so the user running Artifactory has full access to the master.key file: 

   chown -R  artifactory:artifactory $JFROG_HOME/artifactory/var/etc/security/ 

Note
 
Copying the $JFROG_HOME/artifactory/var/etc/security/master.key is a critical step in the import process - for both single node and HA imports. The master.key is an AES secret key (128 or 256 bit) that is used by Artifactory for encrypting and decrypting the shared data in the database and is, therefore, required for the import process.

Step 3: Configure System Settings

1. Configure the system.yaml file with your desired settings, including the database connection details
   Location: $JFROG_HOME/artifactory/var/etc/system.yaml
2. Verify that binarystore.xml is configured according to your requirements.

Step 4: Start and Validate

1. Start the Artifactory service
2. Insert your Artifactory license
3. Confirm that Artifactory starts successfully and is functioning properly

(Optional) Step 5: Configure Garbage Collection

This step is only required if you will use the same external filestore on your source and target instance. 
Adjust the Garbage Collection (GC) schedule on both the source and target instances to prevent interference during migration:

1. Navigate to Administration → Artifactory Settings → Maintenance → Garbage Collection

2. Set the GC schedule to run at a time that won't conflict with your migration process
   Example cron expression: 0 0 0 ? 2030/1 * (runs starting in 2030)

3. At the end of the migration process, please set back the GC to run regularly (Default: 0 0 /4 * * ?)

Note

Garbage Collection is a vital maintenance procedure in Artifactory meant to ensure the system does not become clogged with unused binaries. Setting such extended intervals is not recommended as part of the day-to-day Artifactory maintenance and should be utilized for the migration period

Choosing the Right Migration Method

Migrating Artifactory offers flexibility, but the core principle remains constant: all your binary data (Filestore) and metadata (Database) must be successfully transferred to the new location.

The optimal method for your migration depends on several factors, including the size of your Artifactory instance, your acceptable downtime window, and the technical capabilities of your environment.

To help you determine the most suitable approach, consider these questions:

• What is the total size of your filestore?
• How much downtime can your organization tolerate for this migration (if any)?
• Are you migrating between different types of storage (e.g., local disk to S3)?
• Are you migrating between different database types?
  What network bandwidth and file transfer tools are available between the source and target environments?

The following table gives the options available:

Method

Downtime/Continuous

Best For

Key Pros

Key Cons

Summary

This article provides a comprehensive overview of Artifactory migration, covering key concepts and comparing various methods with their respective advantages. We strongly recommend testing all steps in a staging environment before proceeding with a production migration.