Platform Installation with Ansible

Configure the JFrog Platform Ansible collection for production: set up an external PostgreSQL database, enable Artifactory HA with serial playbook execution, encrypt secrets with Ansible Vault, configure TLS and mTLS via NGINX, and run upgrades across all products. If you have not installed yet, start with the Ansible Quick Start.

The JFrog Ansible collection covers the following scope:

• Roles included: JFrog Artifactory, JFrog Xray, JFrog Distribution, and optionally PostgreSQL and NGINX.
• Supported target OS: Linux only (Ubuntu 20.04/22.04/24.04, RHEL 8.x/9.x, Debian 11.x/12.x) — Windows is not supported as a target host.
• Collection resources: The ansible_collections directory contains the collection package, and the examples directory contains playbooks for common architectures.

For license requirements by product combination, see the License Matrix.

Key Configuration Variables

The following variables control the most common production configuration scenarios. Set them in group_vars/all/vars.yml or pass via --extra-vars at playbook runtime.

Override the system.yaml File in Ansible Installations

From jfrog.platform collection version 10.11.x, if you use fully qualified collection names (FQCN), install the required dependencies first: ansible-galaxy collection install community.postgresql community.general ansible.posix.

By default, the <product>_systemyaml_override flag is set to false, which means edits to the existing YAML are not applied. Set the flag to true to override existing configurations. For example:

artifactory_systemyaml_override: true

Use Ansible Vault to Encrypt Variables

Keep sensitive variables in a separate file and encrypt them with Ansible Vault:

ansible-vault encrypt secret-vars.yml --vault-password-file ~/.vault_pass.txt

Include the encrypted file in your playbook:

- hosts: artifactory_servers
  vars_files:
    - ./vars/secret-vars.yml
    - ./vars/vars.yml
  roles:
    - artifactory

Use an External Database with the Ansible Installation

1. Set postgres_enabled: false in group_vars/all/vars.yml.

2. Configure the database connection for each product. The following example shows the Artifactory database configuration:

   YAML

   postgres_enabled: false
   
   artifactory_db_type: postgresql
   artifactory_db_driver: org.postgresql.Driver
   artifactory_db_name: <external_db_name>
   artifactory_db_user: <external_db_user>
   artifactory_db_password: <external_db_password>
   artifactory_db_url: jdbc:postgresql://<external_db_host>:5432/{{ artifactory_db_name }}

Configure xray_db_url and distribution_db_url in the same file for other products.

Create the PostgreSQL Database for the Ansible Installation

For supported PostgreSQL versions, see Artifactory PostgreSQL Support.

Create the Artifactory user and database with appropriate permissions:

CREATE USER artifactory WITH PASSWORD 'password';
CREATE DATABASE artifactory WITH OWNER=artifactory ENCODING='UTF8';
GRANT ALL PRIVILEGES ON DATABASE artifactory TO artifactory;

Grant Artifactory full privileges on the database.

Configure Artifactory to Use PostgreSQL in an Ansible Installation

When Artifactory uses PostgreSQL, artifact metadata is stored in PostgreSQL while binaries are stored in the filestore at $JFROG_HOME/artifactory/var/data/artifactory/filestore. Do not store BLOBs inside PostgreSQL — the PostgreSQL driver does not support streaming BLOBs with unknown length, so Artifactory temporarily saves deployed files to disk before writing them to the database.

Configure Artifactory to Use PostgreSQL Single Node in Ansible

1. Stop the Artifactory service.

2. Edit the database connection details in the system.yaml configuration file:

   YAML

   shared:
     database:
       type: postgresql
       driver: org.postgresql.Driver
       url: jdbc:postgresql://<your_db_host>:5432/artifactory
       username: artifactory
       password: password

3. Start the Artifactory service.

Configure Artifactory HA Nodes to Use PostgreSQL in Ansible

1. Stop the Artifactory service.

2. Edit system.yaml to update the database URLs. Artifactory uses multiple drivers, so configure the connection string for each separately:

   1. The url field under the shared database section:

      Text

      jdbc:postgresql://<PostgreSQL_DB_1_URL>,...,<PostgreSQL_DB_N_URL>/artifactory?targetServerType=primary

   2. The url field under the metadata database section:

      Text

      jdbc:postgresql://<PostgreSQL_DB_1_URL>,...,<PostgreSQL_DB_N_URL>/artifactory?target_session_attrs=read-write

   Example system.yaml:

   YAML

   systemYaml:
     shared:
       database:
         type: postgresql
         url: "jdbc:postgresql://17.21.0.2:5432,17.21.0.3:5432/artifactory?targetServerType=primary"
         driver: org.postgresql.Driver
         username: "artifactory"
         password: "password"
     metadata:
       database:
         type: postgresql
         url: "jdbc:postgresql://17.21.0.2:5432,17.21.0.3:5432/artifactory?target_session_attrs=read-write"
         driver: org.postgresql.Driver
         username: "artifactory"
         password: "password"

3. Start the Artifactory service.

Enable TLS Encryption in Ansible Installation

To enable TLS encryption for PostgreSQL, set sslmode=verify-full in the JDBC connector URL. For example, in $JFROG_HOME/artifactory/var/etc/system.yaml:

shared:
  database:
    url: jdbc:postgresql://mypostgress.mydomain.com:5432/artifactory?ssl=true&sslfactory=org.postgresql.ssl.jdbc4.LibPQFactory&sslmode=verify-full&sslrootcert=/tmp/server.crt

📘

If you use old certificates or an AWS RDS instance created before July 2020, Subject Alternative Name (SAN) may not be enabled. Generate a new certificate with SAN to resolve this.

High Availability (HA) Ansible Installation

HA is supported for Artifactory. By default, the collection installs in a single-node configuration.

To enable High Availability for Artifactory, set the following in roles/artifactory/defaults/main.yml. Add serial mode to your playbook to prevent parallel node startup, which is not supported and causes the installation to fail.

artifactory_ha_enabled: true

Alternatively, pass artifactory_ha_enabled=true as an extra variable for a fresh installation:

ansible-playbook -vv platform.yml -i hosts.ini --extra-vars "artifactory_ha_enabled=true"

To enable HA on an existing single-node installation:

ansible-playbook -vv platform.yml -i hosts.ini --extra-vars "artifactory_ha_enabled=true artifactory_systemyaml_override=true"

⚠️

Serial mode required for HA installations

By default, Ansible manages all machines in parallel. Starting all Artifactory nodes simultaneously is not supported and causes the installation to fail. Add serial mode to your playbook when installing or upgrading in HA mode:

YAML

- hosts: artifactory_servers
  serial:
    - 1
    - 100%
  roles:
    - role: artifactory
      when: artifactory_enabled | bool

The default HA node behavior works as follows:

• All nodes are primary nodes by default, so every node in the cluster can perform replication, garbage collection, backups, and import/export operations.
• Automatic failover: When a node goes down, other nodes take over automatically.
• taskAffinity: any is set by default on all nodes for Artifactory 7.17.4 and later, configured under the Nodes section in the Artifactory Configuration YAML.
• To disable task affinity on a specific node: Set taskAffinity: none to remove this attribute from a specific node.

Build the Ansible Collection Archive

1. Go to the ansible_collections/jfrog/installers directory.

2. Update the galaxy.yml meta file and increment the version.

3. Build the archive (requires Ansible 2.9+):

   Bash

   ansible-galaxy collection build

Set SSL Certificate and Key for Nginx for the Ansible Installation

Set artifactory_nginx_ssl_enabled: true in roles/artifactory/defaults/main.yml. This enables the artifactory_nginx_ssl role.

Configure the following variables in the artifactory_nginx_ssl role:

• server_name: The server name. For example, artifactory.54.105.51.178.xip.io.
• certificate: The SSL certificate.
• certificate_key: The SSL private key.
• nginx_worker_processes: The worker_processes configuration for Nginx. Default is 1.
• artifactory_docker_registry_subdomain: Whether to add a redirect directive for Docker subdomains.

Configure mTLS in Artifactory with NGINX

To enable mTLS (Mutual TLS) authentication in Artifactory through NGINX:

Step 1: NGINX Changes

1. Open platform/products/ansible/ansible_collections/jfrog/platform/roles/artifactory_nginx_ssl/defaults/main.yml.

2. Set mtls_ca_certificate_install to true.

3. Create a CA certificate:

   Bash

   openssl req -new -x509 -nodes -days 365 -subj '/CN=my-ca' -keyout ca.key -out ca.crt

   📘

   CA certificates in mTLS verify the authenticity of client and server certificates, ensuring mutual authentication.

4. Place ca.crt and ca.key in the same directory as main.yml.

5. Add the following parameters to main.yml:

   YAML

   mtls_ca_certificate_crt: |
     <CA_CERTIFICATE_CONTENT>
   mtls_ca_certificate_key: |
     <CA_KEY_CONTENT>

Step 2: Artifactory Changes

1. Open platform/products/ansible/ansible_collections/jfrog/platform/roles/artifactory/defaults/main.yml.

   Under the artifactory_access_config_patch section, add:

   YAML

   security:
     authentication:
       mtls:
         enabled: true
         extraction-regex: (.*)

2. In the same main.yml, update:

   YAML

   artifactory_nginx_ssl_enabled: true
   artifactory_nginx_enabled: false

   For more information, see Set up mTLS Verification and Certificate Termination on the Reverse Proxy.

3. Validate the client:

   1. Generate a server key:

      Bash

      openssl genrsa -out server.key 2048

   2. Create a Certificate Signing Request (CSR):

      Bash

      openssl req -new -key server.key -subj '/CN=localhost' -out server.csr

   3. Generate the server certificate using the CA from Step 1:

      Bash

      openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -days 365 -out server.crt

      This generates server.crt signed by the CA certificate (ca.crt) and key (ca.key) created in Step 1.

4. Test the mTLS setup:

   Bash

   curl -u <username>:<password> "http://<artifactory-url>/artifactory/api/system/ping" --cert server.crt --key server.key -k

Upgrading JFrog Platform for the Ansible Collection

All JFrog product roles support software upgrades. Use the <product>_upgrade_only variable and specify the target version.

⚠️

Before upgrading

Back up your system and database before starting an upgrade. See the System Maintenance and Monitoring guide for backup and restore instructions.

- hosts: artifactory_servers
  vars:
    artifactory_version: "{{ lookup('env', 'artifactory_version_upgrade') }}"
    artifactory_upgrade_only: true
  roles:
    - artifactory
- hosts: xray_servers
  vars:
    xray_version: "{{ lookup('env', 'xray_version_upgrade') }}"
    xray_upgrade_only: true
  roles:
    - xray

Frequently Asked Questions

❓ How do I enable High Availability for Artifactory in an Ansible installation?

A: Set artifactory_ha_enabled: true in roles/artifactory/defaults/main.yml, or pass --extra-vars "artifactory_ha_enabled=true" when running the playbook. Add serial mode to your playbook to prevent parallel startup failures. See High Availability (HA) Ansible Installation for the full configuration.

❓ How do I configure an external PostgreSQL database for the Ansible installation?

A: Set postgres_enabled: false in group_vars/all/vars.yml and configure artifactory_db_url, xray_db_url, and distribution_db_url to point to your external PostgreSQL host. Create the databases and users before running the playbook. See Use an External Database with the Ansible Installation for the full configuration.

❓ How do I upgrade JFrog products using the Ansible collection?

A: Use the <product>_upgrade_only variable in your playbook and set the target version via <product>_version. Back up your system and database before upgrading. See Upgrading JFrog Platform for the Ansible Collection for the full playbook example.

❓ How do I enable SSL for Artifactory through NGINX in an Ansible installation?

A: Set artifactory_nginx_ssl_enabled: true in roles/artifactory/defaults/main.yml. Configure server_name, certificate, and certificate_key in the artifactory_nginx_ssl role. See Set SSL Certificate and Key for Nginx for the full variable list.

❓ How do I encrypt sensitive Ansible variables like database passwords?

A: Store sensitive variables in a separate file (for example, vars/secret-vars.yml) and encrypt it with ansible-vault encrypt secret-vars.yml --vault-password-file ~/.vault_pass.txt. Include the encrypted file under vars_files in your playbook. See Use Ansible Vault to Encrypt Variables for the full example.