The Specify Software Project is funded by the Advances in Biological Informatics Program, U.S. National Science Foundation (NSF/BIO: 1565098).
Specify 7 Copyright © 2017 University of Kansas Center for Research. Specify comes with ABSOLUTELY NO WARRANTY. This is free software licensed under GNU General Public License 2 (GPL2).
Specify Software Project Biodiversity Institute University of Kansas 1345 Jayhawk Blvd. Lawrence, KS USA 66045
After completing these instructions you will be able to run the test server and interact with the Django based Specify webapp in your browser on your local machine.
Instructions for deployment follow.
Note: If updating from a previous version, some of the python dependencies have changed. It is recommended to place the new version in a separate directory next to the previous version and install all the new dependencies in a Python virtualenv as described below. That will avoid version conflicts and allow the previous version to continue working while the new version is being set up. When the new version is working satifactorily using the test server, the Apache conf can be changed to point to it (or changed back to the old version, if problems arise).
Deployment with Docker
Install system dependencies.
Specify 7 requires Python 2.7 which is the default for recent Linux distributions.
Other required software:
- Git to obtain the Specify 7 repository
- Python-pip to install Python dependencies
- Python and MySQL development packages to compile the Python MySQL driver
- The build-essential packages for compiling the Python MySQL driver
- Specify6 for common resource files
sudo apt-get install \ git python-pip python-dev libmysqlclient-dev \ build-essential curl curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash - sudo apt-get install nodejs
To install Specify6, follow the Specify6 installation instructions, or copy an existing installation if you have one.
Get the specifyweb source code.
Clone this repository.
git clone git://github.com/specify/specify7.git
You will now have a specify7 directory containing the source tree.
Adjust settings files.
In the directory
specify7/specifyweb/settings you will find the
specify_settings.py file. Make a copy of this file as
local_specify_settings.py and edit it. The file contains comments
explaining the various settings.
Python Virtual Environment.
Using a Python virtual environment will avoid version conflicts with other Python libraries on your system. Also it avoids having to use a superuser account to install the Python dependencies.
First make sure a reasonably up-to-date virtualenv tool is installed on your system.
If virtualenv is not installed, I recommend installing it using pip.
sudo pip install virtualenv
Creating and activating the virtualenv
I generally create a virtualenv inside the the
virtualenv specify7/ve source specify7/ve/bin/activate
The shell prompt will be modified to indicate the virtualenv is
active. It can be deactivated by invoking
deactivate from the shell
The Makefile contains several targets for building and preparinge Specify 7. If a virtualenv is active when make is invoked, it will be detected and used installing Python dependencies or invoking Python scripts.
When building the frontend, Webpack will issue the following warnings that can be safely ignored:
The default make target all will invoke the steps necessary to run Specfy 7.
Installs or updates dependencies and executes all build steps.
Installs or updates Python dependencies and generates
Install or updates Python dependencies.
Applies Specify schema changes to the database named in the
settings. This step may fail if the master user configured in the
settings does not have DDL privileges. Changing the
MASTER_PASSWORD settings to the MySQL root user will allow the
changes to be applied. Afterwards the master user settings can be
Removes all generated files.
A shortcut for running the Django development server.
Run webpack in watch mode so that changes to the frontend source code will be automatically compiled. Useful during the development process.
Turn on debugging.
Debugging can be enabled by creating the file
specify7/specifyweb/settings/debug.py with the contents,
DEBUG = True.
The development server.
Specify7 can be run using the Django development server. If you are using Python virtual environment, you will of course need to activate it first.
python specify7/specifyweb/manage.py runserver
This will start a development server for testing purposes on
The Makefile contains a shortcut target to start the development server.
When the server starts up, it will issue a warning that some migrations have not been applied:
You have 11 unapplied migration(s). Your project may not work properly until you apply the migrations for app(s): auth, contenttypes, sessions. Run 'python manage.py migrate' to apply them.
Specify 7 makes use of functions from the listed Django apps (auth,
contenttypes, and sessions) but does not need the corresponding tables
to be added to the database. Running
make django_migrations will
apply only those migrations needed for Specify 7 to operate.
Deployment to production.
Start by following the development instructions above, but don't enable debugging (or disable it if you enabled it previously).
For production environments, Specify7 can be hosted by Apache. The following packages are needed:
- mod-wsgi to connect Python to Apache
sudo apt-get install apache2 libapache2-mod-wsgi
specify7 directory you will find the
file. Make a copy of the file as
edit the contents to reflect the location of Specify6 and Specify7 on
your system. There are comments showing what to change.
Then, remove the default Apache welcome page.
sudo rm /etc/apache2/sites-enabled/000-default.conf
And make a link to your
sudo ln -s `pwd`/specify7/local_specifyweb_apache.conf /etc/apache2/sites-enabled/
After changing Apache's config files, restart it.
sudo invoke-rc.d apache2 restart
Updating Specify 7
To update the Specify 7 server software follow this procedure.
Backup your Specify database using MySQL dump or the Specify backup and restore tool.
Clone or download a new copy of this repository in a directory next to your existing installation.
git clone git://github.com/specify/specify7.git specify7-new-version
Copy the settings from the existing to the new installation.
cp specify7/specifyweb/settings/local* specify7-new-version/specifyweb/settings/
Make sure to update the
local_specify_settings.py, if you are updating the Specify 6 version.
If you are using Python virtualenvs for your Specify 7 Python dependancies (recommended), then create a new virtualenv for the new installation.
virtualenv specify7-new-version/ve source specify7-new-version/ve/bin/activate
make allwhich will pull down the Python dependencies, build the JS bundles, and apply any necessary database migrations.
Testing it out with the development server.
Deploy the new version by updating your Apache config to replace the old installation paths with the new.