About this Guide

This guide contains basic instructions on how to use the ToolsCloud development environment. It is not intended to be an exhaustive guide for each tool available. You can find more comprehensive documentation at each tool’s official website – links can be found here.

Getting started

When you purchase a ToolsCloud environment subscription, you’ll receive:

  1. A URL to access your ToolsCloud environment with the following format: <COMPANY>.toolscloud.net . This is your access URL.
  2. A user name and a password to access the ToolsCloud Help Desk tool. You should use the Help Desk to report problems with your ToolsCloud environment.
  3. A initial “toolscloud” user and a password that you can use to start using your environment. Note that you should change the this user password as soon as you access your environment for the first time.

Please, make sure you have the information above to start configuring your environment.

All tools available in the ToolsCloud environment will be accessed using the access URL provided to you. The tools available and their URLs are:

  1. <COMPANY>.toolscloud.net/users : the phpldapadmin tool, used to manage the users that will have access to the development environment.
  2. <COMPANY>.toolscloud.net/redmine : he Redmine tool, an Issue Tracker.
  3. <COMPANY>.toolscloud.net/repos : the Subversion source code manager tool;
  4. <COMPANY>.toolscloud.net/git : the GIT source code manager tool;
  5. <COMPANY>.toolscloud.net/hudson : the Hudson Continuous Integration tool;
  6. <COMPANY>.toolscloud.net/nexus : the Maven artifact repository Nexus;
  7. <COMPANY>.toolscloud.net/toolscloud : the ToolsCloud Manager tool, used to manage your development environment;
  8. <COMPANY>.toolscloud.net : your access URL. It has links to all the other tools available.
  9. ftp://<USER>@<COMPANY>.toolscloud.net: address to access the FTP server of your ToolsCloud environment.

In order to start using your environment, you have to do the initial setup. First, go to https://<COMPANY>.toolscloud.net/toolscloud/manager and provide the requested data. When you’re finished, click in the “Generate Configuration” button. The configuration will only be applied when you restart the application servers. To do that, in the next screen, restart Apache and JBoss application servers.

How to create and modify the ToolsCloud users

The users that can access the ToolsCloud environment are managed by the LDAP server provided. You can access your environment LDAP server using the phpldapadmin tool. This tool is available in the URL: <COMPANY>.toolscloud.net/users.

How to create a new user:

  1. Use the “toolscloud” user and the password your received to log in the phpldapadmin tool for the first time.
  2. Click on “Create New” in the tree path under “ou=users”, as shown in the figure 1.Figure 1: Creating a new user
  3. In the next screen, choose the “User Account” option
  4. Provide the new user data, as shown in the figure 2Figure 2: New user data
  5. Note that the “Common Name” field has the user name that will be used by the user to log in all the tools. Try to choose a user name with no spaces or special characters, making it easier to use it as a log in user name. You can define a standard like firstName.lastName, for example, or only the person’s first name, or any other convention you choose.
  6. In the GID Number field, choose the “accounts” option. This will automatically generate the user GID number.
  7. Click on “create object”
  8. In the next screem, click on “Insert new attribute”
  9. In the next form, choose “mail” and provide the user email. Then click on “Insert”

Note that the users can log themselves in the phpldapadmin tool to change their passwords, but they can’t change other users’s passwords, unless they have the administrator role.

How a user can change their own data:

  1. First, the user should log in the phpldapadmin tool using as “Login DN” the following: “cn=<username>,ou=users,dc=toolscloud,dc=com” . Where <username> is the value you informed in the “Common Name” field, as shown in figure 3.Figure 3: A user logging in
  2. Fiend the user registry in the tree under “ou=users” and click o in the registry, as shown in the figure 4Figure 4: Selecting a user on LDAP
  3. Modify the desired data and click on “Save Changes”
  4. In the next screen, click on “Confirm”

HOW to turn a user in a LDAP Administrator:

Users that are LDAP administrators can create new users, modify other users data and give access permissions to them. LDAP administrator users are the ones that are members of the “ldap-admin” group. If you want to make a user a LDAP administrator, to the following:

  1. Log in the phpldapadmin tool as a LDAP administator. If you never created a LDAP administrator user before, you can use the “toolscloud” user that you received with your ToolsCloud environment.
  2. Select the “ldap-admin” group in the tree under “ou=groups”
  3. Check the users you want to include in the ldap-admin group
  4. Click on “Save Changes”

How to change A User data:

  1. Log in the phpldapadmin with a LDAP administrator user
  2. Select the user you want to modify under the “ou=users” subtree
  3. Change the data and click on “Save Changes”
  4. In the next screen, click on “Confirm”

How to give access to the Hudson tool

  1. Log in the phpldapadmin tool with a LDAP administrator user
  2. Under the subtree ou=groups/ou=hudson-groups you’ll see two subgroups: hudson-admin and hudson-users, as shown in figure 5. Members of the hudson-users group can use Hudson, start builds and more. Only members of the hudson-admin group can manage Hudson. It is possible to create new configurations and groups for Hudson. See the section How to create new access groups for Hudson if you want to create advanced configurations.Figure 5: Groups that can be used to control access to Hudson
  3. Select the group that you want to add users to it
  4. Check the users that will be part of this group and click on “Save Changes”

How to give access to the Nexus tool

  1. Log in the phpldapadmin tool with a LDAP administrator user
  2. Go to the ou=groups/ou-nexus-groups subtree. You’ll see several subgroups under it, as shown in the figure 6. Each of these subgroups is linked to a role in Nexus. You can see which each role means by looking how each role is configured in Nexus. Note that these groups represent the roles available by default on Nexus, but you can create new roles on Nexus and add the corresponding group on LDAP.Figure 6: Groups that control the access to Nexus
  3. Select the subgroup linked to the role that you want to give to a user and add the user to it. Note that the same user can be part of more than one group.
  4. Click on “Save Changes

How to give access to a Subversion repository

  1. Log in the phpldapadmin tool with a LDAP administrator user
  2. Under the subtree ou=groups/ou=svn-groups you’ll see a subgroup named “employees”, as shown in figure 7. By default, no users or groups can read or write any project in the Subversion repository, but you can use the “employees” group to create access rules to Subversion. If you want to add a user to this group, select the group, check the users that will be part of the group and click on “Save Changes”Figure 7: Groups that control access to Subversion

You can also restrict the access to a particular path in the Subversion repository by creating new subgroups. For example, you could create a group named “projectX” and this group would contain only the users that can access the path <COMPANY>.toolscloud.net/repos/projectx . See the Configuring access to Subversion section in the ToolsCloud Manager guide to find out how to make group based configurations.

How to give access to a git repository

  1. Log in the phpldapadmin tool with a LDAP administrator user
  2. Under the subtree ou=groups/ou=git-groups you’ll see a subgroup named “employees”, as shown in figure 8. If you want to add a user to this group, select the group, check the users that will be part of the group and click on “Save Changes”. By default, no group has read or write permissions on the initial GIT repository, named repository.git. If you want to give access to this repository, see the Configuring access to GIT section in the ToolsCloud Manager guide.Figure 8: Groups that control access to GIT

You can also restrict the access to a particular path in the GIT repository by creating new subgroups. For example, you could create a group named “projectX” and this group would contain only the users that can access the path <COMPANY>.toolscloud.net/git/projectx.git . See theConfiguring access to GIT section in the ToolsCloud Manager guide to find out how to make group based configurations.

How to give access to the FTP server

  1. Log in the phpldapadmin tool with a LDAP administrator user
  2. Under the subtree ou=groups/ou=ftp-groups you’ll see a subgroup named “employees”, as shown in figure 8. If you want to add a user to this group, select the group, check the users that will be part of the group and click on “Save Changes”.. Figure 9: Groups that control access to the FTP server

Members of the employees group have read and write permission to the FTP folders available on your ToolsCloud environment.

How to use Subversion

Your ToolsCloud environment has a pre-configured repository that can be accessed using the <COMPANY>.toolscloud.net/repos URL. By default, all users in the “employees” group in the ou=groups/ou-svn-groups subtree have read and write permission in this repository. See how to add new users to this group here. You can alto restrict the access by Subversion path, creating new subgroups. For example, you could create a “projectX” group with users that could only access the path <COMPANY>.toolscloud.net/repos/projetox . See  Configuring access to Subversion in the ToolsCloud Manager User Guide to learn how to create configurations by group.

You can visualize your Subversion repository content in a web browser using the URL <COMPANY>.toolscloud.net/repos . Note that the access via web browser has the same access restrictions applied to Subversion clients. Therefore, onlu users that have read access to the “/” path will be able to access the  <COMPANY>.toolscloud.net/repos URL . For example, if a user can only access the path “/projectx”, he will be able to access only this URL <EMPRESA>.toolscloud.net/repos/projetox.

You can use graphic tools like TortoiseSVN or SmartSVN to access the Subversion repository, or command line commands, if you have a Subversion client installed in your computer.

See how to do the most common Subversion operations using command line:

Create a new project with the standard structure (trunk, tags and branches):

svn mkdir https://<COMPANY>.toolscloud.net/repos/<PROJECT_NAME> -m "Initial Commit"
svn mkdir https://<COMPANY>.toolscloud.net/repos/<PROJECT_NAME>/trunk -m "Initial Commit"
svn mkdir https://<COMPANY>.toolscloud.net/repos/<PROJECT_NAME>/tags -m "Initial Commit"
svn mkdir https://<COMPANY>.toolscloud.net/repos/<PROJECT_NAME>/branches -m "Initial Commit"

Import a project source code to Subversion, after the project is created:

svn import <PROJECT_NAME> https://<COMPANY>.toolscloud.net/repos/<PROJECT_NAME>/trunk/ -m "Initial Commit"

To check if it worked, open the following URL on your browser: https://<COMPANY>.toolscloud.net/repos/<PROJECT_NAME>/trunk/

Checking out a project, i.e., retrieve the source code from the server to your computer:

svn co https://<COMPANY>.toolscloud.net/repos/<PROJECT_NAME>/trunk <PROJECT_NAME>

To commit code, i. e., send modified code to the server:

svn commit -m "Modifying code to test"

Updating the code, i.e., retrieving new version of the code from the server:

svn update

Seeing the change log:

svn log

If you already have a Subversion repository, you can import all its history to your new ToolsCloud repository. Note that your ToolsCloud repository should be empty in order to be able to do that.

Use the svnsync tool to import the history from another Subversion repository. This tool is usually installed with your Subversion client. To use this tool, run the following command in an empty folder:

svnsync init --username=<user-name> --password=<user-password> https://<COMPANY>.toolscloud.net/repos https://<SOURCE_REPOSITORY>

svnsync sync https://<COMPANY>.toolscloud.net/repos

When you run this command, all source repository history will be imported to your ToolsCloud repository. Note that if your source repository is large, this operation can take a lot of time.

You can stop the importing process and restart it later. However, if you stop the process, when you run the svnsync sync command again, you will probably see the following error message: “Failed to get lock on destination repos”. If this happens, remove the repository lock, by running this command:

svn propdel svn:sync-lock --revprop -r 0  https://<COMPANY>.toolscloud.net/repos

After that, you can run “svnsync sync” again and restart the process

How to use GIT

Your ToolsCloud environment has a pre-configured repository that can be accessed using the URL  <COMPANY>.toolscloud.net/git/repository.git . By default, no user has read or write access to this repository. Groups in the ou-groups/git-groups LDAP subtree should be used to configure who can have access to a repository.  Your ToolsCloud environment has a pre-configured group called “employees”. You can add users to this group and then use the ToolsCloud Manager tool to give the group permission to access GIT repositories.  You can also restrict the access to a specific path by creating new groups. For example, you could create a “projectX” group that would have as members only the users that can access the path <COMPANY>.toolscloud.net/git/repository.git/projectx. See Configuring access to GIT in the ToolsCloud Manager user guide to learn how to create configurations by group.

You can browse and see your GIT repository using your web browser. Just access the URL <COMPANY>.toolscloud.net/git . Note that access to the repository via web browser is restrict by the same access rules applied to any GIT client. Therefore, only users that have permission to access the whole repository, i.e., the “/” path, will be able to access the URL <COMPANY>.toolscloud.net/git/ . For example, if a user has permission to access only the “/repository.git/projectx”, he will be only allowed to access the URL <COMPANY>.toolscloud.net/git/repository.git/projectx.

You can also create new GIT repositories, if you want. To learn how to do that, see How to create new GIT repositories, in the ToolsCloud Manager User Guide.

You can access your GIT repository either using a graphic tool like TortoiseGIT or SmartGIT, or using command like, if you have a GIT client installed in your computer.

See how to use command line to execute some common GIT operations:

How to clone a remote repository:

git clone https://<USER>@<COMPANY>.toolscloud.net/git/repository.git

How to add files to GIT:

git add .

This command adds all files in the current directory.

How to commit all local changes:

git commit -a

How to see all the local changes:

git diff

How to see the files status (what files were modified, etc):

git status

How to see the log of what was done:

git log

How to see what branches are available in the repository:

git branch

How to create a branch in a local repository:

git branch <BRANCH NAME>

Check the list of branches again. Note that the branch with an asterisk is where you are working on.

If you want to start working on another branch:

git checkout <BRANCH NAME>

To go back to the master branch:

git checkout master

To merge your changes in the master

git merge <BRANCH NAME>

To send all your changes to the remote repository:

git push --all

After doing this last command, browse the remote repository and see what happened. Note that each commit has always two users associated to it: the “author” is the one that changed the files and the “committer” is the one that executed the commit command. You can configure who will be the author with this command:

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com

How to use Redmine

You can access the Redmine tool using the URL <COMPANY>.toolscloud.net/redmine .

Redmine can be accessed by any user that registered on your LDAP base. However, the user will only access projects and Redmine content when he/she receives the appropriated access permission.

You should create profiles and permissions to Redmine on Redmine administration interface. However, a LDAP user will exist on Redmine only after he/she logs into Redmine for the first time. Because of that, before you can give access to a user to a particular project, the user has to log into Redmine at least once.

How to transform a user in a Redmine administrator:

  1. Log in Redmine as the LDAP user that will be the administrator. This will make Redmine to retrieve the user data from LDAP and the user will be created on Redmine. Log out from Redmine. Log in to Redmine again, but this time using a user name that is already a Redmine admistrator. If this is a new ToolsCloud environment, the toolscloud user will be the default administrator.
  2. Click on Administration/Users
  3. Find the user that you want to turn on administrator and select it
  4. Check the “Administrator” option and click on “Save”

How to give redmine access to a user:

  1. Make sure the user you want to give access was logged on Redmine at least once. This will make Redmine to retrieve the user’s data from LDAP and create a Redmine user for him. Then, log in to Redmine with an administrator user. If this is a new ToolsCloud environment, the toolscloud user is the initial administrator.
  2. Click on Administration/Groups
  3. If there is already a group with the permissions you want to give to user, simply add the user to that group.
  4. If you prefer, add a new group
  5. In the “Users” tab, select the users that will be part of the group
  6. In the “Projects” tab, select the permissions that you want to give to the members of that group in each project.

How to create a new project:

  1. Click on Administration/Projects/New Project
  2. In the Name field, type the name of the project and in the identifier field, type a lower case project identifier. If you want allow only authorized users to access the project, uncheck the Public option.
  3. Check all available modules. This will make your project to have the features of all Redmine plugins available in the ToolsCloud environment
  4. Go to the Members tab and select who can access the project and what the members can do
  5. In the Versions tab you can create a new version for the project, if you want
  6. In the Repository tab, select Subversion or GIT and configure the project repository, if you want. See how to do this in the next section
  7. Go to the Forum tab and add a new forum for the project, if you want

how to associate git or subversion to redmine:

If there is a GIT or Subversion repository associated to your Redmine tool, you can see on each issue what were files were changed to solve that issue. Here is how to do this:

  1. First, you have to set which the Subverion or GIT repository will be used for your project. If you are using Subversion:
    1. Go to Administration/Projects and select your project
    2. Click on the Repository tab
    3. In the SCM field, select “Subversion”
    4. In the URL field, inform a Subversion URL, like https://<COMPANY>.toolscloud.net/repos/<PROJECT NAME>/trunk . Note that you can associate any path to this URL. In this example, only the trunk path is associated to the project, but it is possible to associate the whole project and its branches. It is also possible to make the path even more specific, like  https://<COMPANY>.toolscloud.net/repos/<PROJECT NAME>/trunk/codebase, for example. Note, however, that the larger the repository, more time will be required to Redmine to collect repository statistics. Because of that, if you have a large repository, try to use more limited paths, so the amount of processed data is not too large.

    If you are using GIT:

    1. In the Administration/Projects select your project
    2. Click on the Repository tab
    3. In the SCM field, select “GIT”
    4. In the Path to .git directory field, put the local disk path to your GIT repository. In the ToolsCloud environment, this path is always /applications/git/<REPOSITORY NAME>. If you are using the default repository, the path will be /applications/git/repository.git .Note, however, that the larger the repository, more time will be required to Redmine to collect repository statistics. Because of that, when using GIT, a good practice is to use several smaller repositories, usually one repository to each project.
  2. When Redmine is integrated to the repository, you can commit changes putting in the commit comment something like this: “IssueID #X – Message”. In this example, X is the issue code. When you have done this, you can go to the issue page on Redmine and you will see your commit associated to it. All GIT or Subversion commits that have IssueID #<Issue Number> in the comments, will be automatically show up in the corresponding issue page on Redmine.

HOW TO USE THE HUDSON TOOL:

You can access your Hudson instance through the URL <COMPANY>.toolscloud.net/hudson .

Hudson can be accessed by users in the hudson-users LDAP group. Users in the hudson-admin LDAP group will be Hudson administrators.

So, to give a user access to Hudson, do this:

  1. Add the user to LDAP using the phpldapadmin tool
  2. In the LDAP tree, select groups/hudson-groups and select the group you want to put the user on (hudson-users or hudson-admin).
  3. Check the users that you want to add to the group and save your changes.

After that, the user can log into Hudson and use it.

The Hudson installation available in the ToolsCloud environment has some pre-installed plugins to give you a better user experience. One of the pre-installed plugins is the one that allows to integrate Hudson with Redmine. Since this is available, when you create a new Hudson task, you can inform what is the corresponding project at Redmine. This will allow you to see the issues associated to each build.

how to create new access groups for Hudson

You can create more complex access rules to Hudson using LDAP groups. If you need other groups besides the hudson-users and hudson-admin groups, you can do this:

  1. In the main Hudson screen, click on “Manage Hudson”
  2. In he next screen, click on “Configure System”.
  3. In the form, look for a section called “Authorization”. You’ll see the ROLE_HUDSON-ADMIN group (corresponding to the hudson-admin LDAP group) and ROLE_HUDSON-USERS (corresponding to the hudson-users group). You can add new groups or change the permissions in the current groups. Note that each new LDAP group should be under the hudson-groups group. Also, note that when you refer to the same group on Hudson, you should concatenate the group name with the “ROLE_” prefix. For example, if you create a LDAP group called “readonly”, the same group on Hudson should be ROLE_READONLY.

How to use the Nexus tool

The Nexus tool can be accessed using the URL <COMPANY>.toolscloud.net/nexus .

In order to have access to Nexus, the LDAP users should be members of one of the groups under the ou=groups/nexus-groups group. Each subgroup will give the user a set of specific permissions, that you can configure on Nexus. See How to give access to the Nexus tool for more information.

When you have all the users with the right permissions, you have to configure your  /.m2/settings.xml file with something similar to this:

<settings xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0           http://maven.apache.org/xsd/settings-1.0.0.xsd">

  <servers>
    <server>
      <id>Releases</id>

      <username><!-- your user name --></username>
      <password><!--  your password --></password>
    </server>
    <server>
      <id>Snapshots</id>

      <username><!-- your user name --></username>
      <password><!-- your password --></password>
    </server>
    <server>
      <id>nexus</id>

      <username><!-- your user name --></username>
      <password><!-- your password --></password>
    </server>
  </servers>
  <mirrors>

    <mirror>
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>https://<COMPANY>.toolscloud.net/nexus/content/groups/public/</url>

    </mirror>
  </mirrors>
<profiles>
 <profile>
           <id>alwaysActiveProfiles</id>
           <repositories>
           <repository>
                <id>central</id>
                <url>http://central</url>
                <releases><enabled>true</enabled></releases>
                <snapshots><enabled>true</enabled></snapshots>
           </repository>
          </repositories>
 <pluginRepositories>
 <pluginRepository>
               <id>central</id>
               <url>http://central</url>
               <releases><enabled>true</enabled></releases>
               <snapshots><enabled>true</enabled></snapshots>
 </pluginRepository>
 </pluginRepositories>
 </profile>
</profiles>

<activeProfiles>
      <activeProfile>alwaysActiveProfiles</activeProfile>
</activeProfiles>
 </settings>

Don’t forget to put your user name and password and the right Nexus URL on the settings.xml file.

If you want to deploy your artifacts to Nexus via maven, you have to configure the distributionManagement section of your project pom.xml with the following:

<distributionManagement>

    <repository>
      <id>Releases</id>
      <name>ToolsCloud Releases Repository</name>
      <url>dav:https://<COMPANY>.toolscloud.net/nexus/content/repositories/releases/</url>

    </repository>
    <snapshotRepository>
      <id>Snapshots</id>
      <name>ToolsCloud Snapshots Repository</name>
      <url>dav:https://<COMPANY>.toolscloud.net/nexus/content/repositories/snapshots/</url>

    </snapshotRepository>
  </distributionManagement>

Make sure to put the right URL for your ToolsCloud environment. Also, when you change your pom.xml, don’t forget to commit your changes on Subversion or GIT, so all the users can have them!

How to use the ToolsCloud Manager tool

The ToolsCloud Manager tool can be accessed through the URL <COMPANY>.toolscloud.net/toolscloud/manager .

To learn how to use the ToolsCloud Manager tool, see the ToolsCloud Manager User Guide.

How to use the FTP server available in your ToolsCloud environment

Your ToolsCloud environment has an FTP server that can be accessed through the following URL: ftp://<USER>@<COMPANY>.toolscloud.net .

Using FTP, you can access and modify some folders in your environment. You can read and write on your Hudson work folders and the .m2 folder, where the Maven repository used by the Hudson tool is stored. You can also create new folders and files.