ARTIFACTORY: Installation Quick Start Guide – Linux Archive

Lawrence Fung
2022-03-21 07:29

What will you get?

User-added image

This is a quick start guide on how to prepare Artifactory 7 HA for a production ready environment using the Linux Archive installation. In this guide, we will be walking through setting up a Postgres external database, multiple artifactory nodes, and a NGINX reverse proxy (which can act as a load balancer as well). At minimum, a server per Artifactory node is required. Note that you will need a license per Artifactory node. We also recommend having a type of cloud bucket storage (e.g. S3) ready. A good understanding of linux based operating systems will be required to fully grasp the material throughout this guide.

Pre-requisites

One of the supported linux distributions.

Debian 8.x, 9.x 10.x
Centos 7.x, 8.x
RHEL 7.x, 8.x
Ubuntu 16.04, 18.04, 20.04

The following ports will need to be available internally: 8081, 8082, 8040, 8045, 8048, 9092, 8070, 8086, 8046, 8047, 8049, 8091, 8061, 8062. 8081 and 8082 will additionally need to be reachable externally between nodes – and your LB/reverse proxy. They do not need to be exposed to the end user. The other ports just need to be available within the VM and not consumed by another process – some of these ports are configurable via the system.yaml if it cannot be made available.

Environment details

Before installing Artifactory, refer to System Requirements for information on supported platforms, supported browsers and other requirements. We recommend using a machine that is easily scalable in case there is an increase of Artifactory usage. Generally a machine with 4-core CPU, 8GB RAM per node is enough starting out.

See for more node hardware details https://www.jfrog.com/confluence/display/JFROG/System+Requirements 

Database

The artifactory linux installation comes bundled with a derby database. It is highly recommended to use an external database. The performance of the bundled derby database can degrade as the artifact count increases. In this quickstart guide, we will cover the Postgres setup.

PostgreSQL support:

  • 9.5 (EOL)
  • 9.6 (EOL soon)
  • 10.x
  • 11.x
  • 12.x
  • 13.x

External Postgres setup:

1. Logged into the DB, run:CREATE USER artifactory WITH PASSWORD 'password';
CREATE DATABASE artifactory WITH OWNER=artifactory ENCODING='UTF8';
GRANT ALL PRIVILEGES ON DATABASE artifactory TO artifactory;2. Download the JDBC driver corresponding to your PostgreSQL version from the PostgreSQL JDBC Driver Download site and copy the downloaded jar file into the following directory:$JFROG_HOME/artifactory/var/bootstrap/artifactory/tomcat/libMake sure your driver has read permissions for all users. Note that this directory will get created on unzipping of the linux archive, or you may pre-create it.

3. Adjust the database connection details in the system.yaml configuration file (more below): shared:
database:
type: postgresql
driver: org.postgresql.Driver
url: jdbc:postgresql://<your db url, for example: localhost:5432>/artifactory
username: artifactory
password: passwordMake sure to keep your YAML spacing consistent! We recommend either 2 or 4 spaces indentation, but ensure that it is consistent throughout.

4. Enabling PostgreSQL connectivity from the Artifactory servers:
Add the following line to: <postgres_mount>/data/pg_hba.conf.
host artifactory artifactory <artifactory_ip> md5Add the following line to (if it already exists, update it)<postgres_mount>/data/postgresql.conf
listen_addresses='*'We recommend having sizable storage space for the database, even if it is only storing metadata. It should be at least 2/10 of your expected file store size. 

Artifactory supports a number of DB types, including mysql, oracle, mariaDB. You may find the links to other supported databases below in the glossary.

For more database recommendations, see https://jfrog.com/whitepaper/best-practices-for-managing-your-artifactory-database/ 

Filestore (S3)

The binary storage is configurable in the$JFROG_HOME/var/etc/artifactory/binarystore.xmlBelow is a sample configuration using an Amazon S3 bucket. Note that this file/directory will get created on unzipping of the linux archive, or you may pre-create it.

Sample S3v3 HA configuration

<config version="2">
<chain template="cluster-s3-storage-v3"/>
<provider id="s3-storage-v3" type="s3-storage-v3">
<endpoint>s3.amazonaws.com</endpoint>
<bucketName>bucketName</bucketName>
<path>pathPrefix</path>
<region>s3Region</region>
<identity>yourIdentity</identity>
<credential>yourCredentials</credential>
<usePresigning>true</usePresigning>
<signatureExpirySeconds>600</signatureExpirySeconds>
</provider>
</config>We have other configuration templates for other cloud providers as well:
https://www.jfrog.com/confluence/display/JFROG/Configuring+the+Filestore#ConfiguringtheFilestore-ConfiguringShardingforHACluster

If you want to use local disk storage instead of S3, you can use:<config version="2">
<chain template="cluster-file-system"/>
</config>

Download Location

wget https://releases.jfrog.io/artifactory/artifactory-pro/org/artifactory/pro/jfrog-artifactory-pro/[RELEASE]/jfrog-artifactory-pro-[RELEASE]-linux.tar.gz

Steps to install

1. Extract the tar file.

tar -xvf jfrog-artifactory-pro-\[RELEASE\]-linux.tar.gz

2. Create a system.yaml under:

./artifactory-pro*/var/etc/system.yaml

3. Add the following to enable HA in system.yaml:

shared:
extraJavaOpts: "-Xms512m -Xmx4g"
node:
haEnabled: true
taskAffinity: any4. Add the DB/binarystore.xml details above
5. On additional nodes, copy over $JFROG_HOME/var/etc/security/master.key from the first node to the same location. The first node will automatically generate this file on the first startup.
6. Start up the application.sudo bash ./artifactory-pro*/app/bin/artifactory.sh7. Check the console.log for the following printout of start-up success2021-09-20T18:25:44.992Z [jfrou] [INFO ] [470978b404ac5eac] [local_topology.go:270 ] [main ] -
###############################################################
### All services started successfully in 52.558 seconds ###
###############################################################
8. Once Artifactory comes up, the UI should be accessible at port 8082. Check that Artifactory is in HA mode by running the following REST API and look in the addon array for “ha”:$ curl localhost:8082/artifactory/api/system/version -u admin:password
{
"version" : "7.25.7",
"revision" : "72507900",
"addons" : [ "ha",...If it is missing, it means Artifactory did not start in HA mode. Alternatively, the Artifactory-service.log will also print out an ASCII art of “Artifactory HA” during start-up. It will print “Artifactory Pro” if it isn’t in HA mode.
9. For a new node to join a cluster, the nodes must connect to the same database and have the same Master Key. to install additional nodes repeat these steps, with the addition of also needing to copy over $JFROG_HOME/var/etc/security/master.key from the first node to the same location on the additional. The first node will automatically generate this file on first startup. If you would like to generate your own key ahead of time, you can follow the guide here to do so.

SSL

If HTTPS is required, you can setup nginx reverse proxy in front of Artifactory. A reverse proxy configuration can be generated in the Artifactory UI by going to Administration->Artifactory->HTTP Settings. This will need to be copied to your nginx config. You will need to have your own SSL certs and key and place them in the correct directory specified in the nginx config. Below is a sample configuration for reference.  

###########################################################
## this configuration was generated by JFrog Artifactory ##
###########################################################

## add ssl entries when https has been set in config
ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
ssl_certificate /etc/ssl/private/server.key;
ssl_certificate_key /etc/ssl/private/server.crt;
ssl_session_cache shared:SSL:1m;
ssl_prefer_server_ciphers on;
## server configuration
server {
listen 443 ssl;
listen 80 ;
server_name ~(?<repo>.+)\.artifactory_host artifactory_host;

if ($http_x_forwarded_proto = '') {
set $http_x_forwarded_proto $scheme;
}
## Application specific logs
## access_log /var/log/nginx/artifactory_host-access.log timing;
## error_log /var/log/nginx/artifactory_host-error.log;
rewrite ^/$ /ui/ redirect;
rewrite ^/ui$ /ui/ redirect;
rewrite ^/(v1|v2)/(.*) /artifactory/api/docker/$repo/$1/$2;
chunked_transfer_encoding on;
client_max_body_size 0;
location / {
proxy_read_timeout 2400s;
proxy_pass_header Server;
proxy_cookie_path ~*^/.* /;
proxy_buffer_size 128k;
proxy_buffers 40 128k;
proxy_busy_buffers_size 128k;
proxy_pass http://localhost:8082;
proxy_set_header X-JFrog-Override-Base-Url $http_x_forwarded_proto://$host:$server_port;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

location ~ ^/artifactory/ {
proxy_pass http://localhost:8081;
}
}
}Reverse proxies can also be configured to handle load balancing traffic between nodes. In NGINX’s case, you can add this snippet at the top: upstream artifactory {
server 10.150.0.222:8082;
server <additional node IP>:8082;
}
upstream artifactory-direct {
server 10.150.0.222:8081;
server <additional node IP>:8081;
}Otherwise, you may use a dedicated load balancer to handle traffic balancing. 
Then, modify the proxy_pass lines to be:proxy_pass http://localhost:8082; → proxy_pass http://artifactory;
proxy_pass http://localhost:8081; → proxy_pass http://artifactory-direct;Note that to support docker requests, you’ll need a reverse proxy or load balancer to handle request rewrites. Also, if you are planning on having a load balancer terminating SSL, and a reverse proxy, you’ll need the below headers to be hard coded to the details of your load balancer:

For NGINX: proxy_set_header X-JFrog-Override-Base-Url https://<LBHOST>:<LBPORT>;
proxy_set_header X-Forwarded-Port <LBPORT>
proxy_set_header X-Forwarded-Proto https

Steps to upgrade

1. Stop Artifactorycd $JFROG_HOME/app/bin
./artifactoryctl stop2. Extract the contents of the compressed archive and go to the extracted folder.tar -xvf jfrog-artifactory-<pro|oss|cpp-ce>-<version>-linux.tar.gz3. Replace the old app folder with the new one.# Export variables to simplify commands
export JFROG_HOME=<Your JFrog home directory, for example /opt/jfrog>
export JF_NEW_VERSION=<For example /opt/jfrog/artifactory-7.x>

# Remove old app
rm -rf $JFROG_HOME/app

# Copy new app
cp -r $JF_NEW_VERSION/app $JFROG_HOME

# Remove extracted new version
rm -rf $JF_NEW_VERSION4. Startup Artifactory.$JFROG_HOME/artifactory/app/bin/artifactoryctl start|stop|check5. Repeat for the other nodes.

Tuning Artifactory (Optional)

We have the following optional tuning section to optimize Artifactory for heavier loads – it is a good idea to keep these parameters in mind as your Artifactory instance takes on more load. 

1. javaOpts (heap size) in system.yaml – we recommend at least setting this one:shared:
extraJavaOpts: "-Xms512m -Xmx4g"2. Customize database connections in system.yaml: artifactory:
  database:
    maxOpenConnections: 200
   
access:
  database:
    maxOpenConnections: 200

metadata:
  database:
    maxOpenConnections: 200As a rule of thumb, we require (upto) a number of DB connections based on the following formula:
Total number of connections = (number of nodes) * ((artifactory.database.maxOpenConnections * 2) + access.database.maxOpenConnections + metadata.database.maxOpenConnections) + 50
3. Tune Tomcat threads in system.yaml:artifactory:
tomcat:
connector:
maxThreads: 400

access:
tomcat:
connector:
maxThreads: 100When modifying the Access maxThreads, it is required to update the $JFROG_HOME/artifactory/var/etc/artifactory/artifactory.system.properties file with: artifactory.access.client.max.connections = <VALUE>4. Tune Async thread pool in the same file. Note the corePoolSize should not be more than 8x the number of CPU cores: artifactory.async.corePoolSize = 32
artifactory.async.poolMaxQueueSize = 100000

To begin working with the product, you can utilize the guides below:

QuickStart Guide: JFrog Self-Hosted
QuickStart Guide: Go
QuickStart Guide: Maven and Gradle
QuickStart Guide: npm

Glossary

– System Requirements: https://www.jfrog.com/confluence/display/JFROG/System+Requirements
– External DB: https://www.jfrog.com/confluence/display/JFROG/Configuring+the+Database
– Postgresql DB: https://www.jfrog.com/confluence/display/JFROG/PostgreSQL
– Filestore: https://www.jfrog.com/confluence/display/JFROG/Configuring+the+Filestore
– HTTPS Settings: https://www.jfrog.com/confluence/display/JFROG/HTTP+Settings
– NGINX Install: https://www.nginx.com/resources/wiki/start/topics/tutorials/install/
– JFrog Download: https://jfrog.com/download-jfrog-platform/
– Linux Archive installation: https://www.jfrog.com/confluence/display/JFROG/Installing+Artifactory#InstallingArtifactory-LinuxArchiveInstallation
– Linux Archive upgrade: https://www.jfrog.com/confluence/display/JFROG/Upgrading+Artifactory#UpgradingArtifactory-LinuxArchiveUpgrade.1