- YouTrack Requirements
- Installation and Upgrades
- Internet Explorer automatically renames JAR and WAR files to ZIP. What am I to do?
- How do I get YouTrack running on the same machine as TeamCity?
- How do I upgrade to a newer YouTrack build or version? Should I back up my database before upgrading?
- I'm reinstalling (upgrading) YouTrack Windows service installation (using exe distribution) and get an error on installing Tomcat service. What's the problem?
- Importing Issues
- Administering YouTrack
- I got the java.lang.OutOfMemoryError exception. What should I do?
- 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?
- I have deployed YouTrack under Apache Tomcat but attempting to access YouTrack fails because of BeanCreationExceptions. What's the problem?
- What are the default user rights for Guest?
- How do I allow guest users to view my public projects?
- How do I grant permissions to create new issues in a specific project to any registered user?
- I don't want to use root account, but it seems I cannot delete it. What should I do?
- I forgot my root password. How can I restore it?
- How to restore my root password if I run YouTrack as Windows service?
- Why I don't see <some permission> on edit role page?
- How do I create users in YouTrack?
- How do I exclude a user from a group? There's no such option in group properties
- I'm trying to change logging level for YouTrack but it shows unnecessary messages time and again. What am I doing wrong?
- I want to allow attaching files larger than 10Mb set by default. How can I do that?
- How to launch YouTrack without letting it open a browser window?
- Using YouTrack
- I'm trying to assign an issue to myself but YouTrack refuses to do so. What's wrong?
- YouTrack Screenshot applet does not start on Mac OS X 10.7 Lion! What's wrong?
- I run YouTrack with Glassfish 3 and I cannot upload files or attach screenshots! WTF?!
- Our workflow requires that developers mark issues as fixed and hand them over to QA. Is there a state in YouTrack that lets us do that, something like "Fixed not tested"?
- 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?
- How do I search for issues, which were created/updated/resolved before specific date?
- How do I order search results by anything other than "Updated"?
- Is there an easy way to create multiple issues with the same set of attributes, tags etc.?
- Can I visually distinguish between features, bugs and other issue types in the list of issues?
- Integration with External Tools
- Integration with Version Control Systems
- How to integrate YouTrack with different version control systems?
- Does YouTrack integrate with version control systems directly, without using TeamCity?
- I have configured TeamCity integration but TeamCity doesn't convert issue IDs to links
- Is it possible to integrate YouTrack with several TeamCity servers? How can I do it?
Legend: — new or updated topic
Which application servers does YouTrack support?
YouTrack distributed as a WAR file can be deployed into the following application servers:
- Apache Tomcat 6+, 7+
- Apache Geronimo
- Mortbay Jetty
- JBoss 4+
- Caucho Resin
Distributed as a JAR file, YouTrack comes bundled with Mortbay Jetty.
Distributed as an EXE file, YouTrack comes bundled with Apache Tomcat 6.
What hardware requirements does YouTrack have?
Standalone version of YouTrack does not have 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 currently (as of March 14, 2014) runs in Amazon EC2 environment, on a
m2.4xlarge instance. It processes about 658 thousand issues in 105 projects. These issues contain about 690000 comments and 155000 attachments, of which about 107000 are images.
However, since YouTrack 5.0, requirements for allocated JVM memory have been increased:
- The Permanent Generation Size must be set to at least 150Mb via the
- We recommend to start YouTrack with at least 512M of heap memory available.
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.
Installation and Upgrades
Internet Explorer automatically renames JAR and WAR files to ZIP. What am I to do?
Nothing special, really:
- Download a JAR or WAR file.
- Run your JAR file or deploy your WAR file as usual.
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 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
<TeamCity installation directory>/webapps/ROOTfolder into
<TeamCity installation directory>/webapps/teamcity
<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. Back to top
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.
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.warwith a new build or version. Feel free to rename the new file to match the old one.
- Start YouTrack JAR or application server.
I'm reinstalling (upgrading) YouTrack Windows service installation (using exe distribution) and get an error on installing Tomcat service. What's the problem?
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).
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
- YouTrack plug-in for JIRA 3.10-3.13.4 (available at
- YouTrack plug-in for Jira 4.0 and higher (available at
- YouTrack plug-in for JIRA 3.8-3.9.3 (available at
- Install the appropriate YouTrack plug-in in your JIRA instance by following guidelines for "Version 1" plug-ins in Managing JIRA Plugins.
- 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".
- 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.
Can I import issues from other issue tracking systems?
Yes, YouTrack supports import from other tracking systems via 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, FogBugz, Mantis, 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.
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.
I got the
java.lang.OutOfMemoryError exception. What should I do?
java.lang.OutOfMemoryError exception can be fixed by increasing the memory allocated for Java. To fix the error, identify the particular type of the
you've got. Depending on the exception reason, you should run YouTrack with the corresponding -D start Java parameter to solve the problem. Please refer to the table below:
Fix and Java Parameter
Java heap space
Increase heap size via
Increase permgen size via
GC overhead limit exceeded
Increase heap size via
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
and add the line
</Set>. That's it!
For example, to set hostname to the
127.0.0.1, the block should look as follows:
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.
Solving the problem for YouTrack WAR under Apache Tomcat on Ubuntu.
By default, YouTrack creates database in the
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/tomcat6folder. Not recommended
- Change tomcat user
$homefolder to something like
/home/tomcatand grant write access to it.
- Change the default database location. For detailed procedure, please refer to Changing Database Location page.
What are the default user rights for Guest?
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
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.
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 "Create Issue" 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:
- Click OK to apply changes.
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.
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:
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.
How to restore my root password if I run YouTrack as Windows service?
To restore your root password, if you run YouTrack as Windows service, please follow these instructions:
- Stop the service
- In the command line, run This will cause Tomcat webserver properties manager to appear in your Windows system tray
- Click on the above mentioned manager and select 'Java' tab
-Djetbrains.charisma.restoreRootPassword=trueinto Java options input
- Click OK. This will close the manager (Attention! This feels a bit counter-intuitive, but you really have to close it here)
- Open the manager once again. On General tab press Start
- Log in to YouTrack with root/root credentials
- Change the password
- Open the manager once again. On General tab press Stop
- Right click on manager's icon -> Exit
- Run the service as usual
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.
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.
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 for details.
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.
For more details, please refer to the Configuring Logging in YouTrack page.
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:
How to launch YouTrack without letting it open a browser window?
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:
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:
YouTrack Screenshot applet does not start on Mac OS X 10.7 Lion! What's wrong?
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:
- Restart your browser.
This simple procedure should solve the problem.
I run YouTrack with Glassfish 3 and I cannot upload files or attach screenshots! WTF?!
Our workflow requires that developers mark issues as fixed and hand them over to QA. Is there a state in YouTrack that lets us do that, something like "Fixed not tested"?
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 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 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.
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.
How do I search for issues, which were created/updated/resolved before specific date?
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:
How do I order search results by anything other than "Updated"?
Indeed, by default, search results are ordered by the "Updated" field, in descending order. That is, the most recently updated issue is displayed at the top of the list.
However, you can sort search results by any issue field.
First option is to specify sorting order in the search request itself. For example:
In this case search results will be sorted by Project name in ascending order (in case of project names, this means alphabetical order).
You can also sort search results by several parameters. In this case, issues will be sorted by the first parameter, and within the batch matching the first sort parameter, issues will be sorted according to the second sorting parameter.
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:
- 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.
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
- 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 #featurein 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:
- Click Settings in the toolbar and make sure that the Tags check box is selected in the Visibility tab:
- 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:
Integration with External Tools
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.
I have some problems with my Mailbox Integration. How can I enable detailed logging?
To enable logging for Mailbox integration, in the file
<YouTrack installation directory>/WEB-INF/classes/jetbrains/charisma/main/log4j.xml change the following code:
Integration with Version Control Systems
How to integrate YouTrack with different version control systems?
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, 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.
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 in TeamCity 8.x documentation.
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 section in the Admin area, add your TeamCity servers, and do not forget create correct mappings between YouTrack projects and TeamCity projects.