Configuring Artifactory

Transcription

1 Configuring Artifactory 1 Configuration Files 2 Understanding Repositories 2.1 Local Repositories 2.2 Remote Repositories 2.3 Virtual Repositories 3 Common Repositories Configuration 3.1 Snapshots and Releases 3.2 Unique Snapshot Policy 3.3 Unique Snapshots Cleanup 3.4 Accept and Reject Patterns 3.5 Offline 3.6 Caching and Retrieval Timeouts of Remote Artifacts sockettimeoutmillis retrievalcacheperiodsecs failedretrievalcacheperiodsecs missedretrievalcacheperiodsecs Remote Repository Authentication 3.7 Going Through Proxy Servers 3.8 Proxying Maven 1 repositories 4 Backups 4.1 Backup Frequency 4.2 Old Backups Retention Period 4.3 Excluding Repositories 4.4 Backup Dir Configuration Files All Artifactory configuration files are located under the $ARTIFACTORY_HOME/etc folder. On Unix $ARTIFACTORY_HOME is usually a soft link to /etc/artifactory. This folder should contain the following files: File Name artifactory.config.xml log4j.properties jetty.xml Description The main Artifactory configuration file, that is loaded on Artifactory's startup. This file contains definitions for all managed repositories + other relevant data. The XML syntax is based on a well documented W3C XML Schema available here. Also, the artifactory.config.xml that is shipped with Artifactory contains a sensible default configuration and a lot of commented references. This makes configuration by example a real easy task. The standard log4j configuration file, that should be tuned on. Note that changes to this file are picked up immediately in runtime. The standard Jetty configuration file. Most common changes to this file is changing the default listen port (8080) or adding the AJP connector when running behind Apache HTTPd. Understanding Repositories Artifactory hosts two kinds of repositories: local and remote. Both local and remote repositories can be aggregated under virtual repositories, in order to create controlled domains for artifacts navigation and search, as we will see in the next sections. All repositories are defined in the artifactory.config.xml file. Local Repositories Local repositories are essentially physical repositories that are managed locally and that one can deploy artifacts into. A local repository is directly accessible via a URL pattern of Sample local repository definition (in this case, a release-only repository):

2 <localrepositories> <localrepository> <key>libs-releases</key> <description>local repository for in-house libraries</description> <handlereleases>true</handlereleases> <handlesnapshots>false</handlesnapshots> </localrepository>... </localrepositories> Remote Repositories Remote repositories serve as proxies and caches for repositories managed at remote URLs (including other Artifactory repository URLs). Artifacts are stored and updated in remote repositories according to various configuration parameters that control the caching and proxying behavior. You can remove artifacts from remote repository caches but you cannot deploy anything into a remote repository. A remote repository is directly accessible via a URL pattern of or h ttp://<host>:<port>/artifactory/<remote-repository-name>-cache/ Sample remote repository definition (in this case, proxying the Maven 2 "repo1" repository): <remoterepositories> <remoterepository> <key>repo1</key> <handlereleases>true</handlereleases> <handlesnapshots>false</handlesnapshots> <excludespattern>org/artifactory/**,org/jfrog/**</excludespattern> <url> </remoterepository>... </remoterepositories> Virtual Repositories A virtual repository (or repository group, if you prefer this term) aggregates several repositories under a common URL. The repository is virtual in the sense that you can resolve artifacts from it but you cannot deploy anything to it. By default Artifactory uses a global virtual repository that is available at This repository contains all local and remote repositories defined in your artifactory.config.xml. The search order in which artifacts are resolved in a virtual repository is always: local repositories, remote repository caches and finally remote repositories themselves. You can create new virtual repositories and aggregate local and/or remote repositories under them in order to form new artifact resolution groups. There is an example in the artifactory.config.xml that is included in the Artifactory distribution. Basically, you simply refer to already defined local and remote repositories. So, to create a new virtual repository "snapshots-only" that is available at napshots-only/ you should include something like:

3 <virtualrepository> <key>snapshots-only</key> <repositories> <repositoryref>plugins-snapshots</repositoryref> <repositoryref>codehaus-snapshots</repositoryref> <repositoryref>libs-snapshots</repositoryref> <repositoryref>third-party-snapshots</repositoryref> </repositories> </virtualrepository> Note: Search order is always as described earlier, regardless of the order in which repositories are listed inside the virtual repository. Common Repositories Configuration The following sections introduce important repositories configuration attributes. For a full list of configuration options, please see the thoroughly documented XSD for the artifactory.config.xml, here. Snapshots and Releases You can configure whether a repository handles snapshots and release artifacts by configuring the handlesnapshots and handlereleases el ements for a repository. Unique Snapshot Policy The snapshotversionbehavior provides centralized control on how snapshots may be deployed into the repository, regardless of the user specific settings. The nonunique (default) value specifies non-unique snapshots, while the unique value will cause snapshots to be deployed with unique timestamp and build number suffix. You can use the deployer value to instruct Artifactory to let the user determine the way snapshots are deployed (i.e. act as a standard, non-smart, repository). Unique Snapshots Cleanup We strongly recommend using non-unique snapshots ( why? ). However, putting aside the question of usefulness in using unique snapshots, you can tell Artifactory to automatically clean up old unique snapshots by using the maxuniquesnapshots element to specify the maximum number of unique snapshots of an artifact that should be maintained in the repository. Clean up takes effect on each new snapshot deployment. Accept and Reject Patterns It is extremely important to use accept and reject patterns, especially for remote repositories to avoid: Looking for remote artifacts on repositories that will never contain those artifacts, or that contain only a certain range of group ids. Exposing sensitive business information that can be derived from your artifact queries to whoever can intercept the queries, including the owners of the remote repository itself. For this, it is recommended to use early filtering by using the includespattern and excludespattern elements. These elements take a comma separated list list of Ant-like patterns to filter-in and filter-out artifact queries. Filtering works by subtracting the excluded patterns (default is none) from the included ones (defaults to everything). for example:

4 <includespattern>org/apache/**,com/acme/**</includespattern> <excludespattern>com/acme/exp-project/**</excludespattern> Will cause Artifactory to submit queries to the repository in question for org/apache/maven/parent/1/1.pom and com/acme/project-x/c ore/1.0/nit-1.0.jar but not for com/acme/exp-project/core/1.1/san-1.1.jar. Offline If a remote repository has become offline for a substantial amount of time, or if Artifactory is used in circumstances such that it cannot regularly connect to remote repositories to download artifacts (such as in a secured disconnected environment), it is possible to tell Artifactory that the remote repository is offline. This is done by setting the offline element value to true. In this case, only artifact already present in the cache will be used. Caching and Retrieval Timeouts of Remote Artifacts The following parameters are used by remote repositories when deciding how to handle remote artifact requests. Note that we experimented with these for quite some time in many different locations before deciding on the default values. It is therefore recommended, that unless there's a compelling reason to change the defaults (except for disabling caching), that you just leave them as they are and not override them (if you do not specify any value the defaults are taken). sockettimeoutmillis This is the timeout period that Artifactory will wait before giving up on retrieving an artifact from a remote repository. After a timeout Artifactory will cache the fact that a retrieval failure has happened for the amount of time defined in failedretrievalcacheperiodsecs. Artifactory will answer future requests for that particular artifact with NOT_FOUND (404) for a period of failedretrievalcacheperiodsecs seconds and will not attempt to retrieve it it again until that period expired. sockettimeoutmillis defaults to 5 seconds (5000 millis). retrievalcacheperiodsecs Defines how long before Artifactory checks for a newer version of a requested artifact in remote repository (either a snapshot or a redeployed release version). Artifactory will not fetch anything but the metadata if no newer version is found. The default is 12 hours (43200 seconds). You can force expiry of this cache from the UI tree view by right-clicking an artifact or a folder and selecting expire cache. failedretrievalcacheperiodsecs See the explanation for sockettimeoutmillis. The default is 30 seconds. missedretrievalcacheperiodsecs The number of seconds to cache artifact retrieval misses (artifact not found). A value of 0 means no caching. A miss is a 404 response ( NOT_FOUND) received from a remote repository that currently does not have the artifact requested. You might want to treat this differently than when failing to retrieve the artifact is due to network problems (timeouts or connection failures == retrieval failures). The default is 12 hours (43200 seconds). Remote Repository Authentication If a remote repository requires authentication you can provide a username and password as part of the repository definition. Going Through Proxy Servers It is not uncommon in a corporate environment that in order to access remote resources you need to go through an internal proxy server.

5 Artifactory supports both regular network proxies and NTLM proxies. To use a proxy you first need to create a proxy definition: <proxies> <proxy> <key>ntlm-proxy</key> <host>proxy</host> <port>8111</port> <username>aba</username> <password>ima</password> <domain>bamba</domain> </proxy> </proxies> Then use a reference to the proxy inside a remote repository definition: <remoterepository> <key>apache-m2-snapshots</key> <handlereleases>false</handlereleases> <handlesnapshots>true</handlesnapshots> <url> <proxyref>ntlm-proxy</proxyref> </remoterepository> Proxying Maven 1 repositories To proxy Maven 1 repositories, simply add the <type>maven1</type> element to a remote repository definition (the default is type is maven2, and does not need to be explicitly specified). For example, to proxy the java.net Maven 1 repo, include the following in your artifactory.config.xml: <remoterepository> <key>java.net.m1</key> <description>java.net</description> <handlereleases>true</handlereleases> <handlesnapshots>true</handlesnapshots> <type>maven1</type> <url> </remoterepository> Backups You can automatically and periodically back up the whole Artifactory data. The backup system is basically identical to a full system export (see below). The format of the backup is a timestamped zip file that resides in the target backup dir. All backup definitions are inside the backup element of the Artifactory configuration file.

6 Note: The content of the backup (when extracted) is in standard Maven format and can be loaded into any external Maven repository, so that Artifactory never locks you up. Backup Frequency Controlling the frequency of backup is by specifying a valid cron expression. For example, to back up every 12 hours use: <cronexp>0 0 /12 * *?</cronexp> Old Backups Retention Period You can have Artifactory automatically clean up old backups and free valuable disk space by defining a retention period for your backups. For example, to keep backups for up to a week max, use: <retentionperiodhours>168</retentionperiodhours> Excluding Repositories Sometimes, you may wish to exclude certain repositories from being backed up. This normally applies mainly to repository caches. but not always. For example, to exclude repo1 and codehaus' snapshots repositories from the backup, use: <excludedrepositories> <repositoryref>repo1</repositoryref> <repositoryref>codehaus-snapshots</repositoryref> </excludedrepositories> Backup Dir By default all backups are stores under the $ARTIFACTORY_HOME/backup directory. If you wish to use another directory for storing backups in change the value of the dir element.