CanDIGv2 Install Guide
These instructions work for server deployments or local deployments. For local OSX using M1 architecture, there are modification instructions in the install-os-dependencies-Apple Silicon section. For WSL you can follow the linux instructions and follow WSL instructions for firewall file at update firewall.
Docker Engine (also known as Docker CE) is recommended over Docker Desktop for linux installations. Docker Desktop works well on Mac installations.
Resource requirements
We have successfully run and installed the CanDIGv2 stack on VMs with 4 CPUs and 8GB of memory.
We recommend giving Docker at least 4 CPUs and 4GB of memory.
Dependencies
Select one of the operating systems below to install the dependencies required for CanDIG.
- Update system/install dependencies
sudo apt update && \ sudo apt dist-upgrade -y && \ sudo apt autoclean && \ sudo apt autoremove -y
sudo apt install -y git-core build-essential
yq >= 4 is required. See https://github.com/mikefarah/yq/#install for install options.
- Install Docker
# remove old versions (optional)sudo apt-get remove docker docker-engine docker.io \ containerd runc
sudo apt-get install \ apt-transport-https \ ca-certificates \ curl \ gnupg2 \ software-properties-common
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -sudo add-apt-repository \ "deb [arch=amd64] https://download.docker.com/linux/debian \ $(lsb_release -cs) \ stable"
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $(whoami)
- Update system/install dependencies
sudo apt-get update
sudo apt-get install \ apt-transport-https \ ca-certificates \ curl \ gnupg2 \ software-properties-common \ apt-transport-https \ ca-certificates curl \ software-properties-common \ make \ gcc
yq >= 4 is required. The apt version is outdated. So:
sudo apt install snapdsudo snap install yq
- Install Docker
Follow the official Docker directions. Installation using the apt repository method is recommended.
Set docker to run as a service on startup.
sudo systemctl enable docker
sudo systemctl start docker
You may have to reboot (not just log out).
Add yourself to the docker group rather than use sudo all the time.
sudo usermod -aG docker $(whoami)
You may have to log out or restart your shell for this setting to take effect.
Verify that you are a member of the docker
group with:
groups# orgetent group docker
- Update system/install dependencies
sudo yum update
sudo yum install -y git-core
sudo yum groupinstall -y 'Development Tools'
- Install Docker
# remove old versions (optional)sudo yum remove -y docker \ docker-client \ docker-client-latest \ docker-common \ docker-latest \ docker-latest-logrotate \ docker-logrotate \ docker-engine
sudo yum install -y yum-utils \ device-mapper-persistent-data \ lvm2
sudo yum-config-manager -y \ --add-repo \ https://download.docker.com/linux/centos/docker-ce.repo
sudo yum update
sudo yum install -y docker-ce docker-ce-cli containerd.io
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $(whoami)
yq >= 4 is required. See https://github.com/mikefarah/yq/#install for install options.
Miniconda3 must be installed at ~/miniconda3
on WSL systems to avoid an infinite symlink loop. Add CONDA_INSTALL = ~/miniconda3
above CONDA = $(CONDA_INSTALL)/bin/conda
in the Makefile to avoid this issue. You can also use the below command to move the miniconda3 installation to the correct location.
bash bin/miniconda_install.sh -f -b -u -p ~/miniconda3
yq >= 4 is required, but the conda version is outdated. Install the latest version system-wide by following the instructions at the yq GitHub.
- Install OS Dependencies
- Install dependencies
brew install gettextbrew link --force gettextbrew install jqbrew install yq
- Get Docker Desktop for Apple Silicon. Be sure to start it.
Production vs Development Environments
CanDIG can be installed and deployed as below for development situations where no real data will ever be ingested into the system. For critical differences in production deployments, please see the Guide to CanDIG production deployments.
Initialize CanDIGv2 Repo
If you haven’t done so already
1. Initialize repo and submodules
git clone -b develop https://github.com/CanDIG/CanDIGv2.gitcd CanDIGv2git submodule update --init --recursive
2. Copy and edit .env with your site’s local configuration
cp -i etc/env/example.env .env
Update any of the information you want or need to customize including:
# find out your ip and add to LOCAL_IP_ADDRLOCAL_IP_ADDR=xxx.xx.x.x# change OSVENV_OS=<your OS>
More info about the .env
Environment File
You need an .env
file in the project root directory, which contains a set of global variables that are used as reference to the various parameters, plugins, and config options that operators can modify for testing purposes. This repo contains an example .env
file in etc/env/example.env
.
For a basic desktop sandbox setup, the example variable file needs very little (if any) modification.
When deploying CanDIGv2
using make
, .env
is imported by make
and all uncommented variables are added as environment variables via
export
.
Some of the functionality that is controlled through .env
are:
- operating system flags
- change docker network, driver, and swarm host
- modify ports, protocols, and plugins for various services
- version control and app pinning
- pre-defined defaults for turnkey deployment
Environment variables defined in the .env
file can be read in docker-compose
scripts through the variable substitution operator
${VAR}
.
# example compose YAML using variable substitution with default optionservices: consul: image: progrium/consul network_mode: ${DOCKER_MODE}...
3.a: install miniconda and initialize candig virtualenv
Use this option for systems installations. It installs miniconda in the candigv2 repo.
make bin-conda # If this fails on WSL, see the Note for WSL Systems section abovemake init-conda
3.b: Use an existing Conda installation
If you want to use an existing conda installation on your local at the bottom of the .env, set CONDA_INSTALL
to your existing conda installation path
make mkdir # skip most of bin-conda, but need the dir-creating stepmake init-conda
4. Activate the candig virtualenv. It may be necessary to restart your shell before doing this
conda activate candig
Configuring CanDIG modules
Not all CanDIG modules are required for a minimal installation. The CANDIG_MODULES
setting defines which modules are included in the deployment.
By default (if you copy the sample file from etc/env/example.env
) the installation includes the minimal list of modules:
CANDIG_MODULES=logging keycloak vault redis postgres htsget katsu query tyk opa federation candig-ingest candig-data-portal
Optional modules follow the #
and include various monitoring components, workflow execution, and some older modules not generally installed.
Build and compose all the modules
Use the make command build-all
to build and compose all the CanDIG modules
make build-all
If you can see the data portal at http://candig.docker.internal:5080/ (or your configured $CANDIG_DOMAIN
), your installation was successful!
Try logging in with one of the @test.ca
usernames from env.sh
:
export CANDIG_SITE_ADMIN_USER=site_admin@test.caexport CANDIG_SITE_ADMIN_PASSWORD=<auto generated password>export CANDIG_NOT_ADMIN_USER=user1@test.caexport CANDIG_NOT_ADMIN_PASSWORD=<auto generated password>export CANDIG_NOT_ADMIN2_USER=user2@test.caexport CANDIG_NOT_ADMIN2_PASSWORD=<auto generated password>
Confirm your deployment was successfuly the automatic integration tests:
make test-integration
If all the tests pass, well done! You have a functional CanDIG stack!
Next up, you might like to take a look at the documentation for ingesting data as well as Interacting with the stack using Make and if you are a developer: how to modify code and test changes in the context of the CanDIG stack.
Troubleshooting
Below are some common issues that our users have encountered. If you run into any other issues not addressed here, please reach out via a github issue in this repo.
On some machines (MacOS), if you get an error something like:
Please ensure the value of $CANDIG_DOMAIN in your .env file points to this machineThis should either be: 1) your local IP address, as assigned by your local network, or2) a domain name that resolves to this IP address
it may be necessary to add the following to /etc/hosts
:
In a terminal, run the following commands
sudo nano /etc/hosts
Then add the following line at the bottom of the file and save the changes:
::1 candig.docker.internal
In some other cases, it may be necessary to add your local/internal (network) IP manually, if the build process complains that it could not find the right IP (ERROR: Your internet adapter could not be found automatically.
or ERROR: More than one IP has been detected.
). In this case, find out what your local IP address is
# on macifconfig en0 | awk '$1 == "inet" {print $2}'# on linuxip route | awk -F\ '/default/ {print $9}'
Then edit your .env file with:
LOCAL_IP_ADDR=<your local IP>
Where <your local IP>
is your local network IP (e.g. 192.168.x.x, or another reserved IP address.)
Update Firewall
If the command still fails, it may be necessary to disable your local firewall, or edit it to allow requests from all ports used in the Docker stack.
Edit your firewall settings to allow connections from those adresses:
export DOCKER_BRIDGE_IP=$(docker network inspect bridge | grep Subnet | awk '{print $2}' | tr -d ',')sudo ufw allow from $DOCKER_BRIDGE_IP to <your ip>
Re-run make clean-authx
and make init-authx
and it should work.