ARTIFACTORY: Migration using Export/Import with Manual Filestore Transfer

Artifactory Migration using Export/Import with Manual Filestore Transfer

User-added image

Tip

This is one of many methods for migrating JFrog Artifactory. For a complete understanding of the overall migration process, we recommend reviewing our main article: 
Comprehensive Guide to Migrating JFrog Artifactory

Introduction

The Goal of this guide is to instruct step by step how to perform an Artifactory migration using Artifactory's built-in functionality Export & Import tool, while manually copying the binarystore(Filestore).

Decision table

Advantages

 Disadvantage

 Best For

Straightforward

Less downtime than basic import/export

Works for larger instances

Requires Downtime

Requires external tool/commands

Large instances needing a fast migration

Moving from one DB type to another

Terms

Source server: Server which we will export from. This server we would like to “mirror” to another one.

Target Server: The server which we will import the configuration to, and will be the exact replica of the Source Server.

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

Navigate to $JFROG_HOME/artifactory/var/etc/
Create a security folder if it doesn't already exist
Inside the security folder, create a file named master.key if it doesn't exist
Copy the master key content from your Source server located at: $JFROG_HOME/artifactory/var/etc/security/master.key
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

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

Step 4: Start and Validate

Start the Artifactory service
Insert your Artifactory license
Confirm that Artifactory starts successfully and is functioning properly

Migration process

Migration Timeline

User-added image

1. Initial Filestore Sync

Start by doing an initial sync of the Source Artifactory filestore to the Target Artifactory filestore.
This is to minimize the downtime required during the cutover and final sync, as most of the binaries will be transferred at this stage.

Locate your source filestore folder - This contains your JFrog data that needs to be transferred.
Choose your transfer method based on your setup:
- For local/network transfers: Use rsync for efficient copying with progress tracking
- For AWS environments: Use aws s3 sync if your target is S3-compatible storage
- For other cloud providers: Use their respective sync tools (Azure CLI, Google Cloud SDK, etc.)
- For basic transfers: Use scp or standard file copy commands
Execute the transfer.
Verify the transfer completed successfully by checking file counts and sizes match between source and destination

As the source is still receiving traffic during this time, another final sync will be required to bridge the delta gap created after this data transfer.


Important Note
For the target Artifactory to be a complete functioning replica of the source Artifactory, it is crucial that every artifact has both its metadata and binary file present respectively.

User-added image

2. Block Traffic

Block the source server from receiving requests. (This is to prevent data delta from forming during the rest of this process. For more info see Comprehensive Guide to Migrating JFrog Artifactory).
This can be achieved by creating a firewall, redirecting the LB or reverse proxy that points here or through any other method you prefer. Do not turn off the instance at this stage, we still need it.
For testing purposes we recommend you run through this process without performing this step and only perform this step during your actual migration.

3. Final Filestore Sync

Execute a final delta sync to transfer any remaining differences between the source and target filestore.

4. Export Process

Perform system export with the "Exclude Content & Output Verbose Log" checkboxes selected:. If you have Mission Control (E+ only), please select this also:

The export generates a folder named with a timestamp format yyyymmdd.hhmmss (for example: 20250526.143022).

User-added image

This operation will only export the Artifacts (Metadata & Repositories) and Artifactory configurations (users,packages,builds). Exclude content in this context is to exclude the actual binary files from being included in this export. We do not need them as we are manually syncing the binaires with the filestore sync.

Validate that the Export completed successfully via the artifactory-import-export.log generated in the Artifactory log directory.
Look for “Full system export completed successfully”
Transfer the exported directory (using your preferred method) from the Source Artifactory to the Target Artifactory

Tip
You can upload the exported folder after zipping it to your local Artifactory, and pull it from there to the Target Artifactory.


Once copied to the Target server,Grant the user running Artifactory on that server full permissions on that folder.

5. Import process

Login to the Target server Artifactory UI
Perform a system Import. Select "Output Verbose Log" and Mission Control (E+ only) if you have it. Do not exclude the content or metadata:

User-added image

This process will now import the artifacts from the source Artifactory, this process will search the configured filestore for the corresponding binary file for each Artifact included in the import. It is imperative that the target filestore has been fully synced (steps 2 and 3) to include every corresponding binary file that the system expects.

3. Monitor the system import process completion via the artifactory-import-export.log in the log directory. Look for ### Full system import finished ###

4. Allow some time for Artifactory to import the settings before logging to the UI

Note
Keep in mind that the login credentials are taken from the export, and they might differ from the original credentials set on the Target server.

5. Login to the UI and validate the Target server integrity by downloading and uploading an Artifact and checking the expected artifacts, users and packages are present and downloadable.

6. Go Live

Switch the traffic from pointing to the Source Artifactory server to the Target Artifactory server.

Note
After an import, Xray and Distribution services should be restarted.

Advanced option

If you intend to decommission the Source Artifactory, there is an option to simply link the existing source filestore to the Target Artifactory instead of running the filestore sync, saving space, transfer time, and delta gaps.

The main risk in using this method is in having two active Artifactories point to the same filestore. This can cause data inconsistencies between each Artifactory DB and its filestore.

For example, if the Source Artifactory deletes a binary, the Target Artifactory is not aware of this deletion. When this Artifact is then requested from the Target server, it will attempt to retrieve this binary and return a 500 server error “binary provider has no content for this Artifact”.

To prevent this issue we should ensure that the GC (Garbage Collector) does not run during the migration. This is done by navigating to Administration → Artifactory Settings → Maintenance → Garbage Collection and setting 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)
At the end of the migration process, please set back the GC to run regularly (Default: 0 0 /4 * * ?)

A quick overview of the steps involved in this option.

```
Disable GC
```
```
Block Traffic to source Artifactory
```
```
Export Process
```

Connect target Artifactory to source Artifactory filestore

```
Import Process 
```
```
Go live 
```
```
Decommission Source Artifactory
```
Re-enable GC

With the GC configured not to run, it is ok to temporarily have multiple different Artifactory instances pointed to the same filestore. Of course, any Artifact uploaded to one will not be visible on the other as the DB is not shared.

Option with no Downtime

If you can’t afford downtime, you can use this method without blocking traffic to Artifactory (step 2) and use the Jfrog CLI or repository replication to close the data delta that forms between step 3 and 6.

For the CLI, You can follow this documentation

For repository replication, you can follow this guide

Since most of the data has been transferred already, the use of these methods here is just to fill the delta gap. Both methods are suitable for this as they will only transfer artifacts that are missing from the target. Both methods can also be used to independently fully migrate Artifactory, but will be slower than using this combination.

Summary

This article covered the migration process using the import/export method combined with a manual filestore sync. This approach is fast and suitable for all instance types. For additional migration options and more in-depth information, refer to our Comprehensive Guide to Migrating JFrog Artifactory.