Installation

Before you install, see the System Prerequisites guide to make sure you have all required system packages installed.

Install with pip

To install the Girder distribution from the python package index, simply run

pip install girder

This will install the core Girder REST API as a site package in your system or virtual environment. At this point, you might want to check the configuration to change your plugin and logging paths. In order to use the web interface, you must also install the web client libraries. Girder installs a python script that will automatically download and install these libraries for you. Just run the following command:

girder-install web

If you installed Girder into your system site-packages, you may need to run this command as root.

Optionally, you can also install a set of plugins that are distributed with Girder. The girder-install script can do this for you as well by running:

girder-install plugin

Once this is done, you are ready to start using Girder as described in this section: Run.

Install from Git Checkout

Obtain the Girder source code by cloning the Git repository on GitHub:

git clone https://github.com/girder/girder.git
cd girder

To run the server, you must install some external Python package dependencies:

pip install -r requirements.txt

Note

If you intend to develop Girder or want to run the test suite, you should also install the development dependencies:

pip install -r requirements-dev.txt

One of the development requirements, httpretty, can fail to install if under certain system locales (see the error report). Changing to any UTF8 locale works around this problem. For instance, on Ubuntu, you can change your system locale using the commands:

locale-gen en_US.UTF-8
export LANG=en_US.utf8

Before you can build the client-side code project, you must install the Grunt command line utilities:

npm install -g grunt-cli

Then cd into the root of the repository and run:

npm install

This should run grunt init and grunt to build all of the javascript and CSS files needed to run the web client application.

Run

To run the server, first make sure the Mongo daemon is running. To manually start it, run:

mongod &

If you installed with pip, you will have the girder-server executable on your path and can simply call

girder-server

- or -

If you checked out the source tree, you can start the server with the following command, which will have identical behavior:

python -m girder

Then open http://localhost:8080/ in your web browser, and you should see the application.

Initial Setup

The first user to be created in the system is automatically given admin permission over the instance, so the first thing you should do after starting your instance for the first time is to register a user. After that succeeds, you should see a link appear in the navigation bar that says Admin console.

The next recommended action is to enable any plugins you want to run on your server. Click the Admin console navigation link, then click Plugins. Here, you can turn plugins on or off. Whenever you change the set of plugins that are enabled, you must restart the CherryPy server for the change to take effect. For information about specific plugins, see the Plugins section.

After you have enabled any desired plugins and restarted the server, the next recommended action is to create an Assetstore for your system. No users can upload data to the system until an assetstore is created, since all files in Girder must reside within an assetstore. See the Assetstores section for a brief overview of Assetstores.