Self-Managed Pro / Pro X Start Guide

Patrick Russell
2023-02-12 09:09

Thank you for taking an interest in JFrog! This guide will cover setting up a self-managed Artifactory and Xray with all the steps in one place. In the end, there are some interesting videos on how to set up package managers for the application and some examples of where to look next.

This is the outline of what's covered:

1. Install Artifactory
2. Install Xray
3. Configure the Application and set up Docker Repositories
4. Additional Video Resources

1. Install Artifactory

Artifactory Installation Requirements:

  • A Red Hat, Centos, Ubuntu, or Debian host machine
  • Hardware recommended for a single Pro installation:
  • 8-core CPU, 32 GB RAM, 2 TB disk for the filestore
  • A Postgresql database (Optional, but recommended)
  • Root access to the host

Installing the JFrog applications is straightforward, especially if the packaged installers are used. 

First, download either the Debian DPKG or Red Hat RPM files from the JFrog Platform Downloads page. These packages can install themselves with a single command (Wiki Source):# Debian / Ubuntu
dpkg -i jfrog-artifactory-<pro|oss|cpp-ce>-<version>.deb
# Red Hat / Centos
yum install -y jfrog-artifactory-<pro|oss|cpp-ce>-<version>.rpm
Install and set up a Postgres database as well, it scales better than the bundled Derby database even if it is installed on the same host. Exact installation and setup instructions will differ, please refer to the Postgres documentation for details on installing the database. 

You can create the database schema using these SQL commands:CREATE USER artifactory WITH PASSWORD 'password';
CREATE DATABASE artifactory WITH OWNER=artifactory ENCODING='UTF8';
GRANT ALL PRIVILEGES ON DATABASE artifactory TO artifactory;
Next, go to the newly installed Artifactory Home folder and modify the system.yaml:cd /var/opt/jfrog/artifactory/
vim etc/system.yaml
You should adjust these settings to set up a medium-scale Artifactory; feel free to copy/paste the text into the system.yaml:shared:
    database:
        type: postgresql
        driver: org.postgresql.Driver
        url: "jdbc:postgresql://<Database URL - Or localhost>:5432/artifactory"
        username: artifactory
        password: <password>
     extraJavaOpts: "-Xms512m -Xmx16g"
artifactory:
    database:
        maxOpenConnections: 300 #Default: 100
    tomcat:
        connector:
            maxThreads: 600 #Default: 200
access:
    database:
        maxOpenConnections: 300 #Default: 100
    tomcat:
        connector:
            maxThreads: 150 #Default: 50
metadata:
    database:
        maxOpenConnections: 300 #Default: 100
When you boot up Artifactory, it will connect to the Postgres database and create the tables and indexes for you. You should be able to access the application UI on port 8082.

In the UI, log in using "admin" and "password". You'll need to set up the license key and change the default Admin's password on the welcome screen.

2. Install Xray

Xray Requirements (Single node):

  • A Red Hat, Centos, Ubuntu, or Debian host machine
  • Hardware requirements:
  • 6-core CPU, 24 GB RAM, 500 GB disk space using an SSD
  • Root access to the host
  • Networking access to the Artifactory host machine

Installing Xray will also install a bundled Postgres database, for small to medium scale deployments this is recommended. You can download the Xray installer bundle from the JFrog Platform Downloads page.

Xray needs to connect with Artifactory, and to do so securely you need to retrieve a Join Key from the Artifactory UI. It can be found under Admin -> User Management -> Settings -> Connection Details:

User-added image

The installer script will ask for this key and the Artifactory URL, it's a good idea to note the key down now. Another thing to keep in mind is the network on these host machines may be internal, so you might need to use the Artifactory host's internal IP rather than the public JFrog URL seen in this menu.

You can refer to the steps on the JFrog Wiki for the commands to set up Xray. It's recommended for this guide to install the Postgres on the same host as Xray for ease of maintenance; you can also set up an external Postgres as well if that's preferred.

When you boot up Xray for the first time, there should be a welcome popup and a new set of Xray security buttons in the Platform UI. 
 

3. Configure the Application for Docker 

Add Repositories and Artifacts

This step will walk you through creating a Docker repository type and uploading your container images, allowing you to use Artifactory as your Docker Registry. You can then follow the instructions to create other types of repositories for additional binaries out of the supported technologies such as npm, Maven, Go, and others.

1. Navigate to the Administration Module. Expand the Repositories menu and click on the Repositories menu item.
User-added image
2. Create 3 new Docker package type repositories:
a.  Add a new Local Repository with the Repository Key “docker-quickstart-local” and keep the rest of the default settings.
b.  Click on the Remote tab and add a new Remote Repository with the Repository Key “docker-quickstart-remote” and keep the rest of the default settings.
c.  Click on the Virtual tab and add a new Virtual Repository with the Repository Key “docker-quickstart”.
  • Add the local and remote Docker repositories you just created. 
  • Select your local repository as the Default Deployment Repository and keep the rest of the default settings.
3. Configure the Artifactory Docker settings to use the repository path method. This will access your Docker repository directly without a reverse proxy.
a.  Navigate to the Administration Module. Click on the Artifactory menu and the General > HTTP Settings menu item.
b.  In the Docker Settings panel, select Repository Path as the Docker Access Method.
c.  In the Reverse Proxy Settings panel select Embedded Tomcat as the Server Provider (which indicates you're not using a reverse proxy).
d.  By default, Docker will only send basic HTTP authentication when working against an HTTPS host. Since we are using the repository path method, we’ll use HTTP and need to use insecure registry configuration for our Docker registry.
  • For example, in Linux systems create and add the following daemon.json file under /etc/docker

{
  "insecure-registries" : ["<My_artifactory_IP:Artifactory_Port"]
}

4. Fork the JFrog Project Examples GitHub repository. Here you will find the JFrog QuickStart example GitHub repository, containing a simple Dockerfile that you will use to build your custom image.
5. Update the base image reference.
a.  Clone your forked repository and update the FROM line of the Dockerfile to reference your virtual Docker repository.
FROM ${Artifactory_URL:Artifactory_PORT}/${VIRTUAL_REPO_NAME}/ubuntu:16.04
b.  The SERVER_NAME is the first part of the URL given to you for your environment. For example: Artifactory_IP:Artifactory_Port 
The VIRTUAL_REPO_NAME is the name “docker-quickstart” that you assigned to your virtual repository in the steps above.
6. Using the following commands, log in to your virtual repository “docker-quickstart”, build, tag and push your custom image to your Docker repository:
$ docker login ${SERVER_NAME}
$ docker build --tag ${SERVER_NAME}/${VIRTUAL_REPO_NAME}/my-docker-image:latest .
$ docker push ${SERVER_NAME}/${VIRTUAL_REPO_NAME}/my-docker-image:latest
7. Run these commands from the cloned directory containing the Docker file.
8. Navigate to the Application Module, in the Platform UI, expand the Artifactory menu and click the Artifacts menu item. Here you’ll be able to see the details of your new artifacts.
User-added image

 

Scan for OSS Security Vulnerabilities and Compliance

*Available with a JFrog ProX subscription
This step will walk you through defining a Policy, assigning it to a Watch, selecting a repository to monitor, and running your scan.

  1. Navigate to the Administration Module. Click on the Xray Security & Compliance menu and the Indexed Resources menu item.
  2. Add your “docker-quickstart-local”, “docker-quickstart-remote” repositories to your indexed resources by clicking Add a Repository.
  3. Keep in mind for your future work that indexing all repositories is resource intensive. It is recommended to select only the repositories you need to scan according to your organization needs.
  4. Define a security policy that you will later enforce in a watch.
a.  Navigate to the Application module, expand the Security & Compliance menu and click the Policies menu item.
User-added image
b.  Create a new policy called “docker-security”, of type Security, with a rule called “docker-all-severities” set with All-Severities.
5. Define a watch that includes your new security policy. A watch provides context to a policy by assigning it to resources such as repositories.
a.  Navigate to the Application module, expand the Security & Compliance menu and click the Watches menu item.
b.  Create a new watch called “sample-watch”, with your 2 repositories (“docker-quickstart-local” and “docker-quickstart-remote”) and your “docker-security” policy assigned to it by clicking Manage Policies.

Watches, Policies & Rules

c.  Policies allow us to define security and license compliance behaviors specific to your organization. Once they are defined, they are enforced by applying them to Watches. Rules define the behaviors that we want to enforce.
6. Run your scan by hovering over your watch and clicking on Apply on Existing Content to manually trigger it.

 

7. The Xray scan may take some time to complete and show the vulnerabilities results. You can return to this step later to see your vulnerabilities.
8. View any discovered vulnerabilities by clicking on your watch.

Set up Users, Groups and Permissions

This step will walk you through managing role-based access control (RBAC) for your resources, such as repositories by defining users, groups, roles and permissions. This will allow you, as an administrator of the JFrog Platform, to set up access for different teams in your organization.

1. Create a new user.
a.  Navigate to the Administration Module. Click on the Identity & Access menu and the Users menu item.
b.  Create a new user with the User Name “frog”. Set the Email Address and Password. 
2. Create a group and assign your user to this group.
a.  Navigate to the Administration Module. Click on the Identity & Access menu and the Groups menu item.
b.  Create a new group called “dev-team1”. Set the Group Name and assign your newly created “frog” user to it.
3. Define permission targets that match specific resources to your users and groups. This step will enable access for all the users in your “dev-team1” group to deploy and cache artifacts in the “docker-quickstart-local” and “docker-quickstart-remote” repositories.
a.  Navigate to the Administration Module. Click on the Identity & Access menu and the Permissions menu item.
b.  Create a new permission called “dev-team1-permissions”.
  • Add your “docker-quickstart-local”, “docker-quickstart-remote” repositories to your resources by clicking Add Repositories.
  • Click on the Groups tab, select your newly created “dev-team1” group, and select the Deploy/Cache permission. This also will provide your group with Read and Annotation permissions.

Use a meaningful name for the permission target that will easily help you manage and detect the required permission. For example, RnD_India, Project A, DevOps_US..
 

4. Additional Video Resources

Congratulations! You’re all set and ready to continue exploring the JFrog Platform.

You may be interested in these videos, they cover how to set up the most popular package managers and other important topics:

Package Managers:

How to Set Up an NPM Repository in Artifactory

https://www.youtube.com/watch?v=PYGbN_OcKX8

How to configure Nuget repositories?

https://www.youtube.com/watch?v=fZHRGp44d5A

How to configure a remote V3 NuGet repository in Artifactory?

https://www.youtube.com/watch?v=YiUb_6xmHNE

How to set RPM repositories in JFrog Artifactory?

https://www.youtube.com/watch?v=nJp2kzxHXJA

Jenkins Artifactory Plugin Setup and Demo

https://www.youtube.com/watch?v=kBIsK01bDu0

How to run a build using JFrog CLI with Maven integration?

https://www.youtube.com/watch?v=yFBjopDjhQ0

How to start With Artifactory and Gradle?

https://www.youtube.com/watch?v=g8u7c7hUqKU

How to Configure Conda Repositories?

https://www.youtube.com/watch?v=MJ_e7pbnUIU

How to use docker commands when subdomain method is configured in Artifactory?

https://www.youtube.com/watch?v=Q7EhUau2-Vk

How to setup GitLFS repository in Artifactory?

https://www.youtube.com/watch?v=8z9EWfXrm30

 

Application Details:

How to troubleshoot a startup problem

https://www.youtube.com/watch?v=2u4nGxuCaQU

How to collect and publish Build Info

https://www.youtube.com/watch?v=Y68zibzsgdk

How to upload generic builds using the JFrog CLI

https://www.youtube.com/watch?v=n9nAl4ofUfs

Licenses and Bucket Licenses Explained

https://www.youtube.com/watch?v=1K9P-tVQOCE

 

Documentation Resources