Adminitrator's Guide

Added by Jura Gorohovsky, last edited by Ekaterina Ivanova on Feb 09, 2010  (view change)
Search
Searching YouTrack 1.x Documentation
Table of Contents

Admin Area Overview

Provided that you have sufficient permissions, you can enter YouTrack Admin area by clicking Administration in the top right corner of YouTrack:

Admin area consists of the following pages:

  • Projects. This is an overview of existing issue tracking projects, with options to create a new project or import an existing project from a JIRA instance:
  • Users. This is a list of registered YouTrack users with filters and a link to user registration page:

    See Administering Users.
  • Groups. This page lists and describes existing user groups, and provides an option to create new groups:
  • Roles. This is a list of roles configured in the current YouTrack instance, with detailed permissions associated with them:

    See Configuring Roles and Assigning Roles to Users.
  • Issue Link Types. This is a list of issue links configured in the current YouTrack instance:

    YouTrack comes with 3 predefined link types but you can configure your own types.
    Link type configuration comes down to wording and whether the link is directed or not.
    For directed links, you should specify two names: an inward name for the object of a link (e.g. "is duplicated by") and an outward name for the subject of a link (e.g. "duplicates").
  • Setup. This page lets you configure license data, base URL of your YouTrack installation, enable guest account and notifications. This is the first page that is displayed after you have installed YouTrack:

    See Initial Setup for further details.
  • Database. This page lets you switch YouTrack database between read-write and read-only states, monitor database performance data, as well as schedule, configure, and retrieve database backups:

    See Administering Database for further details.
  • Text Index. This page lets you configure languages to take account of during text indexing, and provides a button to suspend it:

    Suspending text indexing is useful when a massive amount of documents to index considerably impairs server performance (for example, in peak hours). Another use case is to suspend text indexing for creating a backup right after you have imported a new project.
  • System Info. This page displays server statistics: available, allocated, and used memory, as well as the number of available processors:
  • Statistics. Use this page to view usage statistics for your YouTrack installation. Currently, it only has one tab, Browsers Usage:
  • Entity Browser. This is a simple YouTrack database viewer for troubleshooting purposes. If something goes completely wrong with your YouTrack installation, you might have to report some entity data from this page:
  • JIRA Integration. This page incorporates JIRA integration settings:

    See Importing a Project from JIRA.
  • LDAP Integration. This page helps configure YouTrack to allow users in your company to log in using credentials stored in your directory service:

    See LDAP Integration.
  • OpenID Integration. This page lets you enable any or all of five OpenID providers supported by YouTrack:

    See OpenID Integration.
  • TeamCity Integration. This page helps integrate YouTrack with JetBrains TeamCity for linking issues to VCS commits and automatically filling "Fixed in build" attribute values:

    See TeamCity Integration and/or TeamCity Integration Guide.

Initial Setup

When you run YouTrack for the first time, it requires you to log in. For initial setup, use the default username/password pair: root/root.

Default credentials
For initial setup, use the default username/password pair: root/root.

Once you have logged in, the initial configuration page (base_URL/setUp) opens where you should specify your license data:

If you're using a EAP build, you can find a valid user name and license key at the EAP Build Installation page.
In addition, you can:

  • Enter the base URL of your YouTrack installation so that links to issues in your e-mail/jabber notifications can be constructed properly.
  • Enable guest account in your YouTrack installation (you can start managing guest permissions after you've logged in.)
  • Enable issue status notifications via e-mail and/or Jabber.

When you've finished configuring the initial settings, click Save and enter your password to apply the settings. You will be redirected to the Projects page (see Administering Projects).
You can change these settings later using the Setup page (base_URL/settings).

Notes about 'root' user
Currently, the default root user account cannot be deleted. If you prefer to use another account to administer YouTrack instance, configure new admin account properly, and then ban the root account. For more details about administering user accounts refer to the corresponding section of this guide.

Administering YouTrack Instance

Administering Database

Changing Database Location

YouTrack uses its own in-process database. By default, data files are saved to ${user.home}/teamsysdata directory.
To change this default location, modify database.location parameter in file youtrack-xx.war:/WEB-INF/web.xml:

<web-app>
  <display-name>YouTrack</display-name>
  <servlet>
    <servlet-name>MainServlet</servlet-name>
    <servlet-class>jetbrains.charisma.main.ServletImpl</servlet-class>
    <init-param>
      <param-name>database.location</param-name>
      <param-value>${user.home}/teamsysdata</param-value>
    </init-param>
    ...
  </servlet>
...
</web-app>

Backing Up Database

YouTrack database controls are available by clicking Database in the Admin Area. Specifically, you can back up YouTrack database right away or schedule backups using cron expressions (see cron expression syntax for reference).
There are several things to take note of regarding YouTrack database settings and controls:

  • YouTrack automatically switches database to read-only mode after you have launched database backup.
  • You can't cancel database backup once it has started.
  • Users aren't able to access YouTrack during database backup, so be sure to configure backup schedule wisely.
  • Notifications about database backup status can only be configured for YouTrack application administrators.
  • You don't have to back up your database in order to upgrade to a newer YouTrack build or version - YouTrack will find your database automatically after upgrade.

Administering Projects

YouTrack allows you to create new projects or import existing projects from JIRA.

Creating a New Project

To create a new empty project:

  1. In the Projects page (base_URL/projects), click Create new project.
  2. Enter name, ID, and description for the new project, and select a user as the project lead.

    As a general rule, before creating projects on top of an empty YouTrack installation, it is recommended that you configure roles, groups and users (in this particular order).

  3. Click Create. The project properties page will open at the Assignees tab. You can now proceed with configuring the project.

Importing a Project from JIRA

YouTrack is able to import existing projects from JIRA 3.8-3.13.4. A project is imported along with user accounts that have access to it, and (optionally) roles, groups, and group memberships. See JIRA Integration for details on JIRA Integration features.
To import an existing project from JIRA:

  1. In the Projects page (base_URL/projects), click Import existing project from Jira.
  2. In the Jira Integration page, use provided links to download a plug-in for JIRA that enables importing issues to YouTrack. Get one of two available YouTrack plug-ins depending on your JIRA version:
    • YouTrack plug-in for JIRA 3.8-3.9.3 (available at base_URL/_classpath/jira-plugin/jetbrains-charisma-rpc-plugin-3.8.1-3.jar)
    • YouTrack plug-in for JIRA 3.10-3.13.4 (available at base_URL/_classpath/jira-plugin/jetbrains-charisma-rpc-plugin-3.10-3.jar)
  3. Install the appropriate YouTrack plug-in in your JIRA instance by following guidelines for "Version 1" plug-ins in Managing JIRA Plugins.
  4. Make sure that remote API is enabled in JIRA and the YouTrack plug-in has appeared in the list of JIRA plug-ins as "Charisma JIRA plugin".
  5. Getting back to YouTrack, click Enable Jira Integration.
  6. Specify JIRA base URL, your JIRA credentials (note that you must have administrative privileges in order to import projects), a project to import, and choose issue types within the selected project:
  7. To import groups, roles, and group memberships, select Import Security Settings.
  8. Click Import Project.

    When you re-import a previously imported project, YouTrack only processes issues that have been added or changed since.

Configuring a Project

To configure a project:

  1. In the Projects page, click the name of a project that you want to manage.
  2. In the project-specific page (base_URL/editProject/project_ID), use the following five tabs to modify various project settings:
    • Main. General project settings that are usually configured on project creation, including Name, ID, Project lead, and Description.
    • Assignees. Users that can act as assignees within the project.
      You can add assignees as individual users (click Add individual assignee), groups (click Add/remove groups), or both.
      The Full assignees list table shows all users who act as assignees in the current project by virtue of group membership or per-user configuration. The Assigned by column lets you know how exactly a particular user has become an assignee in the current project:
    • Subsystems. Using this tab, you can:
      • Add new subsystems to the project.
      • Choose default assignees for different subsystems (any new unassigned issues within a subsystem are automatically assigned to its default assignee.)
      • Set a default subsystem (the subsystem that YouTrack suggests by default when you create new issues in the project.)

        Subsystems are generally used to differentiate between large, consistent project components (such as "Notifications" in YouTrack's own issue tracking project.) However, in many cases tags are just enough to group a set of similar issues. Unlike subsystems, tags can be created by users themselves (provided they have sufficient permissions).

    • Versions. Using this tab, you can create project versions, set release dates for them, mark them as released (you can reference released versions in "affected version" attribute) or archived (you can search for issues related to archived versions but you can't reference archived versions in issue attributes):
    • Builds. Using this tab, you can set build names/numbers and build assembly dates. If TeamCity integration is configured, the list of successfully assembled builds is automatically generated in this tab:
  3. Click Save to save project settings.

Administering User Access

We suggest that you configure user access in the following order:

  1. Create new roles or configure predefined roles.
  2. Create new groups or configure predefined groups.
  3. Assign roles to groups on a per-project basis.
  4. Configure group membership for YouTrack users.

Configuring Roles

A role in YouTrack is a set of permissions. Roles are applied to groups on a per-project basis (within specified projects).
YouTrack is bundled with four predefined roles: Admin, Developer, Reporter, and Observer.

The following table provides an overview of the predefined roles:

Predefined role Permissions
Admin All permissions included
Developer View existing issues; create, modify, assign, link, and delete issues
Add attachments to issues and delete them
Create comments
View and modify own user profile
Create, modify, and delete tags or saved searches
Mark issues as watched and view lists of other users who are watching issues
Vote for issues and view lists of other users who have voted for issues
Reporter Report new and view existing issues
Read public comments; create, modify and delete own comments
View and modify own user profile
Create, modify, and delete tags or saved searches
Observer View public issues
Read public comments

You can edit these predefined roles and/or create new roles.
The following procedure describes creating a new role. To edit an existing role, click its entry in the Roles page.

To create a new role:

  1. In the Admin Area, click Roles.
  2. Click Create new role.
  3. In the role editing page, enter a name and (optionally) description for the new role.
  4. Assign permissions listed and described in the role editing page.
  5. Click Create.

Once you have created and/or configured necessary roles, create or configure user groups, and assign roles to them on a per-project basis.

Configuring Groups

Creating a Group

The following procedure describes creating a new group. To edit an existing group, click its entry in the Groups page.
To create a new group:

  1. In the Admin Area, click Groups.
  2. Click Create new group.
  3. In the group editing page, enter a name and (optionally) description for the new group.
  4. Select Auto Join to automatically add any new registered users to this group.
  5. Click Create.

Once you have created necessary groups, start assigning roles to them.

Assigning Roles to a Group

To assign a role to a group:

  1. In the Admin Area, click Groups.
  2. In the Name column, click the name of a group that you want to assign roles to.
  3. In the group editing page, click Roles.
  4. In the Roles tab, click Assign role. The Assign Role dialog box opens.
  5. In the Role drop-down list, choose a role to assign.
  6. In the Projects combo box, select one or several projects to apply the selected role:
  7. Click OK.

When you have assigned roles to a group, the Permissions View tab in group properties appears. It shows all permissions assigned to the current group via different roles:

Once you have prepared user groups with properly assigned roles, start adding users into your groups.

Administering Users

Creating User Accounts

In YouTrack, users are expected to create their user accounts themselves.
If for some reason you need to create accounts on behalf of users, you can do it using the regular user registration page at base_URL/registerUserForm. For your convenience, there's a link to this page just above the list of users in the Admin Area:

Whichever user registration procedure you choose, you need to create and/or configure a group that every new user will join, assigning it adequate permissions. See Assigning Roles to a Group for details.

Importing User Accounts from JIRA

User accounts are imported from JIRA along with projects. See JIRA Integration for details.

Adding Users to Groups

You can add a user to a group from either the Groups page or the Users page.
To add a user to a group from the Groups page:

  1. In the Admin Area, click Groups.
  2. Choose a group from the list of groups, and click Add User.
  3. In the Select User dialog box, select a user:
  4. Click OK.

To add a user to a group from the Users page:

  1. In the Admin Area, click Users.
  2. Find a user entry using filters in the Filter area.
  3. In the list of found users, locate a user that you want to add to a group.
  4. Click Groups for the user entry in the list of found users. This opens the administrative part of the user profile at the User Groups tab.
  5. Click Add to groups / Remove from groups.
  6. In the Select Groups dialog box, select one or several groups to add the user to:
  7. Click OK.

Once you have added the user to one or several groups, click Permissions View for the list of specific permissions that the user is granted via group memberships or own roles.

Excluding Users from Groups

Excluding a user from a group should be done via user properties as opposed to group properties.
To exclude a user from a group:

  1. In the Admin Area, click Users.
  2. Find a user entry using filters in the Filter area.
  3. In the list of found users, locate a user that you want to exclude from a group.
  4. Click Groups for the user entry in the list of found users.
  5. In the User Groups tab, click Unassign for a group that you want to exclude the user from.

Assigning Roles to Users

In addition to granting permissions via groups, you can assign roles to users individually.
To assign a role to a user:

  1. In the Admin Area, click Users.
  2. Find a user entry using filters in the Filter area.
  3. In the list of found users, locate a user that you want to assign a role to.
  4. Click Roles for the user entry in the list of found users. This opens the administrative part of the user profile at the User Own Roles tab.
  5. Click Assign role.
  6. In the Assign Role dialog box, choose a role to assign to the user:
  7. Select one or several projects where you want to apply the role.
  8. Click OK.

Open the Permissions View tab for the list of specific permissions that the user is granted via his/her own roles or group memberships.

Miscellaneous

You can delete, merge, or ban user accounts, all from the list of users in the Users page.

To merge two user accounts:

  1. In the Users page, locate a user account that you want to merge with another user account.
  2. Click Merge for the user entry in the list of found users.
  3. In the Select User dialog box, select a user account to merge with:

    Note that if you're merging a less privileged user account with a more privileged user account, the resulting user account gets the more advanced permissions.
  4. Click OK.

As a result of merging, any roles, group memberships, and assigned issues are transferred to the surviving user account.

To ban a user account:

  1. In the Users page, locate a user account that you want to ban.
  2. Click Ban for the user entry in the list of found users. The user account is banned immediately.

You can unban the user account at any time by clicking Unban in the list of users.

To delete a user account:

  1. In the Users page, locate a user account that you want to delete.
  2. Click Delete for the user entry in the list of found users.
  3. Click OK in the confirmation dialog box.

Integrating YouTrack with External Tools

TeamCity Integration

You can integrate YouTrack with your JetBrains TeamCity 5.0+ installation:

TeamCity integration brings two advantages:

  1. TeamCity adds links from issue IDs referenced in VCS commits to actual issues in YouTrack, letting you navigate between commits and issues, and view associated changes from any issue.
  2. TeamCity automatically puts correct build numbers to "fixed in build" attributes of your issues after these builds have been assembled.

For more information and specific TeamCity integration guidelines, see TeamCity Integration Guide.

JIRA Integration

Integrating YouTrack with JIRA lets you execute three tasks:

  • Import existing projects from JIRA, along with roles, users, groups, and group memberships.
  • Update previously imported projects to account for changes made in JIRA (for example, new issues and comments that have appeared in the JIRA project since last import to YouTrack.)
  • Enable users to log into YouTrack using their JIRA credentials.

For guidelines on importing projects from JIRA, see Importing Project from JIRA.
Updating previously imported projects is basically done the same way that you import JIRA projects for the first time.
Users are able to log in with their JIRA credentials as soon as you have completed importing a project from JIRA. That's because, provided that you have selected Import security settings during import, YouTrack also imports all groups and roles applicable for the project being imported.

LDAP Integration

LDAP integration lets you use user credentials stored in your directory service to log into YouTrack:

To enable LDAP integration:

  1. In the LDAP Integration tab, click Enable LDAP Integration.
  2. Enter the URL of your LDAP server.
  3. To make sure that the connection with your LDAP server works:
    1. Click Test connection.
    2. In the Test LDAP Login dialog box, enter a pair of user credentials stored in your directory service:
      • domain\username in the Login field.
      • password in the Password field.
    3. Click Test Login.
    4. If an error message if displayed, check your user credentials and/or server URL.
    5. Click Done to close the Test LDAP Login dialog box.

OpenID Integration

YouTrack lets you enable authentication through any or all of five supported OpenID providers: Google, Yahoo, America Online, LiveJournal, and BlogSpot.
To enable OpenID authentication:

  1. In the Admin Area, click OpenID Integration.
  2. In the OpenID Integration page, select Enable OpenID Integration.
  3. Select OpenID providers that you want to enable:

That's all! From now on, your users are able to log in with their OpenID credentials from base_URL/loginForm:

Configuring Additional OpenID Providers

YouTrack supports four OpenID providers out of the box but you can configure additional providers.
However, any provider that you add must support AX (attribute exchange) fetch requests and return the following attributes:

To configure an additional OpenID provider:

  1. Add a new entry to the list of bean elements in [YouTrack classpath]\jetbrains\charisma\openid\persistence\OpenIdProvidersContainer.xml.
  2. In the added bean element, add four properties:
    • id: Unique integer identifier of your OpenID provider. Default providers are assigned IDs from 0 to 3.
    • v2: Boolean value indicating whether your provider supports OpenID 2.0: assign "true" if it does support OpenID 2.0, otherwise "false".
    • iconClassPathUri: Path to OpenID provider logo within YouTrack classpath (\webapps\youtrack\WEB-INF\classes in Apache Tomcat.) Don't forget to actually add a logo image in addition to referencing it in bean properties. Use 48*48 image files for OpenID providers supporting OpenID 2.0, and 22*22 files for other providers.
    • providerUri: OpenID provider service URL.

The following listing shows how one of default OpenID providers is configured in OpenIdProvidersContainer.xml:

<beans>
  <bean id="openIdProvidersContainer" class="jetbrains.charisma.openid.persistence.OpenIdProvidersContainer">
    <property name="providers">
      <list>
        <bean class="jetbrains.charisma.openid.persistence.OpenIdProvider">
          <property name="id">
            <!-- Integer OpenID provider ID -->
            <value>0</value>
          </property>
          <property name="v2">
            <!-- "true" if provider supports OpenID 2.0, otherwise "false" -->
            <value>true</value>
          </property>
          <property name="iconClassPathUri">
            <!-- Path to provider logo within YouTrack classpath -->
            <value>smartui/img/loginGoogle.gif</value>
          </property>
          <property name="providerUri">
            <!-- OpenID provider service URL -->
            <value>https://www.google.com/accounts/o8/id</value>
          </property>
      </list>
    </property>
  </bean>
</beans>

Labels

 
(None)