Issue Fixing WSO2 Identity Server (Part 1) : Setting up the Environment
Since WSO2 Identity Server is an Open Source platform, a large number of git issues will be raised by Users as well as Employees of WSO2. Suppose you have been assigned to an issue. There will be many repositories in GitHub regarding WSO2 IS. You can select a few of the repositories in which you assume the issue will is in. But there is a Procedure you have to follow while setting up the repositories which need to work collaboratively. Let’s look at it more deeply. (explanations for each of the steps is given)
Suppose you have been assigned to an issue related to API requests. So you have to choose some repositories in which you assume the issue should be. Let’s suppose those repositories were Identity-API-dispatcher, Identity-framework, and Identity-API-server.
- Fork all those repositories and product-is repository to your GitHub account.
Creating a “fork” will produce a personal copy of someone else’s project. This will act as a sort of bridge between the original repository and your personal copy. Now you are going to work on your forked repository.
The reason for forking the product-is repo is because it is the main repo which ties up all the other repo to build the WSO2 Identity Server. (product-IS will not have any source code in it)
2. Clone all the forked repo to your local machine in an existing folder
Copy the link shown and clone in your existing repository using the following command. Likewise, clone all the repositories to an existing folder.
git clone https://github.com/nisho06/identity-api-server.git3. Add respective upstream branches for all the forked repositories.
git remote add upstream https://github.com/wso2/identity-api-server.gitNote that you should have to add the URL of the original repository from which you have forked.
The reason for adding the upstream branch -> whenever you are working on a repository, many others also will be working at the same repo and made pull requests and merged with the original repo. So the local repo that you have cloned will not replicate the merged changes on the original repo. After you have added the upstream branch, whenever you need to merge the original repo changes to the local repo, you can pull the upstream branch to your master branch that you are working on using the following git command.
git pull upstream master4. Open the repositories using any java IDE (Intellij IDEA is preferable)
Before opening the repositories, make sure that you have installed the latest version of the maven. Then open the projects using IntelliJ IDEA. Check the pom.xml file in the opened local repo. If you could be able to see an “m” before it, it is confirmed that the project is opened as a maven project. If not refer to this documentation to open as a maven project.
5. Check the dependencies between the Repositories and change the versions according to it
POM -> A Project Object Model or POM is the fundamental unit of work in Maven. It is an XML file that contains information about the project and configuration details used by Maven to build the project.
Some of the configurations that can be specified in the POM are the project dependencies, the plugins or goals that can be executed, the build profiles, and so on. Other information such as the project version, description, developers, mailing lists, and such can also be specified.
Most projects depend on others to build and run correctly. Maven manages this dependency list and downloads and links the dependencies on the compilation (building projects ). All the downloaded dependencies will be stored in the Maven local repository (m2).
Windows: C:\Users\<User_Name>\.m2Linux: /home/<User_Name>/.m2Mac: /Users/<user_name>/.m2
Whenever a project/repository/component is being built, first it will search the particular mentioned version of the dependencies in the above-mentioned m2 local repository. If that dependency was not there in the local repository, it will be downloaded from a remote repository (Remote repository for WSO2 products is WSO2 Nexus Repository Manager). You can view that in the pom.xml file which is configured.
As I said before, each project may depend on others. So that according to our supposed case, the dependency graph will be as follows.
For example, Identity-API-dispatcher is dependent on Identity-API-server. Like wise, the rest will be considered.
Here, the version of our cloned Identity-API-server is 1.0.179-SNAPSHOT.
Now, Copy the groupID of the identity-API-server repo and search the group name in the pom file of Identity-API-dispatcher to see whether Identity-API-dispatcher is dependent on Identity-API-server or not. (org.wso2.carbon.identity.server.api).
You could see the dependencies of identity-API-server in Identity-API-dispatcher. From that, you can conclude that Identity-API-dispatcher is dependent on Identity-API-server. Likewise, you have to check each pair whether they have dependencies between them or not. ( That dependency graph I mentioned earlier was drawn by checking each pair. )
Then press CTRL and click the dependency version which is mentioned as a variable ${identity.server.api.version}. This will lead you to the version of the identity-API-server dependency that is mentioned in Identity-API-dispatcher.
Here it is mentioned as 1.0.176. But our cloned local identity-API-server version was 1.0.179-SNAPSHOT. To make our cloned local Identity-API-dispatcher to be depended on cloned local Identity-API-server, we should have to change the version from 1.0.176 to 1.0.179-SNAPSHOT. Likewise, we should have to consider each dependency and change the version according to the cloned versions of the repositories.
6. Build the projects using maven
Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project’s build, reporting, and documentation from a central piece of information.
Maven allows the developer to automate the process of the creation of the initial folder structure for the Java application, performing the compilation, testing, packaging, and deployment of the final product.
While you are building a maven project, it will read the pom file and resolves the dependencies mentioned.
mvn clean install -eThis is the command for maven build. Here
- mvn -> maven
- clean -> Clean will remove the target folder in the particular project (you can see in your local file structure of the repository)
- install -> it will compile the project and package it into a .jar/.war file and put it into the target directory (you can see in your local file structure of the repository). The main advantage of install is, while putting the .jar/.war file into the target directory, it will also put the extracted file into the maven local repository (.m2 repo)
- -e -> This will display the errors if there were any while building the project.
Here while you are building repositories, you don’t have to run the test cases. Because the remote repository in which you have cloned should have passed all the test cases before someone gave access to be merged.
So that you can build each repositories by skipping the test cases. Because building with test cases will consume time and unnecessary in this instance.
mvn clean install -Dmaven.test.skip=true -e- Dmaven.test.skip=true -> skipping the test cases
As I said earlier, the install command in the build leads to make a copy extracted built .jar file into the maven local repository. But when you are building a project/repo, it will search for the dependencies in the local .m2 repo, and if it is not there only it will download the dependencies from the maven remote repository.
Suppose you have built Identity-API-server. Now the built identity-API-server of the particular version (1.0.179-SNAPSHOT) will be in the .m2 repository.
As I said earlier you have changed the version of the Identity-API-server dependency in Identity-API-dispatcher. Now, when you are building the identity-API-dispatcher repository, it will search the identity-API-server dependency (1.0.179-SNAPSHOT) in the .m2 repository. It is there in the repository. So that, identity-rest-dispatcher will be built using the identity-API-server we have built earlier. That’s how we make connections between the local repositories.
Likewise, you have to build all the repositories in the following order.
- Identity-framework
- Identity-API-server
- Identity-API-dispatcher
- Product-is
The reason for the above order is, we have to build the repositories from the independent one to product-is. You could understand the reason for this order of building from the above explanation of the .m2 repository. Then only the previously built can be used as a dependency to the next.
Finally, after you built Product-is, go to the mentioned folder (product-is/modules/distribution/target) and extract the built .zip file to any of the folder you want the .zip file to be extracted. ( Do not extract the src.zip file )
Open the bin folder of the extracted folder in the terminal and start the server as usual.
sh wso2server.shNow we have built the server by connecting with the local cloned repositories. So now you can check whether you can reproduce the issue (check whether the issue is still there) in the server you have built.
Thats all for this article regarding setting up the environment for issue fixing. Hope you got everything.
If you have any doubts regarding this medium article, please feel free to comment.
In my next medium article, let’s see how to debug issues using IntelliJ debugging.
