Specify 7

The Specify Collections Consortium is pleased
to offer Specify 7, the web implementation of our biological collections data
management platform.

We encourage members to use our
Dockerized compositions of
Specify 7. You can choose a version, make the necessary adjustments and then run
a single command to get everything working. It is very simple and can be easily
updated when new versions are released. Members can contact us at
[email protected] to gain access
to this repository.

The new generation of Specify combines the interface design components and data
management foundation of Specify 6 with the efficiency and ease-of-use of
web-based data access and cloud computing. Specify 7 uses the same interface
layout language as Specify 6, so any user interface customization made in one
platform is mirrored in the other. Also Specify 6 and Specify 7 use the same
data model and can work from the same Specify MySQL or MariaDB database, which
means 6 and 7 can be run simultaneously with any Specify collection. Specify 7
helps transition Specify 6 collections to cloud computing. It is also a great
starting platform for institutions that prefer zero workstation software
installation and ubiquitous web browser access.

Specify 7’s architecture supports collaborative digitization projects and remote
hosting of specimen databases. Without the need for a local area or campus
network to connect to the MySQL data server, Specify 7 gives you and your
collaborators access to a shared specimen database through any web browser.
Finding it challenging to obtain IT support to maintain a local secure database
server? With the Specify 7 server software supported on generic Linux servers,
museums can utilize a server hosting service to provide support for the
technical complexities of systems administration, security management, and
backing-up. Want to create a joint database for a collaborative digitizing
effort? No problem! Host, hire a hosting service or use our
Specify Cloud service for
your Specify database, set up accounts and go. We provide the same efficient
user interface, report and labels customization and help desk support for
Specify 7 as we do for Specify 6.

Secure. Support for Single Sign-On (SSO) integrates Specify 7 with a campus
or institutional identity providers. It supports all identity providers (IdPs)
that have an OpenID endpoints.

The Security and Accounts tool allows administrators to give access based on
roles and policies. Create, edit, and copy roles among collections and
databases. Administrators can give users as many or few permissions as desired,
from guest accounts to collection managers.

Accessible. It is important that web applications work for people with
disabilities. Specify 7 is developed with this top of mind, not only meeting
international accessibility standards but also providing a better experience for
everyone.

Specify 7 is largely compliant with the main WWW accessibility standard – WCAG
2.1 (AA). It supports screen readers and allows each user to customize their
color scheme and appearance as well as reduce motion and resize all elements.

This accessible design respects system and web browser preferences for date
formats, language, theme, and animations.

The Specify Collections Consortium is funded by its member institutions. The
Consortium web site is: https://specifysoftware.org

Specify 7 Copyright © 2024 Specify Collections Consortium. Specify comes with
ABSOLUTELY NO WARRANTY. This is free software licensed under GNU General Public
License 2 (GPL2).

Specify Collections Consortium
Biodiversity Institute
University of Kansas
1345 Jayhawk Blvd.
Lawrence, KS 66045 USA

Table of Contents

• Specify 7
  • Table of Contents
  • Changelog
• Installation
  • Docker Installation (Recommended)
    • Specify Collections Consortium (SCC) Members:
    • Non-Members:
  • Local Installation
    • Installing system dependencies
    • Installing Specify 6
    • Cloning Specify 7 source repository
    • Adjusting settings files
    • Setting up Python Virtual Environment
    • Building
      • make build
      • make frontend
      • make clean
      • make pip_requirements
      • make django_migrations
      • make runserver
      • make webpack_watch
    • Turning on debugging
    • The development server
    • The Specify 7 Worker
    • Installing production requirements
    • Setting up Apache
    • Restarting Apache
    • Nginx configuration
  • Updating Specify 7
  • Updating the database (Specify 6) version
  • Localizing Specify 7

Changelog

Changelog is available in CHANGELOG.md

Installation

We encourage all users to read our documentation on the Community Forum
regarding installing and deploying Specify –
Specify 7 Installation Instructions.

If you are an existing Specify 6 user who is looking to evaluate Specify 7, you
can contact [email protected]
along with a copy of your database and we can configure a temporary deployment
for evaluation purposes.

Docker Installation (Recommended)

Specify Collections Consortium (SCC) Members:

We encourage members to use our
Dockerized compositions of
Specify 7. You can choose your desired version, make the necessary adjustments
and then run a single command to get everything working. It is very simple and
can be easily updated when new versions are released. Documentation for
deploying Specify using Docker is available within the repository.

📨 Click here to request access
or email [email protected] with
your GitHub username, member institution or collection, and any additional
questions you have for us.

Non-Members:

If your institution is not a member of the Specify Collections Consortium, you
can follow the local installation instructions below or
contact [email protected]
to learn more about joining the SCC to receiving configuration assistance,
support, and hosting services if you are interested.

Local Installation

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 satisfactorily using the test server, the Apache conf
can be changed to point to it (or changed back to the old version, if problems
arise).

Installing system dependencies

Specify 7 requires Python 3.8. Ubuntu 20.04 LTS is recommended. For other
distributions these instructions will have to be adapted.

Ubuntu 20.04 LTS:

sudo apt install -y curl
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get -y install --no-install-recommends \
  build-essential \
  git \
  libldap2-dev \
  libmariadbclient-dev \
  libsasl2-dev \
  nodejs \
  python3-venv \
  python3.8 \
  python3.8-dev \
  redis \
  unzip

CentOS 7 / Red Hat 7:

yum install -y epel-release sudo wget
yum install -y \
  gcc make \
  git \
  openldap-devel \
  mariadb-devel \
  nodejs \
  npm \
  java-11-openjdk-headless \
  python36-virtualenv \
  python36 \
  python36u-devel \
  redis \
  unzip

Afterward, please make sure you have Node.js 20 installed:

node -v

Installing Specify 6

A copy of the most recent Specify 6 release is required on the server as Specify
7 makes use of resource files. A Java runtime is required to execute the Specify
6 installer, but is not needed to run Specify 7. It is possible to copy the
Specify 6 install from another Linux system to avoid the need to install Java on
the server.

wget https://update.specifysoftware.org/Specify_unix_64.sh
sh Specify_unix_64.sh -q -dir ./Specify6.8.03
sudo ln -s $(pwd)/Specify6.8.03 /opt/Specify

Cloning Specify 7 source repository

Clone this repository.

git clone https://github.com/specify/specify7.git

You will now have a specify7 directory containing the source tree.

Note, by default, git clone checks out the production branch of Specify 7.
That branch contains the latest tested features and bug fixes. If you prefer a
more stable release, you can switch to one of our tagged released.

cd specify7
git checkout tags/v7.8.6

Tagged releases are coming out every other week and undergo more testing.

See the list of tags to check what's
the latest stable release.

Adjusting 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.

Setting up 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.

python3.8 -m venv specify7/ve
specify7/ve/bin/pip install wheel
specify7/ve/bin/pip install --upgrade -r specify7/requirements.txt

Building

To build Specify 7 use the default make target.

cd specify7
source ve/bin/activate
make

Note, if source command is not available on your system, try running
. ve/bin/activate instead

Other make targets:

make build

Runs all necessary build steps.

make frontend

Installs or updates Javascript dependencies and builds the Javascript modules
only.

make clean

Removes all generated files.

The following targets require the virualenv to be activated:

make pip_requirements

Install or updates Python dependencies.

make django_migrations

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_NAME and MASTER_PASSWORD settings to the
MySQL root user will allow the changes to be applied. Afterward, the master user
settings can be restored.

make runserver

A shortcut for running the Django development server.

make webpack_watch

Run webpack in watch mode so that changes to the frontend source code will be
automatically compiled. Useful during the development process.

Turning on debugging

For development purposes, Django debugging should be turned on. It will enable
stack traces in responses that encounter exceptions, and allow operation with
the unoptimized Javascript files.

Debugging can be enabled by creating the file
specify7/specifyweb/settings/debug.py with the contents, DEBUG = True.

The development server

NOTE: development server should only be run in debug mode. See previous
section for instructions on how to turn on debugging.

Specify7 can be run using the Django development server.

cd specify7
source ve/bin/activate
make runserver

This will start a development server for testing purposes on localhost:8000.

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.

The Specify 7 Worker

Starting from version v7.6.0, the Specify WorkBench utilizes this dedicated
worker process to handle the upload and validation operations.

Starting from version v7.9.0, the record merging functionality employs the
worker to handle all record merging activities.

This worker process utilizes
Celery, a job queue
management system, with
Redis
serving as the broker.

The worker process can be started from the commandline by executing:

cd specify7
celery -A specifyweb worker -l INFO --concurrency=1

For deployment purposes it is recommended to configure a systemd unit to
automatically start the Specify 7 worker process on system start up by executing
the above command within the installation directory. It is possible to run Redis
and worker process on a separate server and to provision multiple worker
processes for high volume scenarios. Contact the Specify team about these use
cases.

Installing production requirements

For production environments, Specify7 can be hosted by Apache. The following
packages are needed:

• Apache
• mod-wsgi to connect Python to Apache

Ubuntu:

sudo apt-get install apache2 libapache2-mod-wsgi-py3

CentOS / Red Hat:

yum install httpd python3-mod_wsgi

Warning: This will replace the Python 2.7 version of mod-wsgi that was used by
Specify 7.4.0 and prior. If executed on a production server running one of those
versions, Specify 7 will stop working until the new deployment is configured.

Setting up Apache

In the specify7 directory you will find the specifyweb_apache.conf file.
Make a copy of the file as local_specifyweb_apache.conf and 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 and make a link to your
local_specifyweb_apache.conf file.

Ubuntu:

sudo rm /etc/apache2/sites-enabled/000-default.conf
sudo ln -s $(pwd)/specify7/local_specifyweb_apache.conf /etc/apache2/sites-enabled/

CentOS / Red Hat:

sudo ln -s $(pwd)/specify7/local_specifyweb_apache.conf /etc/httpd/conf.d/

Restarting Apache

After changing Apache's config files restart the service.

Ubuntu:

sudo systemctl restart apache2.service

CentOS / Red Hat:

sudo systemctl restart httpd.service

Nginx configuration

Specify 7 is web-server agnostic. Example
nginx.conf
(note, you would have to adjust the host names and enable HTTPs).

Updating Specify 7

Specify 7.4.0 and prior versions were based on Python 2.7. If updating from one
of these versions, it will be necessary to install Python 3.8 by running the
apt-get commands in the
Install system dependencies and the
Production requirements steps. Then proceed as
follows:

0. Backup your Specify database using MySQL dump or the Specify backup and
   restore tool.

1. Clone or download a new copy of this repository in a directory next to your
   existing installation.

   git clone https://github.com/specify/specify7.git specify7-new-version

2. Copy the settings from the existing to the new installation.

   cp specify7/specifyweb/settings/local* specify7-new-version/specifyweb/settings/

3. Make sure to update the THICK_CLIENT_LOCATION setting in
   local_specify_settings.py, if you are updating the Specify 6 version.

4. Update the system level dependencies by executing the apt-get command in
   the Installing system dependencies
   section.

5. Create a new virtualenv for the new installation by following the
   Python Virtual Environment section for the new
   directory.

6. Build the new version of Specify 7.

7. Test it out with the development server.

8. Deploy the new version by updating your Apache config to replace the old
   installation paths with the new ones and restarting Apache.

9. Configure the Specify 7 worker process to execute at system start up as
   described in The Specify 7 worker section.

Updating the database (Specify 6) version

The Specify database is updated from one version to the next by the Specify 6
application. To update the database version connect to the database with a new
version of Specify 6 and follow the Specify 6 update procedures.

Once the database version is updated, a corresponding copy of Specify 6 must be
provided to the Specify 7 server by repeating the
Installing Specify 6 section of this guide for the new
version of Specify 6.

Localizing Specify 7

Specify 7 interface is localized to a few languages out of the box. We welcome
contributions of new translations. We are using
Weblate continuous
localization platform.
Instructions on how you can contribute