Installing Specify 7 Locally

1) Install required software

VS Code IDE
DBeaver CE
Docker + Docker Compose (plugin)
Git
(Optional) MariaDB/MySQL client-only CLI (no server)

Install client only (no server):

macOS (Homebrew):

brew install mysql-client
echo 'export PATH="/opt/homebrew/opt/mysql-client/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Ubuntu/Debian:

sudo apt-get update && sudo apt-get install -y mariadb-client

(Do NOT install or start a local server. We’ll run the DB in Docker.)

2) Clone the Specify 7 repo

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

git clone checks out the main branch by default.

3) Check out the requested tag

Open a terminal in VS Code (or any shell) and run:

cd specify7
git checkout tags/v7.11.1

4) Python virtual environment + dependencies

Set up a Python venv and install dependencies:

# Create a venv
python3 -m venv specify7/ve

# Activate it (macOS/Linux)
source specify7/ve/bin/activate
# On Windows (PowerShell) use:
# .\specify7\ve\Scripts\Activate.ps1

# Install deps
pip3 install wheel
pip3 install --upgrade -r requirements.txt

The app runs in Docker. This venv is just for helper scripts.

5) Get a seed database

Download a database from the Specify test panel.

Then:

Open the downloaded .sql in an editor.
Remove the line:
```
USE database 'db_name';
```
Save the file.
Move it into the repo under:
```
seed_database/
```

Removing USE ...; avoids importing into the wrong DB name.

6) Configure DBeaver (MySQL/MariaDB)

In DBeaver: Database → New Connection → MySQL (or MariaDB).

Fill exactly:

Server Host: localhost
Port: 3306
Database: DATABASE_NAME
Show all databases: ✅ checked
Username: root
Password: your root password (must match MYSQL_ROOT_PASSWORD below)

Click Test Connection (optional) → Finish.

7) Edit the project `.env`

Open the project’s .env and set:

MYSQL_ROOT_PASSWORD=root_pw_here
DATABASE_NAME=db_name_downloaded_locally
MASTER_NAME=master_name_here
MASTER_PASSWORD=master_pw_here

DATABASE_NAME must match the seed DB you intend to use.
Save the file.

8) Run Specify 7

From the repo root:

docker compose up --build

Open the app:

http://localhost/specify

Login:

Username: i.e spadmin
Password: testuser

Select any collection from the drop-down.

9) Troubleshooting

Access denied / DB not found after `docker compose up --build`

Do this:

In Docker Desktop, delete all containers and images related to this project.

Prune old images/volumes:

# CAUTION: removes unused images/volumes. You will lose local DB volumes.
docker image prune -a
docker volume prune -a

Rebuild:
```
docker compose up --build
```

If needed, verify inside the DB container:

# In Docker Desktop: open the 'mariadb' container → Exec → bash
bash
mysql -uroot -proot     # replace 'root' with your actual MYSQL_ROOT_PASSWORD
SHOW DATABASES;
USE db_name;            # use the same name you set in DATABASE_NAME

Back in VS Code terminal, you can re-run:
```
docker compose up --build
```

DBeaver shows “Unknown database”

Ensure the Database field equals your .env DATABASE_NAME.
Confirm the .sql file didn’t have a USE ...; line.
Make sure the .sql was placed in seed_database/ before the first run.

10) Notes

App URL: http://localhost/specify
Repo: https://github.com/specify/specify7
Common test login: spadmin / test user
If you installed a local MySQL server instead of Docker, mirror the same credentials and DB name in DBeaver and .env.