Installation
Single Node Installation
The following installation installs the JFrog Platform as single product (single node) installations and not as clusters/HA.
Install the Ansible Collection from the Ansible Galaxy.
ansible-galaxy collection install jfrog.platform
Verify that you reference the Ansible Collection in your playbook when using these roles.
--- - hosts: artifactory_servers collections: - jfrog.platform roles: - artifactory
Ansible uses SSH to connect to hosts. Verify that your SSH private key is on your client and that the public keys are installed on your Ansible hosts.
Create an inventory file: Use one of the examples from the examples directory to construct an inventory file (
hosts.yml
) with the host addresses and variables.Next, create your playbook: Use one of the examples from the examples directory to construct a playbook using the JFrog Ansible roles. These roles will be applied to your inventory and provision software.
Execute the following command to provision the JFrog software with Ansible.
ansible-playbook -vv platform.yml -i hosts.ini
Generating Master and Join Keys
Generate the master and join keys. If you do not provide these keys, they will be set to the defaults in the
groupvars/all/vars.yaml file
under each role. For production deployments, you may want to generate your master and join keys and to apply them to all the nodes using the following command.MASTER_KEY_VALUE=$(openssl rand -hex 32) JOIN_KEY_VALUE=$(openssl rand -hex 32) ansible-playbook -vv platform.yml -i hosts.ini --extra-vars "master_key=$MASTER_KEY_VALUE join_key=$JOIN_KEY_VALUE"
Important
Remember to save the generated master and join keys for future upgrades.
Overriding the system.yaml in Ansible Installations
By default, the flag <product>_systemyaml_override
is set to false, which means that any changes you do to override/edit the existing yaml will not be applied.
By setting this flag to true, e.g., artifactory_systemyaml_override
: true, you can then override the existing configurations for the product, in this case Artifactory.
Using Ansible Vault to Encrypt Vars
Some vars you may want to keep secret. You may put these vars into a separate file and encrypt them using the Ansible Vault.
Use the following command.
ansible-vault encrypt secret-vars.yml --vault-password-file ~/.vault_pass.txt
Then in your playbook include the secret vars file.
- hosts: artifactory_servers vars_files: - ./vars/secret-vars.yml - ./vars/vars.yml roles: - artifactory
Using an External Database
If you want to use an external database for one or more products:
- Set the value of the
postgres_enabled
field to false (which means that you are not going to use the Postgres role that is bundled with the collection) ingroup_vars/all/vars.yml
. Follow the steps below to create an external database and then change the corresponding product values in
group_vars/all/vars.yml
.
The following example shows a sample configuration for the Artifactory database connection details.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_pasword> artifactory_db_url: jdbc:postgresql://<external_db_host>:5432/{{ artifactory_db_name }}
You can also modify other JFrog products database configuration to set up an external PostgreSQL database in the same file.
Supported PostgreSQL Versions Artifactory supports PostgreSQL version 13.x and below (9.5 and 9.6 were EOL in 2021). Use the commands below to create an Artifactory user and database with appropriate permissions. Modify the relevant values to match your specific environment: Once you have verified that the script is correct, you need to run it to create the database and proceed with configuring the database. Artifactory Privileges We recommend providing Artifactory with full privileges on the database. When you configure Artifactory to use PostgreSQL, all the artifact information is stored in PostgreSQL while the artifact binary data is stored in the file system (under While it is possible to store BLOBs inside PostgreSQL we do not recommend it. This is important because the PostgreSQL driver does not support streaming BLOBs with unknown length to the database. Therefore, Artifactory temporarily saves deployed files to the filesystem and only then saves the BLOB to the database. Edit the database connection details in the system.yaml configuration file as follows. Available from Artifactory 7.31.10. Edit the Because Artifactory uses multiple drivers and you need to configure the connection strings for these separately. The The The following sample shows an example To enable Transport Layer Security (TLS) encryption for PostgreSQL, set the For example, in the $JFROG_HOME/artifactory/var/etc/system.yaml file: If you are using old certificates or have an AWS RDS instance that was created before July 2020, you will not have Subject Alternative Name (SAN) enabled. To resolve this issue, you will need to generate a new certificate with SAN.Creating the PostgreSQL Database
CREATE USER artifactory WITH PASSWORD 'password';
CREATE DATABASE artifactory WITH OWNER=artifactory ENCODING='UTF8';
GRANT ALL PRIVILEGES ON DATABASE artifactory TO artifactory;
Configuring Artifactory to Use PostgreSQL
$JFROG_HOME/artifactory/var/data/artifactory/filestore
).Configuring Artifactory to Use PostgreSQL Single Node
shared:
database:
type: postgresql
driver: org.postgresql.Driver
url: jdbc:postgresql://<your db url, for example: localhost:5432>/artifactory
username: artifactory
password: password
Configuring Artifactory HA to Use PostgreSQL Database in HA
system.yaml
file to update the following values.url
field under the shared
database section in the following format.jdbc:postgresql://<PostgreSQL Database 1 URL>,..., <PostgreSQL Database N URL>/artifactory?targetServerType=primary
url
field under the metadata
database section in the following format.jdbc:postgresql://<PostgreSQL Database 1 URL>,..., <PostgreSQL Database N URL>/artifactory?target_session_attrs=read-write"
system.yaml
file configuration.systemYaml:
shared:
logging:
...
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"
artifactory:
Database:
...
frontend:
...
access:
...
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"
...
Enabling TLS Encryption
sslmode
property to verify-full
in the
JDBC connector URL.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
...
High Availability (HA) Installation
By default, the Ansible Platform Collection is installed in a single node configuration. Currently, HA is supported for Artifactory and not the other products.
To enable HA for Artifactory, set the following as true in roles/artifactory/defaults/main.yml
inside the Ansible Platform Collection.
artifactory_ha_enabled: true
You can also enable HA by setting extra-vars by running the following command if you are doing a fresh installation.
ansible-playbook -vv platform.yml -i hosts.ini --extra-vars "artifactory_ha_enabled=true"
You can enable HA for an existing single node installation by running the following command.
ansible-playbook -vv platform.yml -i hosts.ini --extra-vars "artifactory_ha_enabled=true artifactory_systemyaml_override=true"
By default, Ansible tries to manage all of the machines referenced in a play in parallel and starts all Artifactory nodes in parallel, which is not supported and causes the installation to fail. To avoid such a scenario, add the following serial mode logic in your playbook when you install or upgrade Artifactory in HA mode.
- hosts: artifactory_servers serial: - 1 - 100% roles: - role: artifactory when: artifactory_enabled | bool
By default, all nodes are installed as primary nodes, which means that all nodes in the high availability cluster can perform tasks such as replication, garbage collection, backups, exporting, and importing. Every node in the cluster can serve any of the mentioned tasks and if any node goes down, the different nodes in the cluster will be able to perform these tasks instead. By default, when adding a new node (member) to the cluster, it will be able to perform cluster-wide tasks without user intervention.
The "taskAffinity": "any"
attribute is set by default, on all the nodes in the cluster, when installing an Artifactory version 7.17.4 and above and is configured under the Nodes
section in the Artifactory Configuration YAML. To remove this functionality from a node, set "taskAffinity": "none"
. For more information, see Cloud-Native High Availability.
Building the Collection Archive
Update the
galaxy.yml
meta file as needed. Update the version.Build the archive (this requires Ansible 2.9+).
ansible-galaxy collection build
Set SSL Certificate and Key for Nginx
Set artifactory_nginx_ssl_enabled as true
in roles/artifactory/defaults/main.yml
inside the Ansible Platform Collection. This enables Artifactory to use the artifactory_nginx_ssl
role.
Configure the following role variables in the artifactory_nginx_ssl
role.
server_name
: The server name. For example,artifactory.54.105.51.178.xip.io
.certificate
: The SSL certificatecertificate_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 to the Nginx configuration for the use of docker subdomains.