Silverpeas-Distribution

Silverpeas-Distribution produces the official distribution of Silverpeas, the Free and Open Source Collaborative Platform.

A distribution of Silverpeas isn't the platform itself: it is a small archive made up of an installer, a configurator, a runner and a set of configuration files whose purpose is to fetch, to assemble, to set up and to run both Silverpeas and the Jakarta EE application server hosting it (currently Wildfly).

Everything is driven by the Gradle build platform and wrapped into a single executable: silverpeas for Unix-like systems and silverpeas.bat for Windows.

Table of contents

• How does it work?
• Requirements
• Content of the distribution archive
• Installing and running Silverpeas
• Available commands
• Configuration
• Customizing a Silverpeas installation
• Logs
• Development mode
• Building the distribution
• Source layout
• Releasing
• Related projects
• License

How does it work?

The distribution ships almost nothing but the ability to get what it needs, when it needs it:

1. Bootstrap. The silverpeas script is a Gradle wrapper. At its first execution it downloads the Gradle distribution declared in bin/gradle/wrapper/gradle-wrapper.properties and caches it in the Gradle user home.
2. Tooling. The installer and the configurator are both carried by silversetup, a custom standalone Gradle plugin. It is resolved from the local Maven repository, then from the Silverpeas Nexus, and cached (see bin/settings.gradle).
3. Runner. bin/build.gradle is the runner: it decorates the silversetup tasks with the tasks required to start, to debug, to stop, to redeploy and to get the status of Silverpeas.
4. Construction. The install command downloads all the software bundles that make up Silverpeas (declared in bin/silverpeas.gradle, the silverpeas-assembly artifact by default), caches them, unpacks them and recombines their content into a single web application archive, silverpeas.war.
5. Configuration. Wildfly is configured by applying the JBoss CLI and Groovy scripts of configuration/jboss, then Silverpeas itself is configured by applying the XML and Groovy scripts of configuration/silverpeas. Both use the settings of configuration/config.properties.
6. Migration. The data source schema is created or migrated to the version being installed.
7. Deployment. silverpeas.war and the other artifacts are deployed into Wildfly.

Each step checks the current state before acting: the bundles already extracted aren't extracted again, a configuration script already applied isn't applied again, and a migration already performed isn't replayed. Re-running install therefore only does what remains to be done.

Requirements

Requirement	Version / Notes
Java	JDK 17 (Jakarta EE 10 / Wildfly 34 baseline)
JEE application server	Wildfly 34 in standalone mode (the domain mode isn't supported)
Database	PostgreSQL, Microsoft SQL Server, Oracle or H2
Network access	The Silverpeas Nexus, the Gradle distribution service and the Maven Central repository, unless everything is already cached

Optionally:

• an SMTP server, for the notifications sent by email;
• a document conversion service (LibreOffice running as a daemon), for the preview and the conversion of the documents.

Content of the distribution archive

The distribution is a ZIP archive named silverpeas-<version>-<server.distribution>.zip (for example silverpeas-6.5-wildfly34.zip). Once unpacked, the resulting directory is the SILVERPEAS_HOME directory:

silverpeas-<version>-<server>/
├── BUILD                          # build version, timestamp and Git commit of the distribution
├── bin/
│   ├── silverpeas                 # the launcher for Unix-like systems
│   ├── silverpeas.bat             # the launcher for Windows
│   ├── settings.gradle            # where to find the silversetup plugin
│   ├── build.gradle               # the runner: start/stop/status/debug/redeploy/reload/clean tasks
│   ├── silverpeas.gradle          # the software bundles making up this Silverpeas installation
│   ├── gradle/wrapper/            # the Gradle wrapper
│   └── lib/                       # drop here the local jars (JDBC drivers, custom libraries)
├── configuration/
│   ├── sample_config.properties   # the documented template of the global configuration
│   ├── jboss/                     # the configuration scripts of Wildfly (*.cli, *.groovy)
│   │   └── modules/               # the additional JBoss modules to install into Wildfly
│   └── silverpeas/                # the configuration scripts of Silverpeas (*.xml, *.groovy)
│       └── resources/             # the resources used by those scripts (JCR schema, indexes, ...)
└── log/                           # where the installation and execution logs are written

Once Silverpeas has been installed, some additional directories are generated within SILVERPEAS_HOME, among them data (the users' data), deployments (the artifacts to deploy into Wildfly), properties, xmlcomponents, resources, migrations and build (the working directory of the installer).

Installing and running Silverpeas

1. Install a JDK 17 and a Wildfly 34, and set up the database to be used by Silverpeas.
2. Unpack the distribution archive wherever you want.
3. Set the two required environment variables:

   $ export SILVERPEAS_HOME=/path/to/silverpeas-<version>-<server>
   $ export JBOSS_HOME=/path/to/wildfly-34.x.x.Final

   Both are checked by silversetup; the installation fails fast if one of them isn't set or doesn't refer to an existing directory. (SILVERPEAS_HOME is computed by the launcher itself, but exporting it explicitly is safer.)
4. Create the global configuration file from its documented template and edit it:

   $ cp $SILVERPEAS_HOME/configuration/sample_config.properties \
        $SILVERPEAS_HOME/configuration/config.properties

   Every property is commented out and documented in the template: uncomment and value only the ones you want to override. At least the database access, the administrator email address and the sender email address should be set.
5. If your database isn't H2 or PostgreSQL, drop its JDBC driver into $SILVERPEAS_HOME/bin/lib (this is required for Oracle, whose driver cannot be distributed through a Maven repository for licensing reasons).
6. Install Silverpeas, then run it:

   $ cd $SILVERPEAS_HOME/bin
   $ ./silverpeas install
   $ ./silverpeas start

7. Silverpeas is then available at the URL declared by SERVER_URL (http://localhost:8000 by default).

To move an existing installation to a newer version, unpack the new distribution over the current SILVERPEAS_HOME and check configuration/config.properties against the new sample_config.properties. Then either run ./silverpeas install again, which performs only the steps that are required by the new version, or ./silverpeas upgrade, which first cleans the artifacts of the previous build before installing the new version from scratch.

Available commands

All the commands are Gradle tasks and are invoked as ./silverpeas <command> (or silverpeas.bat <command> on Windows). Use ./silverpeas tasks to list them all.

Tasks provided by the silversetup plugin (the installer and configurator):

Command	Description
assemble	Downloads and extracts all the software bundles making up Silverpeas
build	Generates the Silverpeas web application from the extracted bundles
construct	assemble then build
configure_jboss	Configures Wildfly for Silverpeas
configure_silverpeas	Configures Silverpeas itself
configure	Configures both Wildfly and Silverpeas
migrate	Creates or migrates the data source schema to the current version
install	The full chain: construct, configure, migrate and deployment into Wildfly
upgrade	clean then install, to upgrade an existing installation

Tasks provided by the runner (bin/build.gradle):

Command	Description
start	Starts Silverpeas (that is, starts Wildfly with Silverpeas deployed)
stop	Stops Silverpeas
debug	Starts Silverpeas in debug mode; the port is given by -Pport=<port> (5005 by default)
status	Tells whether Silverpeas is configured, running and active
redeploy	Undeploys then deploys again all the artifacts in SILVERPEAS_HOME/deployments
reload	Rebuilds and redeploys silverpeas.war in a running Wildfly (development mode only)
clean	Stops Silverpeas if needed and removes all the artifacts produced by a previous build

Configuration

The global configuration file

configuration/config.properties is the single entry point for the settings of an installation. It overrides the default settings embedded within the silversetup plugin, and its properties are then expanded by the configuration scripts into the properties files of both Silverpeas and Wildfly. configuration/sample_config.properties documents every supported property, grouped by concern:

• the location of the system directories (data, temporary files, logs);
• the credentials and the email address of the Silverpeas administrator;
• the global settings of the platform (languages, logging level, log rotation);
• the sizing and the options of the JVM;
• the application server (URL, HTTP port, execution mode, starting timeout, reverse-proxy awareness, availability of the management console);
• the database (type, host, port, credentials, connection pools, transaction timeout);
• the JCR (the Java Content Repository storing the metadata of the documents);
• the document conversion service;
• the SMTP server;
• the HTTP(S) proxy.

The configuration scripts

The configuration is performed by applying, in the lexicographical order of their name, the scripts found in the two dedicated directories:

• configuration/jboss — JBoss CLI scripts (*.cli) and Groovy scripts (*.groovy) applied to Wildfly: the datasource of Silverpeas, the JMS queues and topics, the HTTP port, the transaction timeout, the deployment timeout, the maximum size of an HTTP request, the logging profile and the log rotation, the removal of the unused Wildfly extensions, the hardening of the HTTP response headers, the reverse-proxy awareness, and so on. Its modules subdirectory contains the additional JBoss modules copied into JBOSS_HOME/modules (for instance org.mnode.ical4j, which requires its own class loader so as not to interfere with Silverpeas).
• configuration/silverpeas — the descriptor 00-SilverpeasSettings.xml, which values the properties files of Silverpeas from config.properties, followed by the numbered Groovy scripts performing the tasks that cannot be expressed declaratively: initialization and migration of the JCR, the JDBC dialect of the scheduler, the access to the conversion service, the generation of the tickers, and the one-shot fixes applied to the existing contents.

The state of the configuration is persisted into the hidden file configuration/.context, so a script that has already been applied isn't applied again needlessly.

Customizing a Silverpeas installation

bin/silverpeas.gradle declares the version of Silverpeas to install and the software bundles that make it up, through three dependency configurations:

Configuration	Purpose
silverpeas	The standard Silverpeas modules (a war and, optionally, a configuration archive). By default, the single org.silverpeas:silverpeas-assembly artifact
custom	The custom bundles adding specific functionalities to Silverpeas (custom workflows, specific behaviours, ...)
library	The third-party jars to include into Silverpeas, and the JDBC drivers. Fed by default from bin/lib

Any jar dropped into bin/lib is picked up by the library configuration. If it is recognized as a JDBC driver, it is deployed into Wildfly and wired to the datasource of Silverpeas; otherwise it is added to the libraries of the Silverpeas web application.

Logs

The log directory of SILVERPEAS_HOME gathers:

• build-<timestamp>.log — the verbose traces of the construction, configuration and migration of Silverpeas. This is the file to look at when an installation fails.
• jboss-cli-output.log — the output of the JBoss CLI scripts applied to Wildfly.
• jboss_output.log — the standard output of the running Wildfly/Silverpeas.

The application logs of Silverpeas itself are written where SILVERPEAS_LOG points to.

Development mode

The development mode is meant for the developers of Silverpeas and must not be used in production. It is enabled through environment variables:

Variable	Effect
SILVERPEAS_DEV_MODE	true to enable the development mode
SILVERPEAS_DIST_DIR	The directory into which the Silverpeas web application is exploded, instead of the default working directory

In this mode the JSPs are recompiled on the fly and the reload task becomes available: it disassembles the bundles again, regenerates the web application and redeploys it into the running Wildfly, without any restart.

Building the distribution

The build of the distribution archive itself is handled by Maven (the Gradle scripts it contains are only executed at installation time, on the user's machine):

$ mvn clean package

produces target/silverpeas-<version>-<server.distribution>.zip from the assembly descriptor src/main/resources/assembly.xml.

Some noteworthy points of the build:

• the server.distribution property of the POM (wildfly34) is part of the name of the archive and states the targeted application server;
• BUILD, bin/settings.gradle and bin/silverpeas.gradle are filtered by Maven, so that the version of the project is injected into them. Because the escape string of the filtering is '', a ${...} expression prefixed by '' is left untouched and remains a Gradle expression evaluated at installation time;
• bin/silverpeas is made executable (mode 755) within the archive.

To sign the archive and publish it onto the Silverpeas download server:

$ mvn clean install -Dgpg.keyname=GPG_KEY -Dgpg.passphrase=GPG_PASSPHRASE -Dscp.user=SCP_USER

The verify phase signs the archive with GPG (producing a detached .asc signature) and the install phase uploads both the archive and its signature onto www.silverpeas.org over SCP.

Source layout

.
├── pom.xml                        # the Maven build of the distribution archive
├── README.md
├── license.txt                    # the GNU AGPL v3
├── exceptions.txt                 # the Silverpeas FLOSS License Exception
└── src/
    ├── doc/RELEASE.md             # the release process of the whole Silverpeas platform
    ├── main/resources/
    │   └── assembly.xml           # the descriptor of the distribution archive
    └── main/dist/                 # the very content of the distribution archive
        ├── BUILD
        ├── bin/
        ├── configuration/
        └── log/

Releasing

Silverpeas-Distribution belongs to the set of projects made up of Silverpeas-Core, Silverpeas-Components, Silverpeas-Assembly, Silverpeas-Setup and itself: any change in this set implies a release of the whole set at the same version, and this project is always the last one to be released.

The complete and ordered release process of the platform, along with the different release modes (Jenkins pipeline, Maven Release plugin, by hand), is described in src/doc/RELEASE.md.

Related projects

Project	Purpose
Silverpeas-Core	The core of the Silverpeas platform
Silverpeas-Components	The applications of the platform
Silverpeas-Assembly	The assembly of the core and of the components into the software bundles fetched by this distribution
Silverpeas-Setup	The silversetup Gradle plugin: the installer and the configurator
Silverpeas-Looks	The graphical looks of the platform
Silverpeas-Project	The parent POM of the Maven projects of the platform
Jenkins-Pipelines	The CI/CD pipelines of the platform

License

Silverpeas is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

As a special exception to the terms and conditions of version 3.0 of the AGPL, the Silverpeas FLOSS License Exception applies; it is also available online.