Enterprise Plus Startup Guide

Patrick Russell
2020-02-10 19:50

System Requirements

There are separate requirements for each product. You will need to install each one on its own dedicated host, which for Enterprise Plus is three services at minimum. 

Usually, there is an existing Artifactory installation to start with. This guide assumes that this is an empty environment. To install Mission Control, you need to set up an Artifactory installation as an Authentication Provider first.

To take full advantage of Enterprise Plus, there should be further installations and setups for the other Artifactory instances and Edge nodes. This allows users to take advantage of the advanced global Binary Distribution System at the heart of an Enterprise Plus setup. 

Installing other Artifactory or Edge instances will follow the same guidelines as the first Artifactory installation.

Artifactory

JFrog Artifactory is Binary Repository Manager, meaning it can handle many file deployments from build servers such as Jenkins. Artifactory uses three microservices in the latest release:

Artifactory (Binary Repository Manager)
Access (Authentication Manager)
Replicator (Local Distribution Manager)

Artifactory is hosted on an Apache Tomcat server, which requires a Java JDK installation. The JDK version depends on the version of Artifactory, the latest release (6.15) supports both JDK 8 and JDK 11.

Since Artifactory is a Java application, most mainstream operating systems that can run a JVM can run Artifactory. Suggested operating systems are Linux-based Ubuntu, Debian, RedHat, and CentOS.

At minimum, Artifactory requires these resources:

– 4 CPU cores
– 8 GB RAM (2 GB for the JVM)
– A large local disk to store binaries

These will meet the bare minimum requirements. Larger scale usage requires more CPU and RAM resources to be available. For Production Artifactory installations, please have a look at the Artifactory Wiki to determine how large the instance needs to be

Mission Control

Mission Control is used as a central "hub" to remotely manage multiple Artifactory, Distribution, and Edge installations. It is required to use Enterprise Plus features, both for license activation as well as managing Distribution servers.

It has multiple microservices, which are required to take advantage of all the Enterprise Plus features:

– Mission Control's services:
  – Server (Web UI, main service)
  – Insight (Graphs, analytics)
  – Scheduler (Scheduling tasks)
  – Executor (Executing REST API actions)
– ElasticSearch (For Insight analytics)

– PostgreSQL database

The Mission Control microservices require the Java JDK. The latest release (3.5) supports both JDK 8 and JDK 11. Mission Control also requires these minimum hardware specifications:

– 6 CPU cores
– 8 GB RAM
– At least 100 GB storage

Mission Control supports 4 Operating Systems, and is also available as a Docker installation:

– Debian 8.x            – Red Hat 7.x
– CentOS 7.x            – Ubuntu 16.x

Distribution

JFrog Distribution is used to distribute Release Bundles from a Source Artifactory to a Target Artifactory or Edge node.

Distribution needs information from Mission Control to distribute Release Bundles. It has these microservices running in the background:

– Distribution microservices:
Distribution (Web UI, main service)
Distributor (Distributes binaries)
– Redis datastore message broker

– PostgreSQL database

Distribution requires these minimum hardware requirements:

– 8 CPU cores
– 8 GB RAM
– At least  50 GB storage

5 Linux operating systems are supported, Distribution is also available as a Docker installation:
– Centos 7.x        – Debian 8.x
– Red Hat 6.x         – Red Hat 7.x 
– Ubuntu 16.04 

Installing the services

Installing JFrog software has never been easier. Each service comes either in a single-package form (Artifactory) or with an installer script that takes care of the more complex steps automatically (Distribution, Mission Control).

For Distribution and JFMC, there are text prompts that will ask if you wish to use external databases or file paths. For this Quick Start Guide, we'll be using the defaults the installer provides.

Artifactory

Artifactory has many different supported installation types. The easiest way to get started is with the RPM or Debian package installations.

To install Artifactory with a package manager like yum or apt-get, you can follow the steps on the Download Artifactory Pro page. You could otherwise download and unzip the Zip Installation, it should start after the JDK has been installed. 

[Example RPM installation]
wget https://bintray.com/jfrog/artifactory-pro-rpms/rpm -O bintray-jfrog-artifactory-pro-rpms.repo;

sudo mv bintray-jfrog-artifactory-pro-rpms.repo /etc/yum.repos.d/;

yum install jfrog-artifactory-pro

These initial setups come bundled with a Derby Database. This is good for smaller installations, but keep in mind Artifactory works better with an external database at larger scales.
 

Mission Control

Mission Control supports multiple installation types, including Docker, RPM, and Debian installers

There are more complex installation types, such as Kubernetes, docker-compose, and a Zip Installation. These installation types require more steps to complete. Take a look at the linked wiki pages to get started using these installation types.

The Docker, RPM, and Debian installation types follow the same general flow:

1. Download the installer bundle
    For RPM and Debian installers, this includes the full binary files used to install. 
    Docker installations download an SH script to run multiple "docker pull" commands.

2. Run the SH Script – It handles the installation and configuration of the microservices

[Example RPM installer]
cd jfmc-rpm-<version>
./installJFMC-rpm.sh

That's it, Mission Control should have been installed successfully. 

Distribution

Distribution has a similar process to Mission Control for the three mainstream installation types (RPM, DPKG, Docker). For these installations, you should follow this process:

1. Download the Distribution installation bundle  

2. Run the SH script 

./installDistribution-<linux-flavor>.sh

That's it, Distribution should now be installed and ready to work.

Set up Mission Control 

Connecting to Artifactory

Mission Control needs a bi-directional connection to an Artifactory installation.

Starting in Mission Control 3.0, an Artifactory installation is required to complete the installation. This allows Artifactory to handle user and group creation using its existing, secure authentication system.

First, specify the Mission Control Base URL. This endpoint needs to be reachable from the Artifactory host (Use the default site for now):

You can skip the License Bucket screen for now. License Bucket installation is handled in a later section.

To connect to other E+ services, the Artifactory host needs to be connected to Mission Control's host. You can test this by running this curl command from the Mission Control host:

#Ping the Artifactory instance – Run from Mission Control
curl -vvv http://<Artifactory_URL>:8081/artifactory/api/system/ping

Expected response:
OK

You might also need to test the Mission Control URL from Artifactory:

#Ping Mission Control – Run from Artifactory
curl -vv http://<JFMC_URL>:8080/api/v3/ping
Expected response:
true

Back in the Mission Control menu, use the working URL in the Authentication Provider menu. Keep in mind the "Service Name" for Artifactory cannot be easily changed later.

Load the Enterprise Plus License Bucket

To use the Enterprise Plus features, you need to load an Enterprise Plus license bucket. There are two ways to do this in the latest release of Mission Control. One way is to download the License Bucket file, and the other is to supply the download URL to Mission Control. Both require the Enterprise Plus Bucket Key.

This can be done during the on-boarding wizard or after connecting to an already-licensed Artifactory.

The "Signed URL" contains a download link to a binary file. Users that run Mission Control without an internet connection can manually download the file and upload it to Mission Control instead.

In either case, once the key has been supplied as well, the bucket should activate successfully.

Apply the E+ license to Artifactory

The easiest way to do this is through the Services UI in Mission Control. Go to Services -> Artifactory -> Edit. 

Re-validate the Admin credentials by clicking "Verify Connection," and a new dropdown menu will appear:

Artifactory will receive the new license with no restarts or downtime required.

Set up Distribution

After getting Mission Control online, it's time to configure the Distribution server installed earlier. Starting Distribution and navigating to its web UI page yields a helpful tip as to what to do next:

Connect to Mission Control

Connecting to Mission Control involves setting up a new Service in the JFMC UI. This is done in the main "Services" menu by clicking the "Add service" button in the corner of the main menu. 

After activating an E+ bucket, new options are available in the Add Service dropdown menu:

Add the Distribution URL, name, and site. The "Add" button should activate and allow you to save the configuration. This performs a networking test between Mission Control and Distribution, and will report success when the test succeeds.

Once this is done, Mission Control sends information about its Authentication Provider to Distribution. Login attempts in Distribution use this same Authentication Provider.

The Distribution UI should unlock, but it's not quite ready to work yet.

Set up GPG keys

Distribution servers need a set of GPG keys to encrypt and sign release bundles. The public key also needs to be shared with each Artifactory installation so the bundle can be verified.

To generate a GPG key pair, you can follow the steps on the Distribution Wiki. These can be done on the Distribution host or in a Linux environment:

# Generate the keys
# Select RSA
# Select the size of the key – Use 2048 for the default
# Chose "no expiration" unless you want to cycle these keys

gpg –full-generate-key

# Export the private key with the specified id to a file
gpg –output distribution.private.key –armor –export-secret-keys {key-id}
  
# Export the public key with the specified id to a file
gpg –output distribution.public.crt –armor –export {key-id}

At the end of the process there should be a pair of GPG signing keys exported as two separate text files. Keep these key files in a secure place, if they are lost they cannot be easily recovered from the Distribution or Artifactory servers.

Deploy GPG keys to Distribution

To upload the GPG signing keys, they need to be combined into a single JSON payload, then uploaded via the REST API to Distribution:

[keys.json]
{
  "public_key":  "—–BEGIN GPG PUBLIC KEY BLOCK—–
                  —–END GPG PUBLIC KEY BLOCK—–",
  "private_key": "—–BEGIN GPG PRIVATE KEY BLOCK—–
                  —–END GPG PRIVATE KEY BLOCK—–"
}

curl -u <Artifactory-admin> -X PUT -H "Content-Type: application/json" -T keys.json http://distribution.com:8080/api/v1/keys/pgp

Distribution will add these keys to its bundled Postgres database. They are stored in the database in an encrypted format. You should remove the "keys.json" file after this is done, as it contains the GPG Private Key.

Deploy public GPG key to the Artifactory services

Artifactory only needs the public GPG key to verify Release Bundles. Thus a different JSON payload is needed for Artifactory:

[ public-gpg.json ]
{
 "alias" : "distribution key name 1.0.0",
 "public_key" : "—–BEGIN PGP PUBLIC KEY BLOCK—–
—–END PGP PUBLIC KEY BLOCK—–"
}

 
curl -u <Artifactory-admin> -XPOST -H"Content-type: application/json" -T public-gpg.json http://artifactory.com:8081/artifactory/api/security/keys/trusted

This needs to be done for each Artifactory or Edge instance in the E+ network.

Distribute a bundle!

Once all the signing keys have been set up, it's time to distribute a release bundle! This can be done in many ways, the easiest is to specify distributing every file in a small repository.

From the Distribution UI, click on the "Add a Release Bundle" button:

An easy test is to choose a small repository and apply a wildcard filename (*.tar.gz) in the Include Artifact Patterns field. This should find all files of that particular type and add them to the bundle:

When you're happy with the files to distribute, choose "Next" to complete the query setup. Then click "Create & Sign" to create the first bundle.

You'll see a new window displaying the artifacts to distribute. From this menu, you can distribute the bundle to any Artifactory instances connected to Mission Control. 

Clicking "Distribute" causes the Source Artifactory (Where the files were gathered into the Release Bundle) to push all artifacts to the chosen Target Artifactory instances:

Next Steps

After  following this guide, there is now a Distribution and Artifactory network set up to push Release Bundles around the world.

Some next steps may involve configuring Access Federation so the same credentials work across the network, connecting any Jenkins CI servers to Mission Control to track builds, or turning on Direct Cloud Storage Downloads in Artifactory.

The sky is the limit with an Enterprise Plus Distribution Network!