Upgrading from Artifactory Version 6.10.x Onwards to 7.x

The following table provides the version in 7.x you can upgrade from particular versions of 6.x.

Apart from the exceptions listed above, you can upgrade to any version of 7.x from any version from 6.10.x and above.

⚠️

Warning

If you use S3 as the filestore, before you upgrade from 6.23.28 and higher (6.23.28, 6.23.31, 6.23.33, 6.23.36, 6.23.37, 6.23.38) to version 7.x, provide the S3 credentials in a non-encrypted, plaintext format. Artifactory will no longer be able to decrypt the encrypted credentials due to change in the encryption algorithm in version 7.x. and fails to start after upgrade. The credentials are automatically encrypted after the upgrade.

There are several new concepts introduced in Artifactory 7.x, improving the installation and customization process. For example, a system.yaml file holds the configurations and customizations that you make to the Artifactory installation. Artifactory preserves your configuration during an upgrade.

Artifactory 6.x has access-admin and arti-admin users for Access and Artifactory respectively. In Artifactory 7.x, a global admin user handles administration across services. The access-admin and arti-admin users are still kept during the upgrade process. You can safely delete these users after the upgrade.

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

Artifactory System Requirements

Artifactory system requirements depend mainly upon the expected amount of active clients.

Number of Active Clients	Processor	Memory
0-20	4 core CPU	6 GB
20-100	6 core CPU	12 GB
100-200	8 core CPU	18 GB
200+	Contact JFrog Support	Contact JFrog Support

Operating Systems and Platform Support

The following table lists the supported operating systems and their versions:

Product	Debian	RHEL	Ubuntu	Amazon Linux	Windows Server
Artifactory	11.x, 12.x	8.x, 9.x	20.04, 22.04, 24.04	Amazon Linux 2023	2016, 2019, 2022

📘

Note

Debian 12.x and Ubuntu 24.04 are supported from Artifactory 7.104 and Distribution 2.28.

Windows 2022 is supported from Artifactory 7.125.

Supported Platforms

The following table lists the supported platforms:

Product	x86-64	ARM64	Kubernetes	OpenShift
Artifactory			1.27+	4.14+

Installation on Kubernetes environments is through Helm Charts. Supported Helm version is Helm 3.17+.

✅

Kubernetes Sizing Requirements

We have included YAML files with different sizing configurations for Artifactory , Xray, and Distribution in our GitHub pages. You can use these YAML files when you set up your cluster.

📘

ARM64 Support for Container-Based Installations

Artifactory, Xray and Distribution supports installation on ARM64 architecture specifically through Helm and Docker installations. When deploying a product on an ARM64 platform, an external database must be set up as Artifactory does not support the bundled database for ARM64 installations. The appropriate ARM64 Container Image is automatically pulled during the Helm or Docker installation process.

Artifactory Database Requirements

Artifactory supports the following databases:

• PostgreSQL

✅

Tip

JFrog highly recommends using PostgreSQL for all products in the JFrog Platform. For more information, see Choose the right database.

• Oracle
• MySQL
• Microsoft SQL Server
• MariaDB

Artifactory HA requires an external database, which is fundamental for the management of binaries and is also used to store cluster-wide configuration files.

Since Artifactory HA contains multiple Artifactory cluster nodes, your database must be powerful enough to service all the nodes in the system. Moreover, your database must be able to support the maximum number of connections possible from all the Artifactory cluster nodes in your system.

If you are replicating your database, you must ensure that at any given point in time, all nodes see a consistent view of the database, regardless of which specific database instance they access. Eventual consistency and write-behind database synchronization are not supported.

Artifactory File Store

The filestore is where the binaries are physically stored.

Artifactory provides the following options to store binaries:

• Local file system stores binaries with redundancy, using a binary provider that manages the synchronization of files between cluster nodes according to the defined redundancy settings.
• Cloud storage is done using Amazon S3, Microsoft Azure, and Google Cloud Storage.
• Network File System (NFS)

For more information, see Filestore Configuration.

Binary Storage

While Artifactory can use a Networked File System (NFS) for its binary storage, you should not install the application itself on an NFS. The Artifactory application needs very fast, reliable access to its configuration files. Any latency from an NFS will result in poor performance when the application fails to read these files. Therefore, install Artifactory on a local disk mounted directly to the host.

To use an NFS to store binaries, use the file-system binarystore.xml configuration with the additional <baseDataDir> setting.

Working with Very Large Storage

In most cases, our recommendation for storage is at least 3 times the total size of stored artifacts, in order to accommodate system backups.

However, when working with a very large volume of artifacts, the recommendation may vary greatly according to the specific setup of your system. Therefore, when working with over 10 TB of stored artifacts, contact JFrog support, who will work with you to provide a recommendation for storage that is customized to your specific setup.

📘

Allocated storage space may vary

Xray downloads and then deletes fetched artifacts after indexing. However, in order to have more parallel indexing processes, and thereby more temporary files at the same time would require more space.

This is especially applicable for large BLOBs such as Docker images.

Artifactory Network Ports

Artifactory uses external network ports to communicate with services outside Artifactory and internal network ports to communicate with Artifactory and other JFrog Platform microservices.

External Network Ports

Artifactory uses the following external network ports by default:

• 8081
• 8082

Internal Network Ports

Artifactory uses the following internal network ports.

Microservice	Port
Artifactory	HTTP: 8081, 8091
Frontend	HTTP: 8070
Access	HTTP: 8040, 8015 gRPC: 8045, 8016
Topology	HTTP: 8020 gRPC: 8021
One Model	HTTP: 8071 gRPC: 8072
Apollo Router	HTTP: 8074
Metadata	HTTP: 8086
Router	HTTP: 8082, 8046, 8049 gRPC: 8047
Observability	HTTP: 8036 gRPC: 8037
Event	HTTP:8061 gRPC: 8062
Mission Control	HTTP: 8080
JFConnect	HTTP: 8030 gRPC: 8035
JFConfig	HTTP: 8010
Evidence	HTTP: 8051
Artifactory Federation Service (RTFS)	HTTP: 8025 gRPC: 8026

The following upgrade methods are supported:

• Artifactory version 6.x to 7.x Linux Archive Upgrade
• Artifactory version 6.x to 7.x upgrade with Docker
• Artifactory version 6.x to 7.x upgrade with Docker Compose
• Artifactory version 6.x to 7.x upgrade using Docker Volumes
• Artifactory version 6.x to 7.x upgrade with RPM
• Artifactory version 6.x to 7.x upgrade with Debian
• Artifactory version 6.x to 7.x upgrade with Helm
• Artifactory version 6.x to 7.x upgrade in Windows

Artifactory version 6.x to 7.x upgrade with Helm

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

In addition, review the Helm Chart requirements.

Artifactory Upgrade from 6.x to 7.x

Upgrading from 6.x to 7.x requires a one time migration process. You have to enable the migration in the values.yaml file:

artifactory:
  migration:
    enabled: true

It is possible to configure the migration timeout with the following configuration in extreme cases. The default provided should be more than enough for completion of the migration.

artifactory:
  migration:
    enabled: true
    timeoutSeconds: 3600

Migrating the Master Key from Version 6.x to 7.x

Version 6.x only supports a masterKey with 16 hex (32 characters) and if you have set a masterKey using openssl rand -hex 32 (64 characters) in 6.x, only the first 32 characters are used and rest are ignored. When migrating from 6.x to 7.x, we trim the first 32 characters and set the masterkey, which implies that 7.x still uses the trimmed masterkey of 6.x. Therefore, the artifactory.masterKey should not be passed during migration from 6.x to 7.x.

⚠️

Upgrading from 8.x to 11.x and Above Chart Versions

If you are upgrading from 8.x to 11.x and above chart versions, remember to delete the existing PostgreSQL statefulset before upgrading the chart due to breaking changes in PostgreSQL subchart.

Run the following command.

Bash

kubectl delete statefulsets <OLD_RELEASE_NAME>-postgresql

Once you have a new chart version, you can upgrade your deployment.

Single Node Upgrade

1. Use the following command to upgrade.

   Bash

   helm upgrade artifactory --namespace artifactory jfrog/artifactory

2. If Artifactory was installed without providing a value to postgresql.postgresqlPassword (if the password was auto-generated), run the following command to get the current password.

   properties

   POSTGRES_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-postgresql -o jsonpath="{.data.postgresql-password}" | base64 --decode)

3. Upgrade the release by passing the previously auto-generated secret.

   Bash

   helm upgrade <myrelease> jfrog/artifactory --set postgresql.postgresqlPassword=${POSTGRES_PASSWORD} --namespace <namespace>

   This applies any configuration changes on your existing deployment.

HA Upgrade with the artifactory-ha chart

1. Use the following command to upgrade.

   Bash

   helm upgrade artifactory-ha --namespace artifactory-ha jfrog/artifactory-ha

2. If Artifactory was installed without providing a value to postgresql.postgresqlPassword (if the password was auto-generated), run the following command to get the current password.

   properties

   POSTGRES_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-postgresql -o jsonpath="{.data.postgresql-password}" | base64 --decode)

3. Upgrade the release by passing the previously auto-generated secret.

   Bash

   helm upgrade <myrelease> --namespace artifactory-ha jfrog/artifactory-ha --set postgresql.postgresqlPassword=${POSTGRES_PASSWORD}

   This applies any configuration changes on your existing deployment.

Artifactory version 6.x to 7.x upgrade with Docker Compose

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

In addition, review the Docker requirements.

1. Stop and remove the current containers.

   Upgrading from Docker run

   Bash

   docker stop artifactory
   docker rm -f artifactory

   Upgrading from Docker Compose previously available in Bintray

   Bash

   docker stop artifactory postgresql  nginx
   docker rm -f artifactory postgresql  nginx

2. Extract the contents of the compressed archive and go to the extracted folder.

   Bash

   tar -xvf jfrog-artifactory-<pro|oss|cpp-ce>-<version>-compose.tar.gz

❗️

.env file included within the Docker-Compose archive

The .env file is used by docker-compose and is updated during installations and upgrades.

Some operating systems do not display dot files by default. If you make any changes to the file, remember to backup before an upgrade.

3. Run the config.sh script to setup folders with required ownership.

   Bash

   ./config.sh

4. Check that the migration has completed successfully, by reviewing the following files:

   1. migration log: $JFROG_HOME/artifactory/var/log/migration.log
   2. system.yaml configuration: $JFROG_HOME/artifactory/var/etc/system.yaml. This newly created file will contain your current custom configurations in the new format.
   3. Depending on your choices, a selected docker-compose.yaml will be available in the extracted folder. However, there are a few docker-compose templates in the directory **_templates._You can choose any template and copy it to the extracted folder as docker-compose.yaml .

5. Manage Artifactory using native Docker Compose commands.

   Bash

   docker-compose -p rt-postgres -f 
   docker-compose-postgres-9-6-11v.yaml up -d
   docker-compose -p rt up -d
   docker-compose -p rt ps
   docker-compose -p rt down

6. Access Artifactory from your browser at: http://SERVER_HOSTNAME:8082/ui/.

   For example, on your local machine: http://localhost:8082/ui/

⚠️

Reverse Proxy Settings

If you had a reverse proxy or load balancer configured with your Artifactory 6.x, you will need to create a new reverse proxy configuration and update your reverse proxy settings.

You can generate a new configuration template by accessing the upgraded Artifactory server UI (by default http://localhost:8082/ui/), navigate to

Navigate to Administration > Artifactory > General > HTTP Settings to adjust your Reverse Proxy Settings and generate a new configuration template. See Reverse Proxy Settings.

7. Check Artifactory Log.

   Bash

   tail -f $JFROG_HOME/artifactory/var/log/console.log

⚠️

Configure log rotation of the console log

The console.log file can grow quickly since all services write to it. For more information, see configure the log rotation.

Artifactory version 6.x to 7.x Docker Compose Upgrade Using Docker Volumes

1. Stop and remove the current Docker containers.

   Bash

   docker stop artifactory postgresql
   docker rm -f artifactory postgresql

2. Extract the contents of the compressed archive and go to the extracted folder.

   Bash

   tar -xvf jfrog-artifactory-<pro|oss|cpp-ce>-<version>-compose.tar.gz
   ```bash

3. Copy the docker-compose-volumes.yaml file to the extracted folder.

   Bash

   cp templates/docker-compose-volumes.yaml docker-compose.yaml

4. Add the entry to the .env file.

   Bash

   echo -e "JF_SHARED_NODE_IP=$(hostname -i)" >> .env
   echo -e "JF_SHARED_NODE_ID=$(hostname -s)" >> .env
   echo -e "JF_SHARED_NODE_NAME=$(hostname -s)" >> .env

   Avoid duplicating the entry in the .env file.

5. Remove the following env from the docker-compose.yaml file.

   - JF_SHARED_DATABASE_TYPE=postgresql
   - JF_SHARED_DATABASE_USERNAME=artifactory
   - JF_SHARED_DATABASE_PASSWORD=password
   - JF_SHARED_DATABASE_URL=jdbc:postgresql://postgresql:5432/artifactory
   - JF_SHARED_DATABASE_DRIVER=org.postgresql.Driver

   Migration starts from within the container and a new system.yaml aligning to the migrated data from Artifactory 6.x is created. To leverage this process, remove the env here to ensure that the old connection details are taken from system.yaml because the ENV supercedes the system.yaml entries. You can also choose to update these environment values to the old connection details for the upgrade to be successful.

6. Manage Artifactory using the native Docker Compose commands.

   Bash

   docker-compose -p rt up -d
   docker-compose -p rt ps
   docker-compose -p rt down

   Run this command from the extracted folder.

Artifactory version 6.x to 7.x upgrade with Docker

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

In addition, review the Docker requirements.

📘

Note

The Docker upgrade only applies when upgrading from Artifactory 6.x to Artifactory 7.4.1 and above.

1. Stop and remove Artifactory using native Docker commands.

   Bash

   docker stop artifactory
   docker rm -f artifactory

2. Set the path to your current Artifactory home, and make sure the directory permissions are set correctly.

   Bash

   export ARTIFACTORY_HOME=<Mount Path to your current Artifactory data directory>
   chown -R 1030:1030 $ARTIFACTORY_HOME

3. Start the Artifactory container

   Bash

   docker run -e ENABLE_MIGRATION=y --name artifactory -v   $ARTIFACTORY_HOME:/var/opt/jfrog/artifactory -d -p 8081:8081 -p 8082:8082 releases-docker.jfrog.io/jfrog/artifactory-<pro|oss|cpp-ce>:latest

4. Access Artifactory from your browser at: http://SERVER_HOSTNAME:8082/ui/.

   For example, on your local machine: http://localhost:8082/ui/.

5. Check Artifactory Log.

   Bash

   docker logs -f artifactory

Artifactory version 6.x to 7.x upgrade with RPM

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

1. Stop the current server.

   Bash

   service artifactory stop

2. Install Artifactory as a service on Red Hat compatible Linux distributions, as a root user.

   Bash

   yum -y install jfrog-artifactory-<pro|oss|cpp-ce>-<version>

3. Check that the migration has completed successfully, by reviewing the following files:

   1. migration log: $JFROG_HOME/artifactory/var/log/migration.log

   2. system.yaml configuration: $JFROG_HOME/artifactory/var/etc/system.yaml

      This newly created file will contain your current custom configurations in the new format.

4. Manage Artifactory.

   Bash

   service artifactory start|stop

5. Access Artifactory from your browser at: http://SERVER_HOSTNAME:8082/ui/.

   For example, on your local machine: http://localhost:8082/ui/

⚠️

Reverse Proxy Settings

If you had a reverse proxy or load balancer configured with your Artifactory 6.x, you will need to create a new reverse proxy configuration and update your reverse proxy settings.

You can generate a new configuration template by accessing the upgraded Artifactory server UI (by default http://localhost:8082/ui/), navigate to

Navigate to Administration > Artifactory > General > HTTP Settings to adjust your Reverse Proxy Settings and generate a new configuration template. See Reverse Proxy Settings.

6. Check Artifactory Log.

   Bash

   tail -f $JFROG_HOME/artifactory/var/log/console.log

⚠️

Configure log rotation of the console log

The console.log file can grow quickly since all services write to it. For more information, see configure the log rotation.

Artifactory version 6.x to 7.x upgrade with Debian

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

1. Stop the current server.

   Bash

   service artifactory stop

2. Install Artifactory as a service on a Debian compatible Linux distributions, as a root user.

   Bash

   dpkg -i jfrog-artifactory-<pro|oss|cpp-ce>-<version>.deb

3. Check that the migration has completed successfully, by reviewing the following files:

   1. migration log: $JFROG_HOME/artifactory/var/log/migration.log

   2. system.yaml configuration: $JFROG_HOME/artifactory/var/etc/system.yaml

      This newly created file will contain your current custom configurations in the new format.

4. Manage Artifactory.

   Bash

   service artifactory start|stop

5. Access Artifactory from your browser at: http://SERVER_HOSTNAME:8082/ui/.

   For example, on your local machine: http://localhost:8082/ui/

⚠️

Reverse Proxy Settings

If you had a reverse proxy or load balancer configured with your Artifactory 6.x, you will need to create a new reverse proxy configuration and update your reverse proxy settings.

You can generate a new configuration template by accessing the upgraded Artifactory server UI (by default http://localhost:8082/ui/), navigate to

Navigate to Administration > Artifactory > General > HTTP Settings to adjust your Reverse Proxy Settings and generate a new configuration template. See Reverse Proxy Settings.

6. Check Artifactory Log.

   Bash

   tail -f $JFROG_HOME/artifactory/var/log/console.log

⚠️

Configure log rotation of the console log

The console.log file can grow quickly since all services write to it. For more information, see configure the log rotation.

Artifactory version 6.x to 7.x Linux Archive Upgrade

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

Migration is a manual process. The following steps also include copying directories over and running the migration script.

Make sure to run all commands on the server with the user that runs Artifactory.

1. Stop the current server.

   Bash

   cd $ARTIFACTORY_HOME/bin
   ./artifactoryctl stop

2. Extract the contents of the compressed archive and move it into artifactory directory.

   Bash

   tar -xvf jfrog-artifactory-<pro|oss|cpp-ce>-<version>-linux.tar.gz
   mkdir jfrog
   mv artifactory-<pro|oss|cpp-ce>-<version> jfrog/artifactory

3. Set your ARTIFACTORY_HOME and JFROG_HOME variables.

   Bash

   export ARTIFACTORY_HOME=<Path to your current Artifactory installation>
   export JFROG_HOME=<Full path to jfrog directory, for example: /opt/jfrog>
   export JF_PRODUCT_HOME=$JFROG_HOME/artifactory

   The $ARTIFACTORY_HOMEvariable points to your existing installation, and the $JFROG_HOME variable points to the new installation.

4. Copy the directories from your current to the new path.

   Mandatory Directories

   Bash

   # Artifactory data
   mkdir -p $JFROG_HOME/artifactory/var/data/artifactory/
   cp -rp $ARTIFACTORY_HOME/data/. $JFROG_HOME/artifactory/var/data/artifactory/
    
   # Access data
   mkdir -p $JFROG_HOME/artifactory/var/data/access/
   cp -rp $ARTIFACTORY_HOME/access/data/. $JFROG_HOME/artifactory/var/data/access/
    
    
   # Artifactory config
   mkdir -p $JFROG_HOME/artifactory/var/etc/artifactory/
   cp -rp $ARTIFACTORY_HOME/etc/. $JFROG_HOME/artifactory/var/etc/artifactory/
    
   # Access config
   mkdir -p $JFROG_HOME/artifactory/var/etc/access/
   cp -rp $ARTIFACTORY_HOME/access/etc/. $JFROG_HOME/artifactory/var/etc/access/
     
   # master.key
   mkdir -p $JFROG_HOME/artifactory/var/etc/security/
   cp -p $ARTIFACTORY_HOME/etc/security/master.key $JFROG_HOME/artifactory/var/etc/security/master.key
    
   # server.xml
   mkdir -p $JFROG_HOME/artifactory/var/work/old
   cp -p $ARTIFACTORY_HOME/tomcat/conf/server.xml $JFROG_HOME/artifactory/var/work/old/server.xml
    
   # artifactory.defaults
   cp -rp $ARTIFACTORY_HOME/bin/artifactory.default $JFROG_HOME/artifactory/var/work/old/artifactory.default
   #or, if Artifactory was installed a service
   cp -rp $ARTIFACTORY_HOME/etc/default $JFROG_HOME/artifactory/var/work/old/artifactory.default
    
   # External database driver, for example: mysql-connector-java-<version>.jar
   mkdir -p $JFROG_HOME/artifactory/var/bootstrap/artifactory/tomcat/lib
   cp -rp $ARTIFACTORY_HOME/tomcat/lib/<your database driver> $JFROG_HOME/artifactory/var/bootstrap/artifactory/tomcat/lib/<your database driver>
    
   # Remove logback.xml with old links. Please consider migrating manually anything that is customized here
   rm -f $JFROG_HOME/artifactory/var/etc/artifactory/logback.xml
   rm -f $JFROG_HOME/artifactory/var/etc/access/logback.xml
    
   # Move Artifactory logs
   mkdir -p $JFROG_HOME/artifactory/var/log/archived/artifactory/
   cp -rp $ARTIFACTORY_HOME/logs/. $JFROG_HOME/artifactory/var/log/archived/artifactory/
    
   # Move configuration files
   # Note: Run the following only when upgrading from Artifactory version 6.x to version 7.5.x and above.
   mkdir -p $JFROG_HOME/artifactory/var/etc/artifactory/old
   mkdir -p $JFROG_HOME/artifactory/var/etc/access/old
   cp $JFROG_HOME/artifactory/var/etc/artifactory/db.properties  $JFROG_HOME/artifactory/var/etc/artifactory/old/db.properties
   cp $JFROG_HOME/artifactory/var/etc/artifactory/ha-node.properties  $JFROG_HOME/artifactory/var/etc/artifactory/old/ha-node.properties
   cp $JFROG_HOME/artifactory/var/etc/access/db.properties   $JFROG_HOME/artifactory/var/etc/access/old/db.properties

   Additional directories for HA

   Replace any relative paths in the$ARTIFACTORY_HOME/etc/ha-node.propertiesfile with absolute paths.

   Bash

   # relative path
   artifactory.ha.data.dir=artifactory-ha
   # absolute path
   artifactory.ha.data.dir=/var/opt/jfrog/artifactory-ha

   Optional Steps

   Bash

   # Artifactory backup (optional)
   mkdir -p $JFROG_HOME/artifactory/var/backup/artifactory/
   cp -rp $ARTIFACTORY_HOME/backup/. $JFROG_HOME/artifactory/var/backup/artifactory/
    
   # Access backup (optional)
   mkdir -p $JFROG_HOME/artifactory/var/backup/access/
   cp -rp $ARTIFACTORY_HOME/access/data/. $JFROG_HOME/artifactory/var/backup/access/
   
   # Access logs (optional)
   mkdir -p $JFROG_HOME/artifactory/var/log/archived/access/
   cp -rp $ARTIFACTORY_HOME/access/logs/. $JFROG_HOME/artifactory/var/log/archived/access/

⚠️

Warning

When you upgrade Artifactory using Linux Archive, verify that the copied directories and the copied content have the right owners.

If you are using the default user:group, the owner is automatically assigned artifactory:artifactory, and you need need take any further actions (the upgrade will use these by default).

If, however, you are using a custom user:group, you need to go the Artifactory system.yaml file and update it with the custom user:group. You then need to make sure that the directory has the same user and group.

5. Run the migration script with the same privileges as you have in your current Artifactory installation.

   The script copies over and translate your current configurations to the new configuration format, according to the new file system layout.

   Bash

   cd $JFROG_HOME/artifactory/app/bin
   ./migrate.sh

   The migration script only migrates configuration values. Any comments added to the configuration files in the Artifactory 6.x installation are not migrated.

6. Check that the migration has completed successfully, by reviewing the following files.

   migration.log: $JFROG_HOME/artifactory/var/log/migration.log

   system.yaml: $JFROG_HOME/artifactory/var/etc/system.yaml This newly created file contains your current custom configurations in the new format.

7. If Artifactory was installed as a service in previous version, install this version also as a service.

   Bash

   cd $JFROG_HOME/artifactory/app/bin
   ./installService.sh

   Otherwise, a restart of the server may lead to older version of Artifactory coming up.

8. Manage Artifactory.

   Bash

   $JFROG_HOME/artifactory/app/bin/artifactoryctl start|stop|check

9. Access Artifactory from your browser at: http://SERVER_HOSTNAME:8082/ui/.

   For example, on your local machine: http://localhost:8082/ui/

⚠️

Reverse Proxy Settings

If you had a reverse proxy or load balancer configured with your Artifactory 6.x, you will need to create a new reverse proxy configuration and update your reverse proxy settings.

You can generate a new configuration template by accessing the upgraded Artifactory server UI (by default http://localhost:8082/ui/), navigate to

Navigate to Administration > Artifactory > General > HTTP Settings to adjust your Reverse Proxy Settings and generate a new configuration template. See Reverse Proxy Settings.

10. Check Artifactory Log.

    Bash

    tail -f $JFROG_HOME/artifactory/var/log/console.log

⚠️

Configure log rotation of the console log

The console.log file can grow quickly since all services write to it. For more information, see configure the log rotation.

Artifactory version 6.x to 7.x upgrade in Windows

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

Migration is a manual process for a Windows installation. The following steps also include copying directories over and running the migration script.

Make sure to run all commands on the server with the user that runs Artifactory.

1. Stop the current server.

   Bash

   cd %ARTIFACTORY_HOME%\bin
   artifactory.bat stop

   If you are running the Artifactory service as a process, stop the service from Services. Press the Windows key +R and enter services.msc to access Services.

2. Extract the contents of the compressed archive, move it into a newly created jfrog\artifactory folder, and go to the new folder.

   Make sure to run all commands on the server with the user that runs Artifactory.

3. Set your ARTIFACTORY_HOME and JFROG_HOME variables.

   XML

   SET ARTIFACTORY_HOME=<Path to your current Artifactory installation>
   SET JFROG_HOME=<Path to jfrog folder>
   SET JF_PRODUCT_HOME=%JFROG_HOME%/artifactory

   The $ARTIFACTORY_HOME variable points to your existing installation, and the $JFROG_HOME variable points to the new installation.

   When you set the ARTIFACTORY_HOME and JFROG_HOME variables, make sure to use Windows short name or escape space. For more information, see here.

4. Copy the directories from your current to the new path. Ignore if the target directory exists.

   Mandatory Steps

   Bash

   # Artifactory data
    
   mkdir %JFROG_HOME%\artifactory\var\data\artifactory
   xcopy %ARTIFACTORY_HOME%\data %JFROG_HOME%\artifactory\var\data\artifactory /E /q
     
   # Access data
   mkdir %JFROG_HOME%\artifactory\var\data\access
   xcopy %ARTIFACTORY_HOME%\access\data %JFROG_HOME%\artifactory\var\data\access /E /q
      
   # Artifactory config
   mkdir %JFROG_HOME%\artifactory\var\etc\artifactory
   xcopy %ARTIFACTORY_HOME%\etc %JFROG_HOME%\artifactory\var\etc\artifactory /E /q
     
   # Access config
   mkdir %JFROG_HOME%\artifactory\var\etc\access
   xcopy %ARTIFACTORY_HOME%\access\etc %JFROG_HOME%\artifactory\var\etc\access /E /q
      
   # master.key
   mkdir %JFROG_HOME%\artifactory\var\etc\security
   xcopy %ARTIFACTORY_HOME%\etc\security\master.key %JFROG_HOME%\artifactory\var\etc\security /q
     
   # server.xml
   mkdir %JFROG_HOME%\artifactory\var\work\old
   xcopy %ARTIFACTORY_HOME%\tomcat\conf\server.xml %JFROG_HOME%\artifactory\var\work\old /q
     
   # External database driver, for example: mysql-connector-java-<version>.jar
   xcopy %ARTIFACTORY_HOME%\tomcat\lib\<your database driver> %JFROG_HOME%\artifactory\app\artifactory\tomcat\lib /q
    
   # Change ownership of new Artifactory directory to the user intended to run Artifactory.
   # This can be skipped if you performed all previous steps with the user intended to run Artifactory.
    
   # Remove logback.xml with old links. Please consider migrating manually anything that is customized here
   del %JFROG_HOME%\artifactory\var\etc\artifactory\logback.xml
   del %JFROG_HOME%\artifactory\var\etc\access\logback.xml
    
   # Move configuration files
   # Note: Run the following only when upgrading from Artifactory version 6.x to version 7.5.x and above.
   mkdir %JFROG_HOME%\artifactory\var\etc\artifactory\old
   mkdir %JFROG_HOME%\artifactory\var\etc\access\old
    
   move /Y %JFROG_HOME%\artifactory\var\etc\artifactory\db.properties %JFROG_HOME%\artifactory\var\etc\artifactory\old\db.properties
   move /Y %JFROG_HOME%\artifactory\var\etc\artifactory\ha-node.properties %JFROG_HOME%\artifactory\var\etc\artifactory\old\ha-node.properties
   move /Y %JFROG_HOME%\artifactory\var\etc\access\db.properties  %JFROG_HOME%\artifactory\var\etc\access\old\db.properties

   Optional Steps

   Bash

   # Artifactory backup (optional)
    
   mkdir %JFROG_HOME%\artifactory\var\backup\artifactory
   xcopy %ARTIFACTORY_HOME%\backup %JFROG_HOME%\artifactory\var\backup\artifactory /E /q
     
   # Access backup (optional)
   mkdir %JFROG_HOME%\artifactory\var\backup\access
   xcopy %ARTIFACTORY_HOME%\access\backup %JFROG_HOME%\artifactory\var\backup\access /E /q
     
   # Artifactory logs (optional)
   mkdir %JFROG_HOME%\artifactory\var\log\artifactory
   xcopy %ARTIFACTORY_HOME%\logs %JFROG_HOME%\artifactory\var\log\artifactory /E /q
     
   # Access logs (optional)
   mkdir %JFROG_HOME%\artifactory\var\log\access
   xcopy %ARTIFACTORY_HOME%\access\logs %JFROG_HOME%\artifactory\var\log\access /E /q
     
   # Copy specific files from your current to the new path.

5. For HA installations, replace any relative paths in the %ARTIFACTORY_HOME%\etc__ha-node.properties file with absolute paths.

   Bash

   # relative path
   artifactory.ha.data.dir=artifactory-ha
   # absolute path
   artifactory.ha.data.dir=\var\opt\jfrog\artifactory-ha

6. Run the migration script with the same privileges as you have in your current Artifactory installation. This script will copy over and translate your current configurations to the new configuration format, according to the new file system layout.

   Bash

   cd %JFROG_HOME%\artifactory\app\bin
   migrate.bat

⚠️

Warning

The migration script only migrates configuration values. Any comments added to the configuration files in the Artifactory 6.x installation will not be migrated.

7. Check that the migration has completed successfully, by reviewing the following files.

   1. migration log: %JFROG_HOME%\artifactory\var\log\migration.log

   2. system.yaml configuration: %JFROG_HOME%\artifactory\var\etc\system.yaml

      This newly created file will contain your current custom configurations in the new format.

8. Manage Artifactory.

   Bash

   %JFROG_HOME%\artifactory\app\bin\artifactory.bat start|stop

📘

Note

When you start Artifactory, you may get some firewall exception messages. Select private networks and allow access to continue working.

9. To install Artifactory as a Windows service, follow the steps here.

10. Access Artifactory from your browser at: http://SERVER_HOSTNAME:8082/ui/.

    For example, on your local machine: http://localhost:8082/ui/

⚠️

Reverse Proxy Settings

If you had a reverse proxy or load balancer configured with your Artifactory 6.x, you will need to create a new reverse proxy configuration and update your reverse proxy settings.

You can generate a new configuration template by accessing the upgraded Artifactory server UI (by default http://localhost:8082/ui/), navigate to

Navigate to Administration > Artifactory > General > HTTP Settings to adjust your Reverse Proxy Settings and generate a new configuration template. See Reverse Proxy Settings.

11. Check the artifactory-service.log.

    type %JFROG_HOME%\artifactory\var\log\artifactory-service.log

Metadata Migration in the JFrog Platform

The JFrog Metadata server is a JFrog Platform microservice that is used for storing, managing, and sharing metadata between different components of the JFrog Platform. The microservice is part of JFrog Artifactory and is bundled with JFrog Artifactory 7.x installations. The microservice is used to store and share metadata for all packages from any JFrog services, such as Artifactory and JFrog Xray, and has its own configuration settings and logs files.

When upgrading from one version of Artifactory to another, the metadata must also be migrated to the new version. The length of this process will vary depending on the number of packages being migrated - as well as the number of versions being migrated.

📘

Note

This migration occurs automatically when upgrading from JFrog Artifactory 6.x to 7.x and requires no user action.

Fetching Metadata Using GraphQL

GraphQL is a query language that enables you to query your APIs and fetch specific data you need. Using GraphQL to query metadata provides a simple way to fetch packages data stored in the metadata microservice. To learn more, see GraphQL.

Viewing Metadata in the JFrog Platform UI

The Metadata server stores metadata, collected or calculated, from all the different JFrog products and services.

The Metadata data-model is used to manage the package-versions metadata, which can be consumed using various filters and search options through the JFrog platform UI - "Packages View". To learn more, see Package Management.

Frequently Asked Questions on Metadata Migration

❓What happens to the UI during the migration?

A: When the migration takes place, the JFrog Platform UI displays a notification that the metadata is currently being migrated.

❓What happens if the migration stops in the middle?

A: The migration will continue from the same point the next time Artifactory is started.

❓Does the migration happen during or after the upgrade?

A: The migration occurs after the upgrade, and will be triggered on the first system initialization after the upgrade (the first time you start Artifactory v7.x).

❓Is there any downtime during migration?

A: JFrog tested the migration process using a benchmark of Artifactory of 27k packages and 1.2M versions:

• Artifactory ran with the default migration configurations (5 threads migrating to MDS).
• The Artifactory and a PostgreSQL database were run on different machines with the following spec - GCP VM with 8 CPU & 30 Gb RAM.

❓Does the migration cause downtime?

A: There is no downtime caused by the migration, however, search results in the UI and in the GraphQL API will be limited.

❓How long will the migration take and what is the rate of conversion?

A: Based on the benchmark above, the migration rate was 60k-67k versions per hour. The total migration using these specifications took between 18-22 hours.

Database Details

Database Connections

The Metadata service uses a database connection pool that by default contains 100 connections. Running Artifactory with the default MDS migration settings (5 threads migrating metadata), no significant raise in the active connections to the database (about 10 live connections) were detected.In the worst case, the number of connections will not pass 100 connections.

CPU

• The PostgreSQL CPU max value was 60%.
• The MDS CPU max value was 23%

RAM

• The PostgreSQL RAM consumption was about 5%
• The MDS RAM consumption was about 10%

Storage

The database size increased from 95GB to 155GB (~60% increase).

Managing the Metadata Migration Process

Customers can control the metadata migration by limiting the number of threads in Artifactory (threads<=1 means that the migration is off):

shared.extraJavaOpts
-Dartifactory.metadata.event.operator.threads=5

PostgreSQL: To check the migration status, query the PostgreSQL database as follows.

SELECT encode(
           migration_info_blob::bytea, 
           'escape'
       ) 
FROM migration_status 
WHERE identifier = 'metadata-service-migration';

Oracle DB: To check the migration status, query the Oracle database as follows:

SELECT UTL_RAW.CAST_TO_VARCHAR2(
           DBMS_LOB.SUBSTR(migration_info_blob)
       ) 
FROM migration_status 
WHERE identifier = 'metadata-service-migration';

Upgrading from Artifactory Version Below 6.10

To upgrade from a version below 6.10.x, you first need to upgrade to version 6.10.x (or any 6.x version above 6.10.x) as described in the Upgrading Artifactory 6.x documentation, and then continue to upgrading from version 6.10 to 7.x.

Before you proceed, see System Requirements for information on supported platforms, supported browsers, and other requirements.

Artifactory System Requirements

Artifactory system requirements depend mainly upon the expected amount of active clients.

Number of Active Clients	Processor	Memory
0-20	4 core CPU	6 GB
20-100	6 core CPU	12 GB
100-200	8 core CPU	18 GB
200+	Contact JFrog Support	Contact JFrog Support

Operating Systems and Platform Support

The following table lists the supported operating systems and their versions:

Product	Debian	RHEL	Ubuntu	Amazon Linux	Windows Server
Artifactory	11.x, 12.x	8.x, 9.x	20.04, 22.04, 24.04	Amazon Linux 2023	2016, 2019, 2022

📘

Note

Debian 12.x and Ubuntu 24.04 are supported from Artifactory 7.104 and Distribution 2.28.

Windows 2022 is supported from Artifactory 7.125.

Supported Platforms

The following table lists the supported platforms:

Product	x86-64	ARM64	Kubernetes	OpenShift
Artifactory			1.27+	4.14+

Installation on Kubernetes environments is through Helm Charts. Supported Helm version is Helm 3.17+.

✅

Kubernetes Sizing Requirements

We have included YAML files with different sizing configurations for Artifactory , Xray, and Distribution in our GitHub pages. You can use these YAML files when you set up your cluster.

📘

ARM64 Support for Container-Based Installations

Artifactory, Xray and Distribution supports installation on ARM64 architecture specifically through Helm and Docker installations. When deploying a product on an ARM64 platform, an external database must be set up as Artifactory does not support the bundled database for ARM64 installations. The appropriate ARM64 Container Image is automatically pulled during the Helm or Docker installation process.

Artifactory Database Requirements

Artifactory supports the following databases:

• PostgreSQL

✅

Tip

JFrog highly recommends using PostgreSQL for all products in the JFrog Platform. For more information, see Choose the right database.

• Oracle
• MySQL
• Microsoft SQL Server
• MariaDB

Artifactory HA requires an external database, which is fundamental for the management of binaries and is also used to store cluster-wide configuration files.

Since Artifactory HA contains multiple Artifactory cluster nodes, your database must be powerful enough to service all the nodes in the system. Moreover, your database must be able to support the maximum number of connections possible from all the Artifactory cluster nodes in your system.

If you are replicating your database, you must ensure that at any given point in time, all nodes see a consistent view of the database, regardless of which specific database instance they access. Eventual consistency and write-behind database synchronization are not supported.

Artifactory File Store

The filestore is where the binaries are physically stored.

Artifactory provides the following options to store binaries:

• Local file system stores binaries with redundancy, using a binary provider that manages the synchronization of files between cluster nodes according to the defined redundancy settings.
• Cloud storage is done using Amazon S3, Microsoft Azure, and Google Cloud Storage.
• Network File System (NFS)

For more information, see Filestore Configuration.

Binary Storage

While Artifactory can use a Networked File System (NFS) for its binary storage, you should not install the application itself on an NFS. The Artifactory application needs very fast, reliable access to its configuration files. Any latency from an NFS will result in poor performance when the application fails to read these files. Therefore, install Artifactory on a local disk mounted directly to the host.

To use an NFS to store binaries, use the file-system binarystore.xml configuration with the additional <baseDataDir> setting.

Working with Very Large Storage

In most cases, our recommendation for storage is at least 3 times the total size of stored artifacts, in order to accommodate system backups.

However, when working with a very large volume of artifacts, the recommendation may vary greatly according to the specific setup of your system. Therefore, when working with over 10 TB of stored artifacts, contact JFrog support, who will work with you to provide a recommendation for storage that is customized to your specific setup.

📘

Allocated storage space may vary

Xray downloads and then deletes fetched artifacts after indexing. However, in order to have more parallel indexing processes, and thereby more temporary files at the same time would require more space.

This is especially applicable for large BLOBs such as Docker images.

Artifactory Network Ports

Artifactory uses external network ports to communicate with services outside Artifactory and internal network ports to communicate with Artifactory and other JFrog Platform microservices.

External Network Ports

Artifactory uses the following external network ports by default:

• 8081
• 8082

Internal Network Ports

Artifactory uses the following internal network ports.

Microservice	Port
Artifactory	HTTP: 8081, 8091
Frontend	HTTP: 8070
Access	HTTP: 8040, 8015 gRPC: 8045, 8016
Topology	HTTP: 8020 gRPC: 8021
One Model	HTTP: 8071 gRPC: 8072
Apollo Router	HTTP: 8074
Metadata	HTTP: 8086
Router	HTTP: 8082, 8046, 8049 gRPC: 8047
Observability	HTTP: 8036 gRPC: 8037
Event	HTTP:8061 gRPC: 8062
Mission Control	HTTP: 8080
JFConnect	HTTP: 8030 gRPC: 8035
JFConfig	HTTP: 8010
Evidence	HTTP: 8051
Artifactory Federation Service (RTFS)	HTTP: 8025 gRPC: 8026