diff --git a/content/apt/guides/mini/guide-large-scale-centralized-deployments.apt b/content/apt/guides/mini/guide-large-scale-centralized-deployments.apt new file mode 100644 index 0000000000..6d82915c98 --- /dev/null +++ b/content/apt/guides/mini/guide-large-scale-centralized-deployments.apt @@ -0,0 +1,243 @@ + ------ + Guide to Large Scale Centralized Deployments + ------ + Phil Clay + ------ + 2021-01-01 + ------ + +~~ Licensed to the Apache Software Foundation (ASF) under one +~~ or more contributor license agreements. See the NOTICE file +~~ distributed with this work for additional information +~~ regarding copyright ownership. The ASF licenses this file +~~ to you under the Apache License, Version 2.0 (the +~~ "License"); you may not use this file except in compliance +~~ with the License. You may obtain a copy of the License at +~~ +~~ http://www.apache.org/licenses/LICENSE-2.0 +~~ +~~ Unless required by applicable law or agreed to in writing, +~~ software distributed under the License is distributed on an +~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +~~ KIND, either express or implied. See the License for the +~~ specific language governing permissions and limitations +~~ under the License. + +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/doxia/references/apt-format.html + +Guide to Large Scale Centralized Deployments + + This guide covers a simple optimized approach to using a + {{{../../repository-management.html}repository manager}} + in a large organization with hundreds/thousands of Maven projects. + + The pillars of this approach are: + + [[1]] Use a centralized {{{../../repository-management.html}repository manager}}. + + * Maven clients should download needed artifacts from the repository manager. + + * Maven clients should upload proprietary artifacts to the repository manager. + + [[2]] Configure the location to download/upload artifacts in Maven <<>> files, + rather than in <<>> files. + + [[3]] Centrally manage the <<>> files, and distribute them via automation. + + +* {Repository Manager Layout} + + Repository managers generally have at least three types of repositories: + + [hosted] contains artifacts uploaded to the repository manager + + [proxy] proxies a remote repository and caches artifacts + + [virtual] aggregates several repositories into one + + + The simplest way to organize repositories within a repository manager is + to have a single virtual repository that aggregates: + + * a proxy repository for each public repository to mirror. (For example: Maven Central) + + * a hosted repository for releases + + * a hosted repository for snapshots + + * a hosted repository that can contain both releases and snapshots + (Only needed if some projects are still using Maven Deploy Plugin \< 2.8. + See {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}} for more info.) + + Separate hosted repositories are generally used for releases and snapshots + due to the need for different artifact retention policies. + + The following sections describe how to configure Maven clients to: + + * {{{Managing_Downloads_from_the_Repository_Manager}Download}} artifacts from the virtual repository. + + * {{{Managing_Uploads_to_the_Repository_Manager}Upload}} artifacts to one of the hosted repositories. + +* {Managing Downloads from the Repository Manager} + + All artifacts used by Maven projects in the organization should be downloaded + from the single virtual repository of the repository manager. + + Maven can be instructed to download artifacts from the repository manager's virtual repository + by defining a mirror in the Maven <<>> file as described in the + {{{./guide-mirror-settings.html}Guide to Mirror Settings}}. + + Example: To download artifacts from the corporate repository manager's <<>> repository: + ++-----+ + + ... + + + + corp-repository-manager + Corporate Repository Manager + external:* + https://corp-repository-manager-host/maven-virtual + + + ... + ++-----+ + +* {Managing Uploads to the Repository Manager} + + All proprietary artifacts produced by Maven projects in the organization should be uploaded + to the repository manager's hosted repositories. + + The {{{../../plugins/maven-deploy-plugin}Maven Deploy Plugin}} can be instructed to upload artifacts + to the repository manager's repositories by defining the <<>> properties + in the Maven <<>> file. + When these properties are defined, the Maven Deploy Plugin's {{{../../plugins/maven-deploy-plugin/deploy-mojo.html}deploy}} + goal uses them instead of the <<<\>>> section of <<>> files + to determine where to upload artifacts. + + Defining the upload destination of artifacts in <<>> files rather than + in the <<<\>>> section of <<>> files allows the destinations + to be centrally managed, which simplifies maintenance if the destinations need to change. + In other words, rather than changing a huge number of <<>> files, + you just need to change {{{Settings_File_Locations}relatively few}} + <<>> files if/when the distribution locations need to change. + + The ability to specify separate alternate deployment repositories for releases and snapshots + via the <<>> and <<>> properties, + respectively, was added in Maven Deploy Plugin 2.8. + To get the most out of the approach defined in this document, all projects should use Maven Deploy Plugin \>=2.8. + If some projects are still using an older version of Maven Deploy Plugin (\>=2.3 and \<2.8), then + specify a single alternate deployment repository via the <<>> property + that points to a repository capable of containing both releases and snapshots. + + Typically, only continuous integration servers are allowed to upload artifacts to the repository manager. + Therefore, these settings should only be specified in <<>> files on continuous integration servers, + and should not be in <<>> files on developer machines. + Alternatively, if you want developers to be able to upload artifacts to the repository manager, + then include these properties in the <<>> files used by developers. + + Example: To upload artifacts to one of the corporate repository manager's hosted repositories: + ++-----+ + + ... + + + + corp-repository-manager + + + + corp::default::https://corp-repository-manager-host/maven-snapshots + + + corp::default::https://corp-repository-manager-host/maven-releases + + + corp::default::https://corp-repository-manager-host/maven-combined + + + + + corp + + https://ignored + + true + never + + + true + always + + + + + + + corp + + https://ignored + + true + never + + + true + always + + + + + + + + corp-repository-manager + + ... + ++-----+ + + +* {Settings File Locations} + + Maven <<>> files need to be available wherever Maven builds are performed, typically: + + * on continuous integration servers, and + + * on developer machines + + Both locations should have the mirror settings mentioned in + {{{Managing_Downloads_from_the_Repository_Manager}Managing Downloads from the Repository Manager}}. + + Typically, only continuous integration servers should have the deployment repository settings + mentioned in {{{Managing_Uploads_to_the_Repository_Manager}Managing Uploads to the Repository Manager}}, + because only continuous integration servers should be allowed to upload to the repository manager. + Alternatively, if you want developers to be able to upload artifacts to the repository manager, + then include the deployment repository properties in the <<>> files used by developers. + + How the <<>> files are stored and updated is beyond the scope of this document. + The general recommendation is to manage a few <<>> files centrally, + and then use automation to distribute them to continuous integration servers and developer machines. diff --git a/content/apt/guides/mini/index.txt b/content/apt/guides/mini/index.txt index eacdd2870c..d6928cdb02 100644 --- a/content/apt/guides/mini/index.txt +++ b/content/apt/guides/mini/index.txt @@ -61,6 +61,8 @@ * {{{$prefix/guide-default-execution-ids.html} Guide to Configuring Default Mojo Executions}} + * {{{$prefix/guide-large-scale-centralized-deployments.html} Guide to Large Scale Centralized Deployments}} + ~~ ** Testing ~~ * {{{$prefix/guide-attached-tests.html}Reusable Test JARs}} diff --git a/content/site.xml b/content/site.xml index f2cef6b4f6..674e381e48 100644 --- a/content/site.xml +++ b/content/site.xml @@ -132,6 +132,7 @@ under the License. +