ARTIFACTORY: Installation Quick Start Guide – Linux Archive
What will you get?
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';
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:
CREATE DATABASE artifactory WITH OWNER=artifactory ENCODING='UTF8';
GRANT ALL PRIVILEGES ON DATABASE artifactory TO artifactory;$JFROG_HOME/artifactory/var/bootstrap/artifactory/tomcat/lib
Make 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:
Make sure to keep your YAML spacing consistent! We recommend either 2 or 4 spaces indentation, but ensure that it is consistent throughout.
database:
type: postgresql
driver: org.postgresql.Driver
url: jdbc:postgresql://<your db url, for example: localhost:5432>/artifactory
username: artifactory
password: password
4. Enabling PostgreSQL connectivity from the Artifactory servers:
Add the following line to: <postgres_mount>/data/pg_hba.conf.
Add the following line to (if it already exists, update it)
host artifactory artifactory <artifactory_ip> md5<postgres_mount>/data/postgresql.conf
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.
listen_addresses='*'
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.xml
Below 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">
We have other configuration templates for other cloud providers as well:
<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>
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:
4. Add the DB/binarystore.xml details above
extraJavaOpts: "-Xms512m -Xmx4g"
node:
haEnabled: true
taskAffinity: any
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.sh
7. 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
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.
{
"version" : "7.25.7",
"revision" : "72507900",
"addons" : [ "ha",...
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 {
Otherwise, you may use a dedicated load balancer to handle traffic balancing.
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;
}
Then, modify the proxy_pass lines to be:proxy_pass http://localhost:8082; → proxy_pass http://artifactory;
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:
proxy_pass http://localhost:8081; → proxy_pass http://artifactory-direct;
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
2. Extract the contents of the compressed archive and go to the extracted folder.
./artifactoryctl stoptar -xvf jfrog-artifactory-<pro|oss|cpp-ce>-<version>-linux.tar.gz
3. 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|check
5. 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:
2. Customize database connections in system.yaml:
extraJavaOpts: "-Xms512m -Xmx4g"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