Specify 7 and Web Portal in Docker

[DEPRECATED]
This repository is no longer maintained.
Please contact Specify support at "[email protected]" for up-to-date Docker deployment options.

Dockerized version of Specify 7.5.0 and Web Portal 2.0.

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

Specify 7 Copyright © 2020 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 and Web Portal in Docker
  • Table of Contents
  • Installation
  • How to report problems and get support?
  • How to toggle debugging in Specify 7?
  • Upgrading to a newer version of Specify 7
  • Troubleshooting
  • TODOs

Installation

• Install Docker Desktop (macOS, Linux, Windows) and make sure it is running.

• Download this repository:

  1. You can either press the button at the top right corner of this page and then press Download ZIP, unzip the downloaded file and place it into a convenient location.
  2. OR install Git, open terminal, navigate to a convenient location and run the following command.

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

• If you want to use your own database with specify7, replace data/database.sql with an export of your database. Be sure to name it database.sql. Instructions on how to create a backup of your database can be found here.

• If you want to use your own data for Web Portal, replace data/export.zip with your export file. Be sure to name it export.zip. You can use the Specify Data Export tool to create a Web Portal export zip file (see the Specify 6 Data Export documentation).

• [For Windows hosts only] Follow these instructions in order to avoid getting Drive-related error messages:

  1. Press on the arrow-shaped button in your Start Menu.
  2. Find the docker logo and click on it.
  3. Select Settings in the list of options.
  4. Press on the Resources tab.
  5. Press on the File Sharing submenu.
  6. Select the drive where your specify7-docker folder is located (It is drive C in most cases).
  7. Press Apply & Restart and wait for Docker to fully reboot (as shown by the indicator in the lower-left corner of the window).

• Build the Docker image and start the container:

  1. Open the terminal (or Command Prompt) in the specify7-docker folder (use cd specify7-docker to open the directory).
  2. Run the docker-compose up -d command (you may need to run this command as a root user depending on the system).
  3. The building process would take about 15 minutes.

Specify 7 instance should now be available at http://localhost:8080. The login for the default database is demouser and the password is also demouser.

Web Portal instance should be available at http://localhost:80.

You can build containers without Specify7. In such a case, you can comment out respected sections for mariadb and specify7 in docker-compose.yml as well as the networks part.

You can build containers without Web Portal. In such case, you can comment out the webportal section in docker-compose.yml.

If you want to run Specify7 with a local SQL server, follow these instructions. We recommend doing that when Docker container would be used in production systems.

• To stop the container:

    docker-compose stop

• To destroy the container:

    docker-compose down

• To rebuild the container:

    docker-compose up -d --build

  You will have to rebuild the container after new release of Specify 6 or after making any changes to files in the ./data or ./specify7_config directories for those changes to be reflected.

How to report problems and get support?

If you have problems with building containers or have any questions, please open an issue in this repository or send an email to [email protected]. It would help us in solving your issues if you were to attach the output of all the commands you run in the terminal/command prompt.

How to toggle debugging in Specify 7?

Open your terminal/command line and execute the following command to enable debugging (you may need to run these commands as a root user depending on the system):

docker exec -it specify7-docker_specify7_1 cp /usr/local/specify_config/enable_debug.py /usr/local/specify7/specifyweb/settings/debug.py
docker restart specify7-docker_specify7_1

And this one to disable debugging:

docker exec -it specify7-docker_specify7_1 cp /usr/local/specify_config/disable_debug.py /usr/local/specify7/specifyweb/settings/debug.py
docker restart $specify7-docker_specify7_1

Replace specify7-docker_specify7_1 with the name of your specify7 container. You can see it in the Docker Dashboard.

Upgrading to a newer version of Specify 7

To run a newer version of Specify7 make sure the database you want to connect to has been upgraded to the new version of Specify. Then, run the following commans

• Pull the changes from the GitHub repository:

    git pull

• Rebuild the container:

    docker-compose up -d --build

Troubleshooting

• If you get the following error: ERROR: Service 'mariadb' failed to build: Get https://registry-1.docker.io/v2/library/mariadb/manifests/latest: unauthorized: incorrect username or password, run docker logout in the command line.

TODOs

• Right now, Specify7 container has an Apache webserver, Web Portal container uses Nginx and Web Asset Server is running Bottle. Ideally, there should be a separate container for Nginx, and Specify 7, Web Asset Server, and Web Portal should all connect to it.

• We can uninstall most of the packages from the Specify7 and Web Portal containers after the build process is over in order to reduce container size