How to generate a XIP file for an Extension?

Last modified by Vincent Massol on 2022/01/30

XIP files are used for offline installations. XWiki doesn't provide XIP files for contrib extensions (only for the Standard Flavor).

Let's take the example of the JIRA macro and let's assume you wish to install it offline. Here's how you can do it using the XWiki Extension Maven plugin.

  1. Clone the sources of that extension. In this case git clone https://github.com/xwiki-contrib/jira.git (found in the xwiki-contrib organization)
  2. Checkout the version you wish to generate a XIP for. Let's assume you want version 8.6.3. git checkout jira-8.6.3.
  3. Create a new Maven module with a xip packaging and excluding the extensions already in the XWiki Standard Flavor since you already have these installed. Note that we depend on org.xwiki.contrib.jira:jira-macro-platform since that the top level extension we want to install (along with its dependencies). Here's how the pom.xml would look like:
    <!--
     * See the NOTICE file distributed with this work for additional
     * information regarding copyright ownership.
     *
     * This is free software; you can redistribute it and/or modify it
     * under the terms of the GNU Lesser General Public License as
     * published by the Free Software Foundation; either version 2.1 of
     * the License, or (at your option) any later version.
     *
     * This software is distributed in the hope that it will be useful,
     * but WITHOUT ANY WARRANTY; without even the implied warranty of
     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
     * Lesser General Public License for more details.
     *
     * You should have received a copy of the GNU Lesser General Public
     * License along with this software; if not, write to the Free
     * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
     * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
    -->


    <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
     <modelVersion>4.0.0</modelVersion>
     <parent>
       <groupId>org.xwiki.contrib.jira</groupId>
       <artifactId>jira-macro</artifactId>
       <version>8.6.3</version>
     </parent>
     <artifactId>jira-macro-xip</artifactId>
     <name>JIRA - Macro - XIP</name>
     <packaging>xip</packaging>
     <description>XIP for offline installation of JIRA Platform Macro</description>
     <dependencies>
       <dependency>
         <groupId>org.xwiki.contrib.jira</groupId>
         <artifactId>jira-macro-platform</artifactId>
         <version>${project.version}</version>
       </dependency>
     </dependencies>
     <build>
       <pluginManagement>
         <plugins>
           <plugin>
             <groupId>org.xwiki.commons</groupId>
             <artifactId>xwiki-commons-tool-extension-plugin</artifactId>
             <version>${commons.version}</version>
             <configuration>
               <coreExtensions>
                 <!-- We exclude what is already in the WAR -->
                 <coreExtension>
                   <groupId>org.xwiki.platform</groupId>
                   <artifactId>xwiki-platform-distribution-war-dependencies</artifactId>
                   <version>${platform.version}</version>
                   <type>pom</type>
                 </coreExtension>
               </coreExtensions>
             </configuration>
           </plugin>
         </plugins>
       </pluginManagement>
     </build>
    </project>

    Note: You could locate this module inside a jira/jira-macro/jira-macro-xip directory for example.

  4. Generate the XIP using mvn clean install. This will generate a target/jira-macro-xip-8.6.3.xip file.
  5. Unzip it into the [Permanent directory]/extension/repository directory on your XWiki server (if you get complains about already existing files don't overwrite them as that would replace other extensions already provided). We're assuming that this XWiki server doesn't have internet connection.
  6. Start or restart XWiki and go to the Extension Manager UI and choose More > Advanced Search. Then enter the extension id and version as on the following screenshot:

    advanced.png

  7. Then click Install when the Extension is found locally and click Continue after

    install.png

  8. You now have the JIRA Macro v8.6.3 installed without having needed an internet connection. Enjoy! emoticon_smile
Tags:
   

Get Connected