Try JFrog
Guides
Contact SupportTry JFrog
Start typing to search…

    Install JFrog Platform via Ansible Collection [Quick Start]

    Deploy the JFrog Platform — Artifactory, Xray, and Distribution — on Linux VMs using the jfrog.platform Ansible collection.

    Choose Your Install Path

    This guide is for teams deploying on bare-metal or VM infrastructure. If you have Kubernetes (including OpenShift), use the Helm quick start instead.

    PathWhen to UseWhat It Needs
    ProductionReal workloads, team useExternal PostgreSQL, unique security keys, cloud filestore
    EvaluationFast exploration, POC, demosNothing — collection defaults work out of the box
    What You Need
    ComponentRequirement
    AnsibleV 2.13.9+
    Collection dependenciesFrom jfrog.platform collection 10.11.x+ (FQCN usage), install: community.postgresql, community.general, ansible.posix
    Host accessSSH access from control host to targets
    PrivilegesRoot or sudo on target hosts
    LicenseJFrog license (or JFrog Platform Free Trial)
    Supported Operating Systems

    The following table lists supported operating systems and versions:

    Product

    Debian

    RHEL

    Ubuntu

    Amazon Linux

    Windows Server

    Artifactory

    11.x
    12.x

    8.x
    9.x

    20.04
    22.04
    24.04

    2023

    2016
    2019
    2022

    Xray

    10.x
    11.x
    12.x

    8.x
    9.x

    20.04
    22.04
    24.04

    2023

    ❌

    Distribution

    11.x
    12.x

    8.x
    9.x

    20.04
    22.04
    24.04

    ❌

    ❌

    Platform Deployment via Ansible
    Collection Defaults Vs Production
    AreaCollection DefaultProduction
    ArtifactoryEnabledEnabled
    Xray (+ bundled RabbitMQ)EnabledEnabled
    Distribution (+ bundled Redis)Enabled (disable with distribution_enabled: false)Enable only if licensed
    NGINXEnabledEnabled
    DatabaseBundled PostgreSQL (postgres_enabled: true) with trust auth, no replicationExternal PostgreSQL — see External Database With Ansible
    Security keysInsecure placeholders for master_key/join_keyUnique keys generated with openssl rand -hex 32
    DB passwordsDefault to passwordStrong, unique passwords per product (artifactory_db_password, xray_db_password, distribution_db_password)
    FilestoreLocal file-system storageCloud object storage (S3, GCS, Azure Blob) — see Filestore Configuration
    📘

    If distribution_enabled: true

    Verify entitlement and prepare external PostgreSQL distribution DB. See External Database With Ansible.

    How Do I Install?

    Install the Collection
    ansible-galaxy collection install jfrog.platform
ansible-galaxy collection install community.postgresql community.general ansible.posix

    To find the installed collection path, run: ansible-galaxy collection list jfrog.platform

    Create Your Inventory

    The collection does not ship an inventory file — create a hosts.ini with your target hosts. The playbook expects one host group per product. For more examples, see the Ansible inventory examples on GitHub.

    Includes all products. Use with playbook-platform.yml. See the full platform inventory example.

    [postgres_servers]
postgres-1 ansible_host=x.x.x.x

[artifactory_servers]
artifactory-1 ansible_host=x.x.x.x

[xray_servers]
xray-1 ansible_host=x.x.x.x

[distribution_servers]
distribution-1 ansible_host=x.x.x.x
    📘

    Single-server evaluation

    For evaluation, all host groups can point to the same IP address. This installs every product on one machine. For production, use separate hosts per product.

    📘

    RabbitMQ

    Bundled with Xray and always runs on the same host — there is no separate host group for it.

    Deploy Platform

    What Do I Need for Production?

    Production Preparation Steps

    Complete these steps before running the playbook:

    1. Set up external database

    Create databases and users for each product on your external PostgreSQL server. 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 database host. See External Database With Ansible for full instructions.

    ⚠️

    Bundled PostgreSQL

    The bundled PostgreSQL role is for evaluation only — it ships with trust authentication open to all hosts, with no replication or backup.

    2. Set up external filestore (optional)

    Configure S3, GCS, or Azure Blob for artifact storage by overriding the artifactory_binarystore variable. See Filestore Configuration.

    3. Review variables

    Open group_vars/all/vars.yml and update at minimum:

    VariableAction
    master_key, join_keyReplace with unique values (passed via --extra-vars at runtime)
    postgres_enabledSet to false for production; use an external PostgreSQL
    artifactory_db_url, xray_db_url, distribution_db_urlPoint to your external database host
    artifactory_db_password, xray_db_password, distribution_db_passwordSet strong passwords
    distribution_enabledSet to false if you don't need Distribution

    Product versions, JVM options, NGINX settings, and binary storage are configurable through role defaults at roles/<product>/defaults/main.yml. For the quick start, the shipped defaults work as-is. See Ansible Advanced Topics for customization.

    GitHub Examples

    Ready-to-use playbooks and inventory files from the JFrog-Cloud-Installers repository:

    ExampleDescription
    playbook-platform.ymlFull platform playbook: Artifactory, Xray, and Distribution
    playbook-rt-xray.ymlArtifactory + Xray only
    playbook-rt.ymlArtifactory only
    inventory/platform/hosts.iniFull platform inventory with all product host groups
    inventory/rt-xray/hosts.iniInventory for Artifactory + Xray deployment
    inventory/rt-ha/hosts.iniMulti-node Artifactory HA inventory

    4. Generate security keys

    export MASTER_KEY=$(openssl rand -hex 32)
export JOIN_KEY=$(openssl rand -hex 32)

    Save these keys securely — they are required for upgrades and disaster recovery.

    5. Pre-install checklist

    Confirm before deploying:

    • SSH access from the control host to every target host (ssh <user>@<host> works without prompts, or use --ask-pass)
    • Root or sudo privileges on all targets
    • Firewall ports open: 8082 (Router/API), 80/443 (NGINX reverse proxy), 5432 (PostgreSQL if on a separate host)
    • External PostgreSQL is reachable from all target hosts, with databases and users pre-created
    • Unique master_key and join_key values generated (step 4 above)

    Generate unique master and join keys at runtime and configure external PostgreSQL in group_vars/all/vars.yml. Save these keys for future upgrades:

    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"

    For the full platform playbook reference, see playbook-platform.yml.

    How Do I Verify the Installation?

    Check Services Are Running

    On each target host, verify the JFrog services are active:

    sudo systemctl status artifactory
sudo systemctl status xray          # on the Xray host
sudo systemctl status distribution  # on the Distribution host, if enabled
    Check Platform Health
    curl -f http://<artifactory_host>/router/api/v1/system/health

    A healthy response returns "status": "HEALTHY" for all services. If any service shows unhealthy, retry after 2-3 minutes — some services take time to initialize.

    Access the UI

    Open http://<artifactory_host> in your browser. Log in with the default credentials (admin / password), change the password immediately, and complete the Onboarding Wizard.

    Common Errors and Fixes
    ErrorCauseFix
    ansible-galaxy fails with 'CustomHTTPSConnection' object has no attribute 'cert_file'Ansible version too old for your Python SSL libraryUpgrade ansible-core: pip install --upgrade ansible-core
    Artifactory ports not listening after installJava binding to IPv6 on hosts with dual-stack /etc/hostsAdd -Djava.net.preferIPv4Stack=true to artifactory_extra_java_opts
    Xray health check failsDatabase not reachable or wrong xray_db_urlVerify xray_db_url points to a running PostgreSQL instance and the database/user exist
    distribution_servers group not founddistribution_enabled: true but no host group in inventoryAdd a [distribution_servers] group to hosts.ini, or set distribution_enabled: false
    Health check returns unhealthy after deployServices still startingWait 2-3 minutes for all services to initialize; check service logs with journalctl -u artifactory

    For common questions about databases, licensing, upgrades, and more, see the Quick Start FAQ.

    Next Steps

    After verifying that all services are healthy:

    1. Complete the Onboarding Wizard to configure repositories and security.
    2. Set TLS on the JFrog Platform to enable HTTPS via NGINX.
    3. Connect your JPD to MyJFrog to activate license-gated features (JAS, Curation, Catalog).
    4. Review Ansible Advanced Topics for SSL/TLS, System YAML overrides, and Ansible Vault.

    Related Topics

    TopicDescription
    External Database With AnsibleUse an external PostgreSQL instead of the bundled role
    High Availability (HA) AnsibleEnable HA for Artifactory or Xray
    Ansible Advanced TopicsSSL/TLS, System YAML overrides, custom binary storage, Ansible Vault, upgrades
    Filestore ConfigurationConfigure S3, GCS, or Azure Blob for artifact storage
    Install JFrog Platform via Helm [Quick Start]Alternative installation path for Kubernetes / OpenShift
    General System RequirementsCPU, memory, and storage requirements per product

    Updated 1 day ago