| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/asciidoc/developers/publishing-site.adoc |
| | Rendered using Apache Maven Fluido Skin 1.11.0 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" /> |
| <title>Archiva – </title> |
| <link rel="stylesheet" href="../css/apache-maven-fluido-1.11.0.min.css" /> |
| <link rel="stylesheet" href="../css/site.css" /> |
| <link rel="stylesheet" href="../css/print.css" media="print" /> |
| <script src="../js/apache-maven-fluido-1.11.0.min.js"></script> |
| <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css"> |
| |
| <!-- Matomo --> |
| <script> |
| var _paq = window._paq = window._paq || []; |
| _paq.push(['disableCookies']); |
| _paq.push(['trackPageView']); |
| _paq.push(['enableLinkTracking']); |
| |
| (function() { |
| var u="https://analytics.apache.org"; |
| _paq.push(['setTrackerUrl', u+'/matomo.php']); |
| _paq.push(['setSiteId', '10']); |
| var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; |
| g.async=true; g.src=u+'/matomo.js'; s.parentNode.insertBefore(g,s); |
| })(); |
| </script> |
| <!-- End Matomo Code --> |
| </head> |
| <body class="topBarEnabled"> |
| <a href="https://github.com/apache/archiva"> |
| <img style="position: absolute; top: 0; right: 0; border: 0; z-index: 10000;" |
| src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png" |
| alt="Fork me on GitHub"> |
| </a> |
| <header id="topbar" class="navbar navbar-fixed-top "> |
| <div class="navbar-inner"> |
| <div class="container"> |
| <a data-target=".nav-collapse" data-toggle="collapse" class="btn btn-navbar"> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </a> |
| <nav class="nav-collapse"> |
| <ul class="nav"> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown">Introduction <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="../index.html" title="About">About</a></li> |
| <li><a href="../download.html" title="Downloads">Downloads</a></li> |
| <li><a href="../versions.html" title="Versions">Versions</a></li> |
| <li><a href="../mailing-lists.html" title="Mailing Lists">Mailing Lists</a></li> |
| <li><a href="../security.html" title="Security">Security</a></li> |
| <li class="dropdown-submenu"> |
| <a href="../" title="Documentation">Documentation</a> |
| <ul class="dropdown-menu"> |
| <li><a href="../docs/2.2.9/" title="Release 2.2.9">Release 2.2.9</a></li> |
| <li><a href="../docs/3.0.0-SNAPSHOT/" title="Dev 3.0.0-SNAPSHOT">Dev 3.0.0-SNAPSHOT</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown">Development <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="../developers/building.html" title="Build Apache Archiva">Build Apache Archiva</a></li> |
| <li><a href="../get-involved.html" title="Get involved">Get involved</a></li> |
| <li><a href="../developers/how-we-do-things.html" title="How we do things">How we do things</a></li> |
| <li class="dropdown-submenu"> |
| <a href="../" title="Developer Reference">Developer Reference</a> |
| <ul class="dropdown-menu"> |
| <li><a href="../ref/2.2.9/index.html" title="Archiva 2.2.9">Archiva 2.2.9</a></li> |
| <li><a href="../ref/3.0.0-SNAPSHOT/index.html" title="Archiva 3.0.0-SNAPSHOT">Archiva 3.0.0-SNAPSHOT</a></li> |
| <li><a href="../redback/core/3.0.0-SNAPSHOT/index.html" title="Redback 3.0.0-SNAPSHOT">Redback 3.0.0-SNAPSHOT</a></li> |
| </ul> |
| </li> |
| <li><a href="../redback/index.html" title="Redback">Redback</a></li> |
| <li><a href="../components/index.html" title="Archiva Components Project">Archiva Components Project</a></li> |
| <li class="dropdown-submenu"> |
| <a href="../jsui/index.html" title="Javascript application Architecture">Javascript application Architecture</a> |
| <ul class="dropdown-menu"> |
| <li><a href="../jsui/rest.html" title="Rest service">Rest service</a></li> |
| <li><a href="../jsui/template-loading.html" title="JS Template loading">JS Template loading</a></li> |
| <li><a href="../jsui/i18n.html" title="i18n">i18n</a></li> |
| <li><a href="../jsui/knockout-binding.html" title="Knockout Binding">Knockout Binding</a></li> |
| <li><a href="../jsui/generics-js.html" title="Generic Javascipts">Generic Javascipts</a></li> |
| </ul> |
| </li> |
| <li><a href="../developers/releasing.html" title="Releasing">Releasing</a></li> |
| <li><a title="Site Publish">Site Publish</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="https://www.apache.org/foundation/how-it-works.html" title="How Apache Works">How Apache Works</a></li> |
| <li><a href="https://www.apache.org/foundation/" title="Foundation">Foundation</a></li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html" title="Sponsoring Apache">Sponsoring Apache</a></li> |
| <li><a href="https://www.apache.org/foundation/thanks.html" title="Thanks">Thanks</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown">Project Documentation <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li class="dropdown-submenu"> |
| <a href="../project-info.html" title="Project Information">Project Information</a> |
| <ul class="dropdown-menu"> |
| <li><a href="../ci-management.html" title="CI Management">CI Management</a></li> |
| <li><a href="../mailing-lists.html" title="Mailing Lists">Mailing Lists</a></li> |
| <li><a href="../issue-management.html" title="Issue Management">Issue Management</a></li> |
| <li><a href="../licenses.html" title="Licenses">Licenses</a></li> |
| <li><a href="../team.html" title="Team">Team</a></li> |
| <li><a href="../scm.html" title="Source Code Management">Source Code Management</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| <div class="nav-collapse"> |
| <form id="search-form" action="https://www.google.com/search" method="get" class="navbar-search pull-right" > |
| <input value="https://archiva.apache.org/" name="sitesearch" type="hidden"/> |
| <input class="search-query" name="q" id="query" type="text" /> |
| </form> |
| <script>asyncJs( 'https://cse.google.com/brand?form=search-form' )</script> |
| </div> |
| </div> |
| </div> |
| </header> |
| <div class="container"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><a href="../index.html" id="bannerLeft"><img src="../images/archiva.png" alt="Apache Archiva" style="" /></a></div> |
| <div class="pull-right"><a href="https://www.apache.org/" id="bannerRight"><img src="https://www.apache.org/images/asf_logo_wide_2016.png" alt="Apache Software Foundation" style="" /></a></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li class=""><a href="https://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li> |
| <li class=""><a href="../" title="Archiva">Archiva</a><span class="divider">/</span></li> |
| <li class="active "></li> |
| <li id="publishDate" class="pull-right">Last Published: 09 Oct 2022</li> |
| </ul> |
| </div> |
| </header> |
| <main id="bodyColumn" > |
| <h1>Archiva Site Publishing</h1> |
| <div id="toc" class="toc"> |
| <div id="toctitle">Table of Contents</div> |
| <ul class="sectlevel1"> |
| <li><a href="#general_information_about_the_site_publish_process">General information about the site publish process</a></li> |
| <li><a href="#where_is_site_content_generated">Where is site content generated?</a></li> |
| <li><a href="#tasks_for_publishing">Tasks for publishing</a> |
| <ul class="sectlevel2"> |
| <li><a href="#using_the_script_linuxbash">Using the script (Linux/Bash)</a></li> |
| <li><a href="#run_the_process_manually">Run the process manually</a></li> |
| </ul> |
| </li> |
| <li><a href="#information_about_maven_script_configuration">Information about Maven / Script configuration</a></li> |
| <li><a href="#information_about_site_generation">Information about site generation</a></li> |
| </ul> |
| </div> |
| <div class="sect1"> |
| <h2 id="general_information_about_the_site_publish_process">General information about the site publish process</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The archiva site is built from multiple different more or less independent modules. The build process |
| uses <code>maven-site-plugin</code> for generating the static HTML pages and stylesheets and <code>scm-publish-plugin</code> for |
| publishing the results to the repository.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The generated HTML pages are stored at a git repository: |
| <a href="https://gitbox.apache.org/repos/asf?p=archiva-web-content.git"><code>archiva-web-content.git</code></a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The git repository contains a <code>.asf.yaml</code> file that defines the branch <code>asf-staging</code> as staging branch. The |
| master branch is used by git-pub-sub to publish the official archiva site at <a href="https://archiva.apache.org" class="bare">https://archiva.apache.org</a> .</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you push something to the <code>asf-staging</code> branch you can see the changes immediately at <a href="https://archiva.staged.apache.org" class="bare">https://archiva.staged.apache.org</a></p> |
| </div> |
| <div class="paragraph"> |
| <p>The maven site report and publishing plugins are configured to deploy the the asf-staging branch. That means the |
| overall publishing process is the following:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Generate the site content for a module by using the scripts / maven</p> |
| </li> |
| <li> |
| <p>Use the maven publish plugin to push the generated pages to the asf-staging branch of archiva-web-content.git</p> |
| </li> |
| <li> |
| <p>Check the generated content at <a href="https://archiva.staged.apache.org/" class="bare">https://archiva.staged.apache.org/</a></p> |
| </li> |
| <li> |
| <p>If the result is fine, release the new content by merging the content from <code>asf-staging</code> to the <code>master</code> branch</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For all modules there exists a script that runs all the steps (apart from the check on the staged site). Currently |
| the script runs only on Linux / Bash. For details see below.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="where_is_site_content_generated">Where is site content generated?</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The Archiva site is generated from the following components:</p> |
| </div> |
| <table class="table table-striped bodyTable frame-all grid-all bodyTable" style="width:100%"><colgroup><col style="width: 16.6666%;" /><col style="width: 16.6666%;" /><col style="width: 16.6666%;" /><col style="width: 16.6666%;" /><col style="width: 16.6666%;" /><col style="width: 16.667%;" /><tr class="a"><th class="halign-left valign-top">Component</th><th class="halign-left valign-top">Content</th><th class="halign-left valign-top">Git Repository</th><th class="halign-left valign-top">Path inside Repo</th><th class="halign-left valign-top">Publish Path</th><th class="halign-left valign-top">Skript</th></tr><tr class="b"><td class="halign-left valign-top">Archiva Site</td><td class="halign-left valign-top">Main Pages, like index.html. General information.</td><td class="halign-left valign-top"><a href="https://gitbox.apache.org/repos/asf?p=archiva-site.git"><code>archiva-site.git</code></a></td><td class="halign-left valign-top">/</td><td class="halign-left valign-top">/</td><td class="halign-left valign-top"><code>deploySite.sh</code></td></tr><tr class="a"><td class="halign-left valign-top">Archiva Documentation</td><td class="halign-left valign-top">Archiva User Documentation. Archiva Configuration.</td><td class="halign-left valign-top"><a href="https://gitbox.apache.org/repos/asf?p=archiva.git"><code>archiva.git</code></a></td><td class="halign-left valign-top">/archiva-docs</td><td class="halign-left valign-top">/docs/${project.version}</td><td class="halign-left valign-top"><code>archiva-docs/deploySite.sh</code></td></tr><tr class="b"><td class="halign-left valign-top">Archiva Reference Documentation</td><td class="halign-left valign-top">Developer documentation for Archiva, API Javadoc pages. Information for each maven module.</td><td class="halign-left valign-top"><a href="https://gitbox.apache.org/repos/asf?p=archiva.git"><code>archiva.git</code></a></td><td class="halign-left valign-top">/archiva-modules</td><td class="halign-left valign-top">/ref/${project.version}</td><td class="halign-left valign-top"><code>archiva-modules/deploySite.sh</code></td></tr><tr class="a"><td class="halign-left valign-top">Redback Site</td><td class="halign-left valign-top">Pages for Redback. General information about redback.</td><td class="halign-left valign-top"><a href="https://gitbox.apache.org/repos/asf?p=archiva-redback-site.git"><code>archiva-redback-site.git</code></a></td><td class="halign-left valign-top">/</td><td class="halign-left valign-top">/redback</td><td class="halign-left valign-top"><code>deploySite.sh</code></td></tr><tr class="b"><td class="halign-left valign-top">Redback Reference Documentation</td><td class="halign-left valign-top">Developer documentation for Redback, API Javadoc pages. Information for each maven module.</td><td class="halign-left valign-top"><a href="https://gitbox.apache.org/repos/asf?p=archiva-redback-core.git"><code>archiva-redback-core.git</code></a></td><td class="halign-left valign-top">/</td><td class="halign-left valign-top">/core/${project.version}</td><td class="halign-left valign-top"><code>deploySite.sh</code></td></tr><tr class="a"><td class="halign-left valign-top">Archiva Component Documentation</td><td class="halign-left valign-top">Information about the Archiva Components</td><td class="halign-left valign-top"><a href="https://gitbox.apache.org/repos/asf?p=archiva-components.git"><code>archiva-components.git</code></a></td><td class="halign-left valign-top">/</td><td class="halign-left valign-top">/components</td><td class="halign-left valign-top"><code>deploySite.sh</code></td></tr></colgroup></table> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="tasks_for_publishing">Tasks for publishing</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="using_the_script_linuxbash">Using the script (Linux/Bash)</h3> |
| <div class="paragraph"> |
| <p>The easiest way is always to use the script <code>deploySite.sh</code> in the directory of the corresponding repository.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>cd <path inside repo for component> |
| ./deploySite.sh |
| ... |
| ... |
| ***************************************** |
| >>>> Finished the site stage process <<<< |
| > You can check the content in the folder target/staging or by opening the following url |
| > file:///archiva/archiva-modules/target/staging/ref/3.0.0-SNAPSHOT/index.html |
| > |
| > If everything is fine enter yes. After that the publish process will be started. |
| Do you want to publish (yes/no)? yes</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When this output is shown you can check the staging output for this component only on the given path.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you enter <code>y</code> or <code>yes</code> here, the content will be pushed to the <code>asf-staging</code>-branch at <code>archiva-web-content.git</code> |
| If you enter any other key, the process will be aborted.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After the page was pushed to the <code>asf-staging</code>-branch, you can check the result at <a href="https://archiva.staged.apache.org/" class="bare">https://archiva.staged.apache.org/</a></p> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>If you would like to check the page with a local clone of archiva-web-content.git you can run the script with:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>./deploySite.sh -DsiteRepositoryUrl=scm:git:file:///${path-to-your-local-archiva}/archiva-web-content.git</pre> |
| </div> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>If the result on the staged URL is fine you have to merge the branch to the master branch:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre># git clone https://gitbox.apache.org/repos/asf/archiva-web-content.git |
| cd archiva-web-content |
| git checkout master |
| git merge --ff-only asf-staging |
| git push</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="run_the_process_manually">Run the process manually</h3> |
| <div class="sect3"> |
| <h4 id="generating_site_pages_for_a_component">Generating Site Pages for a component</h4> |
| <div class="paragraph"> |
| <p>The script basically runs</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>mvn clean site |
| mvn site:stage</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The pom.xml has a plugin definition to checkout the repository as sparse checkout to a local directory <code>.site-content</code> |
| The patterns for the sparse checkout are stored in the file <code>git-sparse-checkout-pattern</code></p> |
| </div> |
| <div class="paragraph"> |
| <p>The content of the module and all submodules is put to the directory <code>target/staging/${Component Path}</code></p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="publishing_to_the_staging_branch">Publishing to the staging branch</h4> |
| <div class="paragraph"> |
| <p>This is the part that is run, when you answer <code>y</code> or <code>yes</code> for publishing.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>mvn scm-publish:publish-scm</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This checks the differences in .site-content and pushes the differences to the <code>asf-staging</code> branch.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="information_about_maven_script_configuration">Information about Maven / Script configuration</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>There are some properties in the pom.xml that are used by the deploySite.sh. You should always make sure, that |
| these properties are set to the corresponding values for the given module:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><scmPubCheckoutDirectory>.site-content</scmPubCheckoutDirectory>: The directory for the sparse checkout</p> |
| </li> |
| <li> |
| <p><scmPublishBranch>asf-staging</scmPublishBranch>: The staging branch</p> |
| </li> |
| <li> |
| <p><scmPublishPath>/</scmPublishPath>: The path relative to the base URL where the content is placed</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The helper script <code>checkoutSite.sh</code> is used for running the sparse checkout of the content.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For multi-module projects the CSS (site.css) is always relative to the module directory. Therefore, we have |
| a link to the stylesheet at <code>/css/site.css</code> in <code>site.xml</code></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="information_about_site_generation">Information about site generation</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Most content is written in apt and xdoc. New documentation can/should be written in asciidoc. Asciidoc needs some css modification |
| to get the styles right. So please check the generated content before publishing it.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For multi-module builds you should add the central <code>/css/site.css</code> to the <code><head></code>-Section in <code>site.xml</code>. Because submodules |
| include only their own site.css and not the parent stylesheets. This can be done with:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre><head> |
| ... |
| <![CDATA[ <link rel="stylesheet" href="/css/site.css" type="text/css" >]]> |
| ... |
| </head></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| </main> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container"> |
| <div class="row"> |
| <div class="row pull-left">Apache Archiva, Archiva, Apache, the Apache feather logo, and the Apache Archiva project logos are trademarks of The Apache Software Foundation.</div> |
| <div class="row"> |
| |
| </div> |
| <div class="row"> |
| <p> |
| <a href="https://archiva.apache.org/privacy-policy.html">Privacy Policy</a> |
| </p> |
| </div> |
| </div> |
| <p id="poweredBy" class="pull-right"><a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> |
| </p> |
| </div> |
| </footer> |
| <script> |
| if(anchors) { |
| anchors.add(); |
| } |
| </script> |
| </body> |
| </html> |
