Installation of a new BIIGLE instance
This guide describes how to install BIIGLE on a new machine.
Setup
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 ubuntu
.
-
Run
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
-
Run
sudo usermod -aG docker ubuntu
to 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.
Installation
Perform these steps on the machine that should run BIIGLE.
-
Clone the
biigle/biigle
repository to the directory where BIIGLE should be installed (e.g./mnt/biigle
or/var/biigle
). -
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
storage
directory:sudo chown -R biigle:biigle storage/
-
Move
.env.example
to.env
. -
Now set the configuration variables in
.env
:USER_ID
should be<user_id>
.GROUP_ID
should be<group_id>
.
-
Move
build/.env.example
tobuild/.env
. -
Now set the build configuration variables in
build/.env
:GITHUB_OAUTH_TOKEN
is an OAuth token of your GitHub account (with therepo
andread:packages
scopes).APP_KEY
is the secret encryption key. Generate one with:head -c 32 /dev/urandom | base64
. Then setAPP_KEY=base64:<your_key>
.APP_URL
ishttps://<your_domain>
. For a local setup without SSL (see below), usehttp://localhost
.MIX_PUSHER_APP_HOST
should be<your_domain>
(withouthttps://
, see above).MIX_PUSHER_APP_TLS
should be changed tofalse
if you use a local setup without SSL.PUSHER_APP_SECRET
should be a random string. Generate one withpwgen 20 1
.ADMIN_EMAIL
is the email address of the administrator(s) of the application.
-
Put the SSL keychain (
fullchain.pem
) and private key (privkey.pem
) tocertificate/
. See here for a description of the required contents of the keychain file. For a local setup no SSL certificate may be required. Update theweb
service indocker-compose.yaml
as 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 usingdocker save
anddocker load
.build.sh
also supports an optional argument to specify the version tag of the Docker images to build (e.g.v2.8.0
). Default islatest
. -
Go back and run the containers:
cd .. && docker compose up -d
. -
Apply the database migrations:
./artisan migrate
. -
Create the first user:
./artisan user:new
.
Configuration
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_ADMIN_STORAGE_DISKS
and 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.