nzilbb/labbcat repository overview

⁠What is LaBB-CAT?

LaBB-CAT⁠ is a browser-based linguistics research tool that stores audio or video recordings, text transcripts, and other annotations.

Annotations of various types can be automatically generated or manually added.

The transcripts and annotations can be searched for particular text or regular expressions. The search results, or entire transcripts, can be viewed or saved in a variety of formats, and the related parts of the recordings can be played or opened in acoustic analysis software, all directly through the web-browser.

⁠How to use this image

This image contains the LaBB-CAT web application, but does not contain MySQL for database storage. So this image must be run in combination with a MySQL server.

The simplest way to use this image is in combination with a dedicated mysql/mysql-server⁠ image:

docker run --name=labbcat-db -e MYSQL_ROOT_PASSWORD=secret -e MYSQL_ROOT_HOST=% -d mysql/mysql-server:5.6 --character-set-server=utf8mb4 --collation-server=utf8mb4_general_ci
docker run --name=labbcat --link labbcat-db -d -p 8888:8080 nzilbb/labbcat

This will make LaBB-CAT available via http://hostname:8888/⁠

NB It can take up to 10 seconds for the web app to become available when first installing.

The image is password protected; the labbcat user has a default password of labbcat

⁠Environment variables

This image supports the following optional environment variables:

• MYSQL_ROOT_USER : (default is root) a MySQL user that can be used to create the database and the database user.
• MYSQL_ROOT_PASSWORD : (default is the value of MYSQL_ROOT_PASSWORD passed to the mysql/mysq-server container) the password for the MySQL root user, for creating the database and database user
• MYSQL_HOST : (default is labbcat-db) the host name of the MySQL server.
• MYSQL_DATABASE : (default is labbcat) the name of the LaBB-CAT database.
• MYSQL_USER : (default is labbcat) the name of the LaBB-CAT database user.
• MYSQL_PASSWORD : (default is a random string) the password of the LaBB-CAT database user.
• LABBCAT_BASE_URL : (default is based on the client's http requests) the apparent base URL for the web app, for stylesheets, scripts, menu links, etc. (with no trailing slash), for cases where the client-visible URL is different from the apparent URL from inside the container; e.g. if it's running behind a reverse-proxy.
• LABBCAT_REDIRECT_REWRITE : (default is blank) the fragment of the LABBCAT_BASE_URL that should be removed when LaBB-CAT sends HTTP 302 redirect responses, for cases where a reverse proxy that's part of the container infrastructure rewrites the Location header of such responses, and this rewriting causes doubling of part of the URL path.

e.g. if the MySQL database is running on server 'my.sql.server.org' with a root password of 'open-sesame', then the LaBB-CAT container should be run with:

docker run --name=labbcat -e MYSQL_HOST=my.sql.server.org -e MYSQL_ROOT_PASSWORD=open-sesame -d -p 8888:8080 nzilbb/labbcat

⁠Pre-existing database/user

If MYSQL_ROOT_PASSWORD is blank and MYSQL_PASSWORD is not blank, then LaBB-CAT assumes that the MySQL server already has a blank database, created with a command like:

CREATE DATABASE IF NOT EXISTS labbcat CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

...and that the MySQL server already has a user, created with commands like:

CREATE USER 'labbcat'@'%' IDENTIFIED BY 'secret';
GRANT ALL PRIVILEGES ON labbcat.* TO 'labbcat'@'%';
GRANT PROCESS ON *.* TO 'labbcat'@'%';

These preconditions can be set up directly in the docker command that runs the mysql/mysql-server container, from which the nzilbb/labbcat container can infer the details:

docker run --name=labbcat-db -e MYSQL_DATABASE=labbcat -e MYSQL_USER=labbcat -e MYSQL_PASSWORD=secret -d mysql/mysql-server:5.6 --skip-log-bin --character-set-server=utf8mb4 --collation-server=utf8mb4_general_ci
docker run --name=labbcat --link labbcat-db -d -p 8888:8080 nzilbb/labbcat

Alternatively, the environment variables can be specified in a file, e.g. if the file database.txt has the following contents:

MYSQL_DATABASE=labbcat
MYSQL_USER=labbcat
MYSQL_PASSWORD=sesame

...then the containers can be run thusly:

docker run --name=labbcat-db --env-file database.txt -d mysql/mysql-server:5.6 --skip-log-bin --character-set-server=utf8mb4 --collation-server=utf8mb4_general_ci
docker run --name=labbcat --link labbcat-db -d -p 8888:8080 nzilbb/labbcat

⁠Mounting an external directory for persistent files

This image saves a copy of uploaded transcripts and media, and installed module configuration files in /labbcat/files.

An external directory can be mounted to this directory to facilitate backup / image update:

docker run -v /path/to/external/directory:/labbcat/files ...