Setting up a development environment

Prerequisites

Before you can start make sure you have the following application installed. 

• Maven 3.8.4 or higher (build project)
• Git (source control)
• Java 8 
• openJDK 1.8 or equivalent
• PHP 8 (Rendering Service)
• Docker 20.10.21 or higher (deployment)
• Docker Compose 2.13.0 or higher (deployment)
• npm 7 or higher (frontend)
• nodejs 14 (frontend)

To get access to the edu-sharing maven repositories you need to edit the maven ~/.m2/settings.xml or create it if it doesn't exist.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <mirrors>
    <!-- MIRROR OPTIONS TO THE EDU-SHARING MAVEN MIRROR -->
    <mirror>
      <id>edusharing-mirror</id>
      <url>https://artifacts.edu-sharing.com/repository/maven-mirror/</url>
      <mirrorOf>!edusharing-remote,!archetype,*</mirrorOf>
    </mirror>
  </mirrors>
  <servers>
    <!-- GIVES YOU ACCESS TO PROTECTED AREAS E.G. CUSTOMER SPECIFIC PROJECTS -->
    <!-- ONLY UNCOMMENT IF YOU HAVE AN ACCOUNT ON OUR SERVER
    <server>
      <id>archetype</id>
      <username>USERNAME</username>
      <password>PASSWORD</password>
    </server>
    <server>
      <id>edusharing-remote</id>
      <username>USERNAME</username>
      <password>PASSWORD</password>
    </server>
    -->
  </servers>
  <profiles>
    <!-- A MAVEN PROFILE TO ACCESS ARCHETYPES -->
    <profile>
      <id>mvn.repositories</id>
      <repositories>
        <repository>
          <id>archetype</id>
          <url>https://artifacts.edu-sharing.com/repository/maven-remote</url>
        </repository>
      </repositories>
    </profile>
  </profiles>
    <activeProfiles> 
      <!-- ACTIVATES THE PROFILE DEFINED ABOVE BY DEFAULT -->
      <activeProfile>mvn.repositories</activeProfile>
    </activeProfiles>
</settings>

Setting up a custom deploy project

The simplest and easiest way to setup a deploy project is to use the edu_sharing-community-sdk maven archetype. It's a maven project template which provides the overall docker structure including docker compose files, kubernetes files as well as utility scripts to deploy, debug and develop edu-sharing locally. It also creates a default project structure where you can add your customization for edu-sharing. 

Your Project should look like this

Deploy configurations

Plugins

Plugins extents the behavior of edu-sharing. There version is defined inside the edu_sharing-community-bom project. Plugins will be mixed together in the deploy project. Some parts get composed in the repository service docker, other are just additional containers that need to be started and therefore added to compose and helm configurations. Which plugins are added will be controlled by maven profiles defined in the deploy project. Due to a bug, it is not recommended to control profiles from within Intellij's maven tool window. The recommended way to control profiles is by using the maven environment variable for the specific plugin. To set maven environment variables go to File → Settings -> Build, Exectuion, Deploymnt → Build Tools → Maven → Runner click on "Environment variables"

Environment variables

edu-sharing version

The version of edu-sharing and it's components is defined by the bom.bom.version property in the root pom.xml of the deploy project. You should set the  bom.bom.version property value to a specific version e.g. 7.0.0-RC57. If you also want to develop the edu-sharing core you should set the maven environment variable DEV=true to activate the maven dev profile which overrides the bom.bom.version value with ${project.version} which activates the git branch naming mechanism.

  <properties>
    <!-- edu-sharing version -->
    <bom.bom.version>7.0.0-RC57</bom.bom.version>
  </properties>

  ...
  <dependencyManagement>
      <dependency>
        <groupId>${project.groupId}</groupId>
        <artifactId>edu_sharing-community-bom</artifactId>
        <version>${bom.bom.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
	...
  </dependencyManagement>

Launching edu-sharing

To run, debug and develop edu-sharing we've create a deploy/docker/deploy.sh script for that. Basically it calls docker compose commands with the required set of docker-compose files for you. E.g. docker compose -f file1.yml -f file2.yml -f file3.yml up. The compose files are called from  docker/compose/target/compose directory therefore you have to build you deploy project first.

Below, you can find a list of useful commands and its meanings. Service means the serivce defined in the docker compose files. Square brackets means that this argument is optional, three dots means there can be more than one and angular brackets means required.

Deploy project without core components

This section is for the case you want to develop an edu-sharing extension only without checking out the core community components.
In this case you have to use rstart, rdebug and rdev to start edu-sharing. Otherwise the docker images of edu-sharing plugins won't be found. But before you can do so, You have to delete the following files:

• deploy/docker/compose/src/main/compose/0_edusharing-remote.yml
• deploy/docker/repository/compose/src/main/compose/1_repository-remote.yml
• deploy/docker/services/rendering/compose/src/main/compose/1_rendering-remote.yml

To use rdev also requires some changes:

In "deploy/docker/repository/compose/src/main/compose/1_repository-dev.yml" file delete all line starting with "- "${GIT_ROOT}/repository/Backend" under volumes.
Delete the deploy/docker/services/rendering/compose/src/main/compose/1_rendering-dev.yml file.

deploy/docker/repository/compose/pom.xml add <excludes>*-dev.yml</excludes> to the configuration part of the maven-dependency-plugin plugin.

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <executions>
          <execution>
            <id>plugins</id>
            <goals>
              <goal>unpack-dependencies</goal>
            </goals>
            <phase>generate-resources</phase>
            <configuration>
              <includeArtifactIds>
                edu_sharing-community-repository-plugin-elastic-deploy-docker-compose,
                edu_sharing-community-repository-plugin-mongo-deploy-docker-compose,
                edu_sharing-enterprise-repository-plugin-antivirus-deploy-docker-compose,
                edu_sharing-enterprise-repository-plugin-cluster-deploy-docker-compose,
                edu_sharing-enterprise-repository-plugin-remote-deploy-docker-compose,
                edu_sharing-enterprise-repository-plugin-transform-deploy-docker-compose
              </includeArtifactIds>
              <excludes>META-INF/**</excludes>
              <excludes>*-dev.yml</excludes>
              <outputDirectory>${project.build.directory}/compose</outputDirectory>
            </configuration>
          </execution>
        </executions>
      </plugin>

 Don't forget to rebuild (mvn clean install) your project.  

edu-sharing core developing

Adding edu-sharing core repositories

If you want to modify the existing core modules of edu-sharing the best practice is to create a fork of the desired github repos and check them out in the same parent folder as your deploy project.
After you've created all repositories, open your deploy project and in the maven module click on the plus icon to add them to your project.

The required projects:

Build order

It's important to retain the build order otherwise you'll discover weird behaviors or bugs because older artifact versions will be used in the depending projects.