Skip to content

Home

Jump to bottom
Anupam Ghosh edited this page Jun 28, 2022 · 2 revisions

Welcome to the SW360 Wiki!

For development, please see the README.md file of the project first. Please check also the pages on the right widget of pages. Not every page there has a link on this page!

Getting started

Name URL Remarks
Main home page https://www.eclipse.org/sw360/ main home page with general info
Project @ Github https://github.com/eclipse/sw360 where the music plays
Developer mailing list sw360-dev@eclipse.org for developers, discussion about developing
Slack Channel https://sw360chat.slack.com/ the main chat spot, everybody is welcome
Slack Channel Invitation Link Sharable join link to join that should bring you in
sw360 developer meeting Meeting Info Everyone is welcome!

Naming Policies for this Wiki

Please start every page with a prefix

  1. User: topics suitable for admins and end users
  2. Deploy: All things about deployment
  3. Dev: All topics for developers
  4. Test: Also a topic for developers, but also around testing

Using sw360

For using the sw360 as a user, please see the following basic workflows:

General

Special

  1. Find information about the role and access model
  2. If you are interested in the concept about moderation requests, read the documentation here.
  3. Explaining enumerations used in SW360

Deploying sw360

For the deployment of the SW360, it is about deploying a Liferay server application. Please understand, that apart from trying sw360 for a short while, for deployments of SW360 in your organisation you will need knowledge about how to deploy Java server applications. Regardless of the deployment approach the following main elements need to be considered:

  • A Liferay Community Edition bundeled with Tomcat.
  • Install CouchDB (this is where SW360 stores all the source code, SPDX files and metadata), depending on your platform, there are a number of ways to use CouchDB. Currently, we tested with CouchDB 2.1.2, other versions of CouchDB may work as well.
  • For productive deployments, you do not want to go with the (Hypersonic) DB bundled with Tomcat, but install some normal DB server. We use PostgreSQL. The relation DB server is used by Liferay and should be thus compatible to it.
  • For searches, consider CouchDB Lucene CouchDb Lucene.
  • There is a number of additional "prerequisites" for SW360, more detailed in the Vagrant deployment setup.

In order to install sw360, you can choose between the following ways:

  • Use the Vagrant-based installation. Please refer to the sw360 vagrant project and the included Readme file. Basic prerequisites are
    • VirtualBox
    • Vagrant and some vagrant plugins
    • Presumeably a git client
  • You could install the sw360portal project natively on the machine. This will require more work in order to install the prerequisites. The above mentioned vagrant project documents very precisely what to do in order to install the sw360portal.
  • Checkout the docker suite sw360chores and generate a pre-built container where you can deploy the *.war files of sw360portal (both frontend and backend). Important this is work in progress now and likely not working out of the box.

Frequently Experienced Problems

  1. The most experienced confusion is about the Liferay setup user: the setup user cannot be used to work with the sw360 because the setup user is missing an organisation assignment. For every user an organisation assignment is required for sw360 to work properly. Unfortunately, you cannot assign a liferay setup user to an organisation. So you do need to import users or create users with organisation.

  2. Currently, you need Java 11, we test it with OpenJDK. Newer or older versions may work, but currently, reports tell that for example Java 8 does not work.

  3. Thrift: for compiling the software you need to install Apache Thrift (a command line tool). We test with version 0.13.

General Deployment Guides

Special Deployment Guides

General Topcis

Special Topics

After installing sw360 more topics may include:

  1. Special Coverage of Country Codes, when countries are displayed, then it uses country codes in the DB
  2. How to export data and import it to a new instance
  3. How to migrate an existing sw360portal to a new instance
  4. Using costco to modify the couchdb database

Developing sw360

The sw360 is Java-based application consisting of two main parts:

  1. A Liferay/based front end application that allows users to work with sw360
  2. A Java-based servlet infrastructure Thrift interfaces that allows the Liferay part and other applications to manage and store data
  3. In the backend, couchdb is used for storing project, component, release and license information as well as attachments.

Submitting Issues

Please report issues to the issue tracker, but please keep also in mind that someone else has to read them! Issues should include:

  • What you intended to do?
  • What did you observe?
  • Why do you think it is wrong?
  • Screenshots of what you have observed presumably gone wrong or link to pages were another person can follow
  • Version where you have observed this.
  • Common written English and use of line breaks!!! Use the preview function!

Please refer to the following pages for writing issues:

Contribution Workflow

As basic introduction, the dev ops works as following:

  1. We are issue-based, please do not hesitate to create issues - also for questions (and set the issue tag)
  2. The issues are organised by milestones which do not represent releases anymore. Milestone are meant to be useful packages of work done
  3. Contributions are made through pull requests
  4. We do conversations directly on issues and pull requests

More topics regarding "how" to develop:

  1. Definition of done and code style
  2. Creating a sw360 release
  3. Brief notes on the jgiven testing
  4. For help with problems, you might want to check that

Architecture

sw360 is a server application using Java servlets. It did some faint steps towards micro services (ie. one maintaining licenses, another for vulnerabilities), the front end is a portlet applications using good old JSPs.

  1. Introduction and Scope
  2. High Level View
  3. Architecture Topics

General

  1. How to write a new portlet
  2. Adding a new backend service
  3. Changing the data model
  4. REST API overview
  5. Migrating to Javascript modules

Special

  1. Filtering in portlets
  2. The FOSSology integration
  3. How moderation requests work
  4. Roles and access rights
  5. Attachment Types Description
  6. Our ideas of Google-Summer-of-Code 2019
  7. How Friendly URLs work with the Liferay Portlets

Testing sw360

Generally, all modules have unit tests and these are executed (including deployment of couchdb) at CI times. In addtion, to test the front end, there are defined integration test cases for a manual check, if the sw360 is working properly in general:

  1. Test Cases: Components Functionality
  2. Test Cases: Licenses Functionality
  3. Test Cases: Moderations Functionality
  4. Test Cases: Projects Functionality
Clone this wiki locally