FAQ

{anchor:top}
{toc:style=disc|indent=20px|maxLevel=5}

h1. YouTrack Requirements

{anchor:appservers}

h3. Which application servers does YouTrack support?

YouTrack [distributed as a WAR file|http://www.jetbrains.com/youtrack/download/#war] can be deployed into the following application servers:
* Apache Tomcat 6\+, 7\+
* Apache Geronimo
* Mortbay Jetty
* JBoss 4\+
* Caucho Resin
* Glassfish

[Distributed as a JAR file|http://www.jetbrains.com/youtrack/download/#jar], YouTrack comes bundled with Mortbay Jetty.

[Distributed as an EXE file|http://www.jetbrains.com/youtrack/download/index.html#exe], YouTrack comes bundled with Apache Tomcat 6.

*[Back to top|#top]*

h3. What hardware requirements does YouTrack have?

We're currently unable to define specific hardware requirements. However, when choosing a hardware configuration to host YouTrack, keep in mind the following:
* If you expect to have up to 10,000 issues in your installation, any up-to-date desktop PC can serve it.
* Our own [YouTrack instance|http://jetbrains.net/tracker/issues] currently processes 330,000 issues in 56 projects.
* We recommend to start YouTrack with at least 512M of heap memory available.

{show-if:mode=edit}is hosted at a 3GHz Quad Core server with 4GB RAM and 80GB SSD drive. 12GB of heap memory is currently allocated to YouTrack.{show-if}

Watch the *System Info* tab in Admin area for live memory usage data.

*[Back to top|#top]*

h3. Does YouTrack support IIS?

Unfortunately, currently YouTrack does not support IIS, and we do not plan to implement IIS support in the near future.

However, you can set up Tomcat to run YouTrack, and configure your IIS to work with Tomcat. For more details, see [http://tomcat.apache.org/connectors-doc/webserver_howto/iis.html].

Please, note that it's not possible to use plain IIS because it's not a J2EE application server; and, in order to run YouTrack, you need a J2EE server in any case.

*[Back to top|#top]*

h1. Installation and Upgrades

h3. Internet Explorer automatically renames JAR and WAR files to ZIP. What am I to do?

Nothing special, really:
# Download a JAR or WAR file.
# Rename {{youtrack-xx.zip}} to {{youtrack-xx.war}} or {{youtrack-xx.jar}}.
# Run your JAR file or deploy your WAR file as usual.

*[Back to top|#top]*

h3. How do I get YouTrack running on the same machine as TeamCity?

No special efforts are required to make YouTrack and TeamCity run together on a single machine. Both products can be deployed under most commonly used J2EE application servers. See below for the procedure of installing and running YouTrack in the same Tomcat instance TeamCity bundles.
[Click here|#appservers] for the list of application servers supported by YouTrack. For guidelines on TeamCity integration, see [Integration with TeamCity].

*To run both YouTrack and TeamCity on the same machine with one HTTP server*, you need to install both applications into the same Tomcat instance:
# Download and install TeamCity
# Download {{youtrack.war}} (instead of {{youtrack.exe}})
# Rename {{<TeamCity installation directory>/webapps/ROOT}} folder into {{<TeamCity installation directory>/webapps/teamcity}}
# Drop {{youtrack.war}} into the {{<TeamCity installation directory>/webapps/}} directory.
# Start Tomcat.
# TeamCity is now available at the {{http://<your_server>:80/teamcity}}, and YouTrack --- at {{http://<your_server>:80/youtrack}}.
{note}Please check that baseURL is correct in the Administration > Settings page of your instance. For example, in this case baseURL should be {{http://<your_server>:80/youtrack}}. Correct baseURL is necessary for correct work of REST API, screenshot applet, OpenID and TeamCity integration and for correct links in YouTrack notifications.{note}
*[Back to top|#top]*

h3. How do I upgrade to a newer YouTrack build or version? Should I back up my database before upgrading?

First, you do not have to back up your database just to upgrade to a newer YouTrack build or version --- after you have upgraded, YouTrack will find your database automatically.

{tip:title=Hint:}Since YouTrack 3.0.3, you can track availability of YouTrack new builds right from Administrators UI. Check the *'Update info'* panel on the *Administration > Settings* page. If a new build is available, you will see a link to download the update.{tip}

*To upgrade to a newer YouTrack build or version:*
# Stop YouTrack JAR, or YouTrack service (if you run YouTrack as Windows service), or, if you are running YouTrack within an application server, stop the server.
# Replace your old {{youtrack.jar}} or {{youtrack.war}} with a new build or version. Feel free to rename the new file to match the old one.
# Start YouTrack JAR or application server.

*[Back to top|#top]*

h3. I'm reinstalling (upgrading) YouTrack Windows service installation (using exe distribution) and get an error on installing Tomcat service. What's the problem? (on)

This is a known issue (see [http://youtrack.jetbrains.net/issue/JT-7600]). Most often case for this error is when you run installation while the currently installed service is still running.

# If you're only going to reinstall YouTrack, please stop running YouTrack services before installation.
# If you've got the error already, please restart the PC. Then install YouTrack once again. The point is to delete Tomcat service marked for deletion during the first installation attempt (after which you've got the error).

*[Back to top|#top]*

h1. Importing Issues


h3. Can I import issues from JIRA to YouTrack?

Yes, you can. To do that:
# Go to [http://yourserver:port/jiraIntegration] to open the *JIRA Integration* tab.
# Use links provided in the *JIRA Integration* tab to 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 {{http://<yourserver>:<port>/_classpath/jira-plugin/jetbrains-charisma-rpc-plugin-3.8.1-3.jar}})
#* YouTrack plug-in for JIRA 3.10-3.13.4 (available at {{http://<yourserver>:<port>/_classpath/jira-plugin/jetbrains-charisma-rpc-plugin-3.10-3.jar}})
#* YouTrack plug-in for Jira 4.0 and higher (available at {{http://<yourserver>:<port>/_classpath/jira-plugin/jetbrains-youtrack-rpc-plugin-4.0.jar}})
# Install the appropriate YouTrack plug-in in your JIRA instance by following guidelines for "Version 1" plug-ins in [Managing JIRA Plugins|http://confluence.atlassian.com/display/JIRA/Managing+JIRA%27s+Plugins].
# Make sure that [remote API is enabled in JIRA|http://confluence.atlassian.com/display/JIRA/Enabling+the+RPC+plugin] and the YouTrack plug-in has appeared in the list of JIRA plug-ins as "Charisma JIRA plugin".
# Go back to [http://yourserver:port/jiraIntegration].
# Click *Enable JIRA Integration*.
# Specify your _admin-level credentials_ in JIRA, a project to import, and required issue types.
# Click *Import Project*.
!jira_integration.png|thumbnail!


*[Back to top|#top]*

h3. Can I import issues from other issue tracking systems?

Yes, YouTrack 3.0 supports import from other tracking systems via [REST API|Import REST API]. We also provide [Python Client Library], which wraps REST API and allows using it with Python scripts. In addition, the Python Client Library contains several ready-to-use scripts for importing issues from [Bugzilla|Import from Bugzilla], [FogBugz|Import from FogBugz], [Mantis|Import from Mantis], [Trac|Import from Trac], from [Google Code Issue Tracker], and from another YouTrack server. In addition to these scripts, we provide another one, which enables importing issues to YouTrack via a CSV file, thus allowing import from almost any other issue tracker.



You can [request other importing features|http://jetbrains.net/tracker/issues/JT].

*[Back to top|#top]*

h3. Which JIRA versions can I import my issues from?

JIRA 3.8 and later is currently supported.
Two separate YouTrack plug-ins for JIRA are provided: one for versions from 3.8 through 3.12 and another for version 3.13 and later. Both are bundled with YouTrack and are available from the Admin area at [http://yourserver:port/jiraIntegration].

*[Back to top|#top]*


h1. Administering YouTrack

h3. I'm using the JAR format with the java service wrapper on a FreeBSD system, and cannot figure out how to specify what hostname YouTrack should bind itself on. What should I do?

*To define a hostname for YouTrack*, you have to edit file {{youtrack.jar\!/jetbrains/mps/webr/standalone/runtime/standalone.xml}}. In the file, locate the block
{code}
<New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
<Set name="port">8081</Set>
{code}and add the line {{<Set name="host">}}{{{}{_}desired hostname{_}{}}}{{</Set>}}. That's it\!

For example, to set hostname to the {{127.0.0.1}}, the block should look as follows:
{code}
<New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
<Set name="port">8081</Set>
<Set name="host">127.0.0.1</Set>
{code}

{anchor:guest_view}

h3. I have deployed YouTrack under Apache Tomcat but attempting to access YouTrack fails because of {{BeanCreationExceptions}}. What's the problem?

The user account used by Tomcat should have write permissions to Tomcat directory. Sometimes it doesn't, so make sure that the permissions are granted.

h4. Solving the problem for YouTrack WAR under Apache Tomcat on Ubuntu.

By default, YouTrack creates database in the {{$\{user.home\}/teamsysdata}} folder.
Most likely, you are running tomcat under user account with {{$HOME}} pointing to {{/usr/share/tomcat6/}} folder. Thus, YouTrack tries to create database folder {{/usr/share/tomcat6/teamsysdata}} and fails, because tomcat user has no write permissions for this folder.

To fix the problem, you can try any of the following methods:
# Grant write access to tomcat user for {{/usr/share/tomcat6}} folder. _Not recommended_
# Change tomcat user {{$home}} folder to something like {{/home/tomcat}} and grant write access to it.
# Change the default database location. For detailed procedure, please refer to [Changing Database Location] page.


*[Back to top|#top]*

{hidden-data}

h3. How do I create a list of assignees for a project?

Since YouTrack Energy any issue's field, including the Assignee field, is a custom field per se. To be able to assign an issue to some user you need to add this user to the Assignees bundle for the project.

To create Assignees list for a project:
# Navigate to Administration > <project> > Fields tab
# For the Assignees field, click the name of the used bundle:
# &nbsp;

*[Back to top|#top]*
{hidden-data}

h3. What are the default user rights for Guest? (on)

By default, the guest user has Observer role, which allows to Read Issues and Comments) for all projects.
To view actual permissions, which are currently set for the guest account, open the URL: {{http://<your youtrack url>/editUser/guest#user-tab=Permissions%20View}}

*[Back to top|#top]*

h3. How do I allow guest users to view my public projects?



# In the Admin Area, click *Groups*.
# Click *All Users*. This is a predefined group that controls permissions for _all_ users including guests.
# Open the *Roles* tab.
# Click *Assign role*.
# In the *Assign Role* dialog box, select _Observer_ in the *Role* drop-down list, and select your public projects in the *Projects* combo box.
# Click *OK*.

*[Back to top|#top]*

h3. How do I grant permissions to create new issues in a specific project to any registered user?

You should create or configure a user group that:
* Allows to report issues within a specific project via _Issue:CREATE_ permission.
* Enables *Auto Join* option, letting all new registered users join it automatically.
Here's how to do that using predefined groups and roles:

# In the Admin Area, open the *Groups* tab.
# Click *New Users*. This is a predefined group that controls permissions for _all_ registered users.
# In the *Main* tab, select *Auto Join* to automatically add all new registered users to this group.
# Open the *Roles* tab.
# Click *Assign role*.
# In the *Assign Role* dialog box, select _Reporter_ in the *Role* drop-down list. In the *Projects* combo box, select projects where you want to enable any registered users to create new issues:
!new_users_reporter.png|thumbnail!
# Click *OK* to apply changes.

{hidden-data}You can create your custom groups and roles but for easier administration, YouTrack provides two two predefined user groups:
* _All users_ (for all users including guests)
* _New users_ (for all registered users)
and four predefined roles:
* _Admin_
* _Developer_
* _Reporter_
\*_Observer_
Before allowing all registered users create issues in a specific project, make sure that guest users are not allowed to do so. See [How do I let guest users view my public projects?|#guest_view] for details.
{hidden-data}

*[Back to top|#top]*

h3. I don't want to use root account, but it seems I cannot delete it. What should I do?

You cannot delete root account in YouTrack, but, if you prefer to use another account to administer YouTrack instance, configure new admin account properly, and then perform any or all of the following operations:
* Deny root account any permissions.
* Set a custom password for root account.
* Ban root account.
Taking these steps prevents unauthorized access using root account.

*[Back to top|#top]*

h3. I forgot my root password. How can I restore it?

To restore root password, run YouTrack with the {{\-Djetbrains.charisma.restoreRootPassword=true}} JVM option. For example:

{code}java -Djetbrains.charisma.restoreRootPassword=true -jar youtrack-3.0.jar 8080{code}

When YouTrack starts, the root user password and permissions will be reset to default values. Log in with the default credentials (root/root) and then set the new root password.

*[Back to top|#top]*

h3. Why I don't see <some permission> on edit role page?

Make sure that you have this permission yourself. You can't grant a permission that you don't currently have.

*[Back to top|#top]*

{anchor:create_users}

h3. How do I create users in YouTrack?

Users are expected to register in YouTrack by themselves. However, if you need to create new user accounts yourself, you can do that using a regular registration form at {{[http://yourserver:port/registerUserForm]}}. After you have created a new user with this form, you are automatically logged in as this new user.
When you import an existing project from JIRA, user accounts are imported along with issues.
{hidden-data}
see [http://jetbrains.net/tracker/issue/JT-1628]

{hidden-data}

*[Back to top|#top]*

h3. How do I exclude a user from a group? There's no such option in group properties

You should exclude users from groups via user properties as opposed to group properties. See [Administrator's Guide|http://www.jetbrains.net/confluence/display/TSYSD/Adminitrator%27s+Guide#Adminitrator%27sGuide-ExcludingUsersfromGroups] for details.

*[Back to top|#top]*


h3. I'm trying to change logging level for YouTrack but it shows unnecessary messages time and again. What am I doing wrong?

You should modify logging levels in {{webapps/youtrack-xx/WEB-INF/classes/jetbrains/charisma/main/log4j.xml}} (for Apache Tomcat). Modifying logging properties in other files won't affect YouTrack logs.

*[Back to top|#top]*

h3. I want to allow attaching files larger than 10Mb set by default. How can I do that?

To specify the maximum allowed file size, use {{\-Djetbrains.webr.maxUploadFileSize=<value>}} JVM property. The value should specified in bytes. For example, to limit the maximun allowed attachment size to 50Mb, you should specify:

{code}-Djetbrains.webr.maxUploadFileSize=50000000{code}

*[Back to top|#top]*

h3. How to launch YouTrack without letting it open a browser window?(on)

When you launch YouTrack as the jar file from the command line, it automatically opens a new browser window to display the main page. If you want to avoid launching the browser, you should use the "{{-Djetbrains.youtrack.disableBrowser=true}}" Java parameter to your command. For example:

{code}java -Djetbrains.youtrack.disableBrowser=true -Xmx512m -jar /Applications/youtrack-3.0.4.jar 8000{code}

*[Back to top|#top]*

h1. Using YouTrack

{anchor:assign_to_yourself}

h3. I'm trying to assign an issue to myself but YouTrack refuses to do so. What's wrong?

You are neither a member of any groups configured as assignees for a particular project nor an individual assignee for this project.
You have three options:
* Ask the project lead that he/she assigns the issue to you.
* Ask your administrator to add you to a group that is configured as assignee for the project.
* Ask your administrator to configure your user account as an individual assignee for the project.

Both groups and individual assignees for a particular project can be configured by choosing *Projects \| <project name> \| Assignees* in the Admin area:
!project_assignees.png|thumbnail!
{hidden-data}
[http://jetbrains.net/tracker/issue/JT-1720]

{hidden-data}

*[Back to top|#top]*

h3. After upgrading to Mac OS X 10.7 Lion, YouTrack Screenshot applet does not start! What's wrong? (on)

If you encounter this problem, first of all check your Java preferences:
# Open *Applications > Utilities > Java Preferences*.
# In *General* settings select the 'Enable applet plug-in and Web Start applications' check box:
!javaSettingForLion.png!
# Restart your browser.
This simple procedure should solve the problem.

Currently, in YouTrack 2.x, you can arrange the verification workflow using tags or custom fields.
With tags, you can organize the workflow via creating shared tags, and customizing notifications for the tags, so all the team members will be notified on time. See [Fixed Not Tested|http://www.jetbrains.net/devnet/thread/283573?tstart=0] in JetBrains Developer Community for guidelines.

With custom fields, an administrator can create a new custom field and attach it to the project. For example, your project can have a custom field "Verify state", with {{enum\[1\]}} type, and enumeration bundle of the following values: _Fixed not Tested_, _Verifying_, _Verified_, _Not Verified_, _Back in development_. The con of this method is that in YouTrack 2.x you cannot customize receiving notifications by one particular field update, and the workaround would be a simultaneous change of assignee along with updating such custom field, or a combination of custom fields and tags. For more details about custom fields please refer to the [Custom Fields] page.
The good news are that in the upcoming YouTrack Energy version we are going to provide a custom workflow support, please stay tuned for updates.

*[Back to top|#top]*


h3. I have an account in YouTrack, but now I want to log in using my OpenID. How can I associate my OpenID to my existing account?

First of all, log in to YouTrack with your OpenID. If your OpenID provider reports the same e-mail address as the one registered for your existing YouTrack account, then the OpenID will be automatically associated with the account.
If your OpenID e-mail address differs from the YouTrack account's e-mail, then upon login a new account will be created. In this case, YouTrack administrator should merge the new account with the existing one, so that OpenID will be associated to the existing user account.

*[Back to top|#top]*

h3. How do I search for issues, which were created/updated/resolved before specific date? (on)

To search for a date before specific one, you can use search by a date range. For example, to find all unresolved issues assigned to you, which were created before January 12th, 2012, you can use the following search query:
{code}for: me #Unresolved created: 1900-01..12-01-2012{code}
*[Back to top|#top]*

h3. Is there an easy way to create multiple issues with the same set of attributes, tags etc.?

Of course there is\!
# Create multiple new issues, one by one, without specifying their attributes.
# Search for your recent reported issues:
{{by: me}}
# Select the recently reported issues that should have identical attributes and/or tags.
# Press *Ctrl+Alt+J* to open the Command window, and apply a single command to the selected issues.
For example, the following command:
{{for me project YouTrack subsystem Wiki priority normal fix for next version}}
will assign all selected issues to you, move them to subsystem _Wiki_ in project _YouTrack_, set them to normal priority, and schedule them to be fixed for next version.
# Press *Ctrl+Enter* to apply the command.

*[Back to top|#top]*

{anchor:subtasks}

h3. How do I create subtasks in YouTrack?

Instead of creating subtasks, you create links between issues. Predefined issue link types include "duplicates", "depends on" and "relates to". Administrators are able to add other issue link types if necessary.
To create a relationship:
# In the list of issues, select one or more issues that relate, depend on or duplicate other issues.
# In the *Link* menu on the toolbar, choose *duplicates*, *depends on*, or *relates to*.
# When the Command window displays with a corresponding command, type the ID of the issue that selected issues should be linked to, or execute full-text search for the issue. To link selected issues to several issues, repeat the command:
!relates_depends.png|thumbnail!
# Click *Submit* or press *Ctrl+Enter* to apply the relationship(s).

Alternatively, consider using [tags|http://www.jetbrains.com/youtrack/features/organize.html#Tags] for grouping issues.

*[Back to top|#top]*

{anchor:visual_types}

h3. Can I visually distinguish between features, bugs and other issue types in the list of issues?

Out of the box, YouTrack doesn't let you configure colors, custom formatting or other means of visually highlighting various issue types.
However, there's a workaround: you can mark different issue types with tags. For example, if you want to introduce custom highlighting for bugs and features, you might do the following:
# Search for unresolved bugs assigned to you:
{{\#unresolved for: me #bug}}
# In the list of issues, press *Ctrl+A* to select all issues (if the list of issues takes more than a single page, additionally click *Select all issues* in the yellow tooltip that appears just above the list of issues after you have pressed *Ctrl+A*.)
# Type command {{tag bug}}.
# Press *Ctrl+Enter* to apply the tag to selected issues.
# Execute steps 1-4 upon unresolved features assigned to you. To find them, enter {{\#unresolved for: me #feature}} in the search box, and call the new tag "feature".
# For each of the two created tags, click the pencil icon in the *Tags* pane to modify their colors. For example, highlight "bug" with red and "feature" with blue:
!tagging_types_colors.png|thumbnail!
# Click *Settings* in the toolbar and make sure that the *Tags* check box is selected in the *Visibility* tab:
!tags_visibility.png|thumbnail!
# Search for all your unresolved features: {{\#unresolved for: me}}. Both bugs and features are in the list of issues are now marked with tags corresponding to their type:
!bugs_features_marked_with_tags.png|thumbnail!

*[Back to top|#top]*

{anchor:vcs}

h1. Integration with External Tools

h3. Does YouTrack support LDAPS? How can I configure integration for LDAPS?

Yes, YouTrack supports LDAPS (LDAP over SSL) protocol. For details about configuration, please refer to the [LDAP integration] page.

*[Back to top|#top]*


h3. I try to connect my YouTrack server in Tasks configuration in my IDEA-based IDE, but it seems to be not working. What's wrong? (on)

Most likely you did not enable REST API on your YouTrack server. To enable the REST API in YouTrack:
# Open *Administration > Settings* page
# In the *System* pane, select the *REST API* check box.
!restApiEnabled.png|thumbnail!

That's it. Just try to connect your YouTrack server from your IDE again.

*[Back to top|#top]*

h3. I have some problems with my Mailbox Integration. How can I enable detailed logging? (on)

To enable logging for Mailbox integration, in the file {{<YouTrack installation directory>/WEB-INF/classes/jetbrains/charisma/main/log4j.xml}} change the following code:
{code}
<category name="jetbrains.youtrack.mailbox">
<priority value="WARN"></priority>
</category>
{code}

to

{code}
<category name="jetbrains.youtrack.mailbox">
<priority value="DEBUG"></priority>
</category>
{code}

That's it\!

*[Back to top|#top]*

h1. Integration with Version Control Systems

{anchor:vcs_through_teamcity}

h3. How to integrate YouTrack with different version control systems?

YouTrack can be integrated with version control systems via [TeamCity|http://www.jetbrains.com/teamcity/] 5.0 or later. For guidelines on TeamCity integration, see [Integration with TeamCity].

*[Back to top|#top]*

{anchor:vcs_directly}

h3. Does YouTrack integrate with version control systems directly, without using TeamCity?

No, it only integrates with VCS through TeamCity. TeamCity supports all major VCS's, including ClearCase, CVS, Perforce, StarTeam, Subversion, Team Foundation Server, Mercurial, and Visual SourceSafe.
TeamCity Professional Edition is [available free of charge|http://www.jetbrains.com/teamcity/download/], making direct VCS support from YouTrack unjustified at this time.
Should TeamCity move their VCS support functionality into a separate module, we might reconsider this possibility.
For guidelines on TeamCity integration, see [Integration with TeamCity].

*[Back to top|#top]*

h3. I have configured TeamCity integration but TeamCity doesn't convert issue IDs to links

Make sure that your TeamCity installation successfully connects to your YouTrack installation.
See [connection configuration guidelines|TCD5:Issue Tracker Tab] in TeamCity 5.x documentation.

*[Back to top|#top]*

h3. Is it possible to integrate YouTrack with several TeamCity servers? How can I do it?

Yes, you can integrate YouTrack with several TeamCity servers.
To configure integration, open the *[TeamCity Integration|Administrator's Guide#TeamCity Integration]* section in the Admin area, add your TeamCity servers, and do not forget [create correct mappings|Integration with TeamCity#Mapping Projects] between YouTrack projects and TeamCity projects.

*[Back to top|#top]*