Installation¶
Before you install, see the System Prerequisites guide to make sure you have all required system packages installed.
Creating a virtual environment¶
While not strictly required, it is recommended to install Girder within
its own virtual environment
to isolate its dependencies from other python packages. To generate a new
virtual environment, first install/update the virtualenv
and pip
packages
sudo pip install -U virtualenv pip
Now create a virtual environment using the
virtualenv command.
You can place the virtual environment directory wherever you want, but it should
not be moved. The following command will generate a new directory called
girder_env
in your home directory:
virtualenv ~/girder_env
Enter the virtual environment:
. ~/girder_env/bin/activate
The (girder_env)
prepended to your prompt indicates you have entered
the virtual environment. Inside the virtual environment you can use pip
,
python
, and any other python script installed in your path as usual.
You can exit the virtual environment by running the shell function
deactivate
. The shell variable VIRTUAL_ENV
will also list the
absolute path to the current virtual environment. Entering a virtual
environment only persists for your current shell, so you must source
the activation script again whenever you wish to enter within a
new shell session. Users and developers needing to work on several virtual
environments should consider using other packages that help manage them such as
virtualenvwrapper,
autoenv,
pyenv-virtualenv, or
pyenv-virtualenvwrapper.
Sources¶
Girder can be installed either from the Python Package Index (pypi) or via a Git repository. Installing from pypi gives you the latest distributed version. Installing from git would be more suitable for development or to have a specific commit, or to use the latest Girder features before they are released in official packages.
Install from pypi¶
To install the Girder distribution from the python package index, simply run
pip install girder
This will install the core Girder server 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 build and install these libraries for you. Just run the following command:
girder-install web
Note
Installing the web client code requires the node package manager (npm). See the System Prerequisites section for instructions on installing nodejs.
Note
If you installed Girder into your system site-packages
, you may
need to run the above commands as root.
Once this is done, you are ready to start using Girder as described in this section: Run.
Installing extra dependencies with pip¶
Girder comes bundled with a number of Plugins that require extra python dependencies in order to use. By default, none of these dependencies will be installed; however, you can tell pip to install them using pip’s “extras ” syntax. Each girder plugin requiring extra python dependencies can be specified during the pip install. For example, installing girder with support for the celery_jobs and geospatial plugins can be done like this:
pip install girder[celery_jobs,geospatial]
There is also an extra you can use to install the dependencies for all bundled
plugins supported in the current python environment called plugins
:
pip install girder[plugins]
Warning
Not all plugins are available in every python version and platform. Specifying a plugin for in an unsupported environment will raise an error.
Install from Git repository¶
Obtain the Girder source code by cloning the Git repository on GitHub:
git clone --branch 2.x-maintenance https://github.com/girder/girder.git
cd girder
Note
Note, it is strongly recommended that downstream (i.e. for production or to
support plugin development) users installing from Git track the 2.x-maintenance
branch, as
this branch will always point to the latest version (which is typically pre-release) in the 2.x.x
series.
To run the server, you must install some external Python package dependencies:
pip install -e .
or:
pip install -e .[plugins]
to install the plugins as well.
Note
This will install the most recent versions of all dependencies.
You can also try to run pip install -r requirements.txt
to duplicate
the exact versions used by our CI testing environment; however, this
can lead to problems if you are installing other libraries in the same
virtual or system environment.
To build the client-side code project, cd into the root of the repository and run:
girder-install web
This will run multiple Grunt tasks, 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 &
Then to run Girder itself, just use the following command:
girder serve
Then open http://localhost:8080/ in your web browser, and you should see the application.
Initial Setup¶
Admin Console¶
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
.
Enable Plugins¶
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 need to press the Rebuild and restart button at the top of the
Plugins page to rebuild the web client and restart the server to apply the change.
For information about specific plugins, see the Plugins section.
Create Assetstore¶
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
.
Installing third-party plugins¶
Girder ships with a standard library of plugins that can be enabled in the admin console, but it’s common for Girder installations to require additional third-party plugins to be installed. If you’re using a pip installed version of Girder, you can simply use the following command:
girder-install plugin /path/to/your/plugin
That command will expose the plugin to Girder and build any web client targets associated with the plugin. You will still need to enable it in the console and then restart the Girder server before it will be active.
Note
The girder-install plugin
command can also accept a list of plugins
to be installed. You may need to run it as root if you installed Girder at the
system level.
For development purposes it is possible to symlink (rather than copy) the plugin
directory. This is accomplished with the -s
or --symlink
flag:
girder-install plugin -s /path/to/your/plugin
Enabled plugins installed with -s
may be edited in place and those changes will
be reflected after a server restart.