Skip to content

Latest commit

 

History

History
224 lines (172 loc) · 8.61 KB

README.adoc

File metadata and controls

224 lines (172 loc) · 8.61 KB
Raw

pepper

Pepper stands for "Plan Progress Review", a project management tool.

Pepper

Pepper is a web application based on (Eclipse Sirius-Web).

It allows to create data related to your project and represents the data with Gantt, Form and boards like Daily, Kanban or OKR. Follow the link for User documentation.

This repository is a mono repo containing both frontend and backend components.

To test Pepper you have two possible options:

  1. If you just want to run an already built version of the example application, follow the Quick Start.

  2. If you want to build the application yourself, follow the complete Build instructions.

Quick Start

If you want a quick overview of how Pepper looks and feels like without building the sample application yourself, you will simply need:

  • Java 17

  • Docker, or an existing PostgreSQL 12 (or later) installation with a DB user that has admin rights on the database (those are needed by the application to create its schema on first startup).

To actually run the application:

  1. Pepper uses PostgreSQL for its database. For development or local testing, the easiest way is to start a PostgreSQL instance using Docker.

    docker run -p 5439:5432 --name pepper-postgres \
                            -e POSTGRES_USER=dbuser \
                            -e POSTGRES_PASSWORD=dbpwd \
                            -e POSTGRES_DB=pepper-db \
                            -d postgres

    If you do not have Docker or want to use an existing PostgreSQL installation, adjust the command-line parameters below and make sure the DB user has admin rights on the database; they are needed to automatically create the DB schema.

  2. Start the application:

    Get the deeplab-application-{$version}.jar from the last successful build on pepper github

    java -jar deeplab-application-{$version}.jar \
          --spring.datasource.url=jdbc:postgresql://localhost:5439/pepper-db \
          --spring.datasource.username=dbuser \
          --spring.datasource.password=dbpwd

  3. Point your browser at http://localhost:8080 and enjoy!

    Warning
    		 The initial version of Pepper has some known issues with Firefox. It is recommended to use a Chrome-based browser until these are fixed.
    Note
    		 Do not forget to stop the PostgreSQL container once you are done: docker stop pepper-postgres.

Building

Requirements

To build the application yourself you will need the following tools:

  • Git, and a GitHub account

  • To build the backend components:

  • To build the frontend components:

    • LTS versions of Node and NPM: in particular, Node >= 18.7.0 is required along with npm >= 8.15.0.

Warning
 Note that there are issues with npm under Windows Subsystem for Linux (WSL). If you use WSL and encounter error messages like "Maximum call stack size exceeded" when running NPM, switch to plain Windows where this should work.

For Windows users: Due to the Maximum Path Length Limitation of Windows, you may exceed the limit of 260 characters in your PATH. To remove this limitation, apply the this procedure with this command line in PowerShell (New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force), then active the longpath option in Git in a command line with administrator rights (git config --system core.longpaths true).

GitHub Access Token

The backend of Pepper depends on sirius-emf-json and sirius-web, which is published as Maven artifacts in GitHub Packages. To build pepper locally, you need a GitHub Access Token so that Maven can download the artifacts.

  1. Create a personal token with a scope of read:package by following the GitHub documentation if you do not have one already.

    Warning
    		 Once generated, a token cannot be displayed anymore, so make sure to copy it in a secure location.

  2. Create or edit $HOME/.m2/settings.xml to tell Maven to use this token when accessing the Sirius EMF JSON repository:

    <?xml version="1.0" encoding="UTF-8"?>
<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">
  <servers>
    <server>
      <id>github-sirius-emfjson</id>
      <username>$GITHUB_USERNAME</username>
      <password>$GITHUB_ACCESS_TOKEN</password>
    </server>
    <server>
      <id>github-sirius-web</id>
      <username>$GITHUB_USERNAME</username>
      <password>$GITHUB_ACCESS_TOKEN</password>
    </server>
  </servers>
</settings>

    Be sure to replace $GITHUB_USERNAME with your GitHub user id, and $GITHUB_ACCESS_TOKEN with the value of your acess token done in the previous step.

    Important
    		 The id used in your settings.xml must be the ones mentioned above to match what is used in the POMs.

  3. Create or edit $HOME/.npmrc and add the following line:

    //npm.pkg.github.com/:_authToken=$GITHUB_ACCESS_TOKEN

    Again, be sure to replace $GITHUB_ACCESS_TOKEN with the value of your access token.

Build Pepper application

Build steps:

  1. Clone the Pepper repository pepper

  2. Build the frontend (from the frontend subfolder of Pepper main location):

    npm ci
npm run build
Note
 In case of npm ERR! Lifecycle script format-lint failed with error, try to run from the frontend subfolder the following command: npx prettier --write . (don’t forget the final dot)

  1. Install the frontend artifacts as static resource to be served by the backend. From the root directory of the repository:

    mkdir -p backend/deeplab-frontend/src/main/resources/static
cp -R frontend/deeplab-web/dist/* backend/deeplab-frontend/src/main/resources/static

  2. Build the backend (from the backend subfolder of Pepper main location):

    mvn clean verify

    The result is a ready-to-run, Spring Boot "fat JAR" in backend/deeplab-application/target/deeplab-application-<VERSION>.jar. Refer to the instructions in the "Quick Start" section above to launch it.

Development environment

Here are instructions that new Pepper developer could follow in order to set up the development environment.

Note

The set up of the Github token is required for setting up back end and front (see GitHub Access Token)

Backend set up

  1. Download your preferred Java IDE

  2. Clone Pepper repositories: pepper repository

  3. Import Pepper projects in workspace

  4. For windows users, please set your git configuration to:

    • git config core.autocrlf true

    • git config core.eol lf

    • git config user.name "$FirstName $ SecondName"

    • git config user.email "$email"

  5. Set up your IDE with

    • Checkstyle configuration.

      backend/deeplab-resources/checkstyle/CheckstyleConfiguration.xml

    • Editor configurations

      backend/deeplab-resources/editor

  1. Create Launch Configuration for Pepper server

    • Start the server with DeeplabWeb.java class.

    • For debugging, add the following environment variable spring.profiles.active=dev

Frontend set up

  1. Open the frontend folder in VSCode

  2. Install dependencies using npm install in the terminal

Launch Application as a developer

  1. Run database docker image (see Docker command)

  2. Launch backend from your Java IDE (see Launch configuration)

  3. Launch frontend npm start

License

Everything in this repository is Open Source. Except when explicitly mentioned otherwise (e.g. for some resources likes images), the license is Eclipse Public License* v 2.0.