Installation of a new BIIGLE instance
This guide describes how to install BIIGLE on a new machine.
This is an example setup of a machine that should run BIIGLE. It is based on a clean install of Ubuntu 20.04 with the user
sudo apt update && sudo apt upgrade.
Install Docker. If you are in a cloud environment, add the repository like this so it is not deleted when a new machine is booted:
echo "deb [arch=amd64] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list
sudo usermod -aG docker ubuntuto add the ubuntu user to the docker group.
Install Docker Compose as a Docker container.
Log out of the machine and back in.
Now you can follow the installation instructions below to install BIIGLE on the machine.
Perform these steps on the machine that should run BIIGLE.
biigle/biiglerepository to the directory where BIIGLE should be installed (e.g.
Create a user for BIIGLE and find out the user and group ID:
$ sudo useradd biigle -U $ id -u biigle <user_id> $ id -g biigle <group_id>
Change the owner of the
sudo chown -R biigle:biigle storage/
Now set the configuration variables in
Now set the build configuration variables in
GITHUB_OAUTH_TOKENis an OAuth token of your GitHub account (with the
APP_KEYis the secret encryption key. Generate one with:
head -c 32 /dev/urandom | base64. Then set
https://<your_domain>. For a local setup without SSL (see below), use
PUSHER_APP_SECRETshould be a random string. Generate one with
pwgen 20 1.
ADMIN_EMAILis the email address of the administrator(s) of the application.
Put the SSL keychain (
fullchain.pem) and private key (
certificate/. See here for a description of the required contents of the keychain file. For a local setup no SSL certificate may be required. Update the
docker-compose.yamlas described by the comments in this case.
Now build the Docker images for production:
cd build && ./build.sh. You can build the images on a separate machine, too, and transfer them to the production machine using
build.shalso supports an optional argument to specify the version tag of the Docker images to build (e.g.
v2.8.0). Default is
Go back and run the containers:
cd .. && docker compose up -d.
Apply the database migrations:
Create the first user:
The default configuration of the production setup includes a
local storage disk that can be used to store images and videos for new volumes (in
build/config/filesystems.php). You can configure more storage disks as well. These storage disks are then offered as an alternative to remote volumes in BIIGLE.
Storage disks must be explicitly allowed for different user roles in BIIGLE. By default, only instance admins are allowed to use the
local storage disk for new volumes. This can be changed with the
VOLUME_EDITOR_STORAGE_DISKS variables in the
build/.env file. Each variable contains a comma-separated list of storage disk names that should be allowed for the respective user role. If the variable is empty, no storage disk is allowed.