Installation
Prerequisites
The only prerequisite is Docker.
See OS-specific (Windows, Mac, Linux) docker installation guidelines below.
Note
Modules of PipeCraft2 are distributed through Docker containers, which will liberate the users from the struggle to install/compile various software for metabarcoding data analyses. Thus, all processes are run in Docker containers. Relevant Docker container will be automatically downloaded prior the analysis.
Warning
Your OS might warn that PipeCraft2 is dangerous software! Please ignore the warning in this case.
Windows
PipeCraft2 was tested on Windows 10 and Windows 11. Older Windows versions do not support PipeCraft GUI workflow through Docker.
Download PipeCraft2 for Windows: v1.0.0
Install PipeCraft2 via the setup executable
Download Docker for windows - ONLY ONCE (no need, when updating PipeCraft)
Warning
In Windows, please keep you working directory path as short as possible. Maximum path length in Windows is 260 characters. PipeCraft may not be able to work with files, that are buried “deep inside” (i.e. the path is too long).
Note
Resource limits for Docker are managed by Windows; but you can configure limits in a .wslconfig file (see Settings -> Resources on your Docker desktop app). Default = 50% of total memory on Windows or 8GB, whichever is less. 80% of total memory on Windows on builds before 20175 (Win10, from 2020).
Quick guide to increase Docker accessible RAM size in Windows
Instructions from https://learn.microsoft.com/en-us/windows/wsl/wsl-config#wslconfig
This is for Windows Build 19041 and later with WSL 2
Open ‘File Explorer’ and type %USERPROFILE% to the address bar to access the %USERPROFILE% directory (generally e.g. “C:Usersmy_user_name”).
Make new text (txt) document into %USERPROFILE% directory.
Paste the following text to that new txt document:
# Settings apply across all Linux distros running on WSL 2
[wsl2]
# Limits VM memory to use no more than X GB, this can be set as whole numbers using GB or MB
memory=30GB
# Sets the VM to use X virtual processors
processors=8
Edit “memory=30GB” and “processors=8” according to your needs
Save the file and rename this as .wslconfig
Restart Docker.
MacOS
PipeCraft2 is supported on macOS 10.15+. Older OS versions might not support PipeCraft GUI workflow through Docker.
Note
If your MacOS has M1/M2 chips, please let us know if you encounter something weird while trying to run some analyses (contact or post an issue on the github page).
Download PipeCraft2 for Mac: v1.0.0
Install PipeCraft2 via pkg file
Currently macOS will flag pipecraft as an app from an unidentified developer. Grant an exception for a blocked app by clicking the “Open Anyway” button in the General panel of Security & Privacy preferences. Installing on latest versions of macOS (13.0+) will require you to disable gatekeeper entirely, to do so paste the following command into a terminal.
Check your Mac chip (Apple or Intel) and download Docker for Mac - ONLY ONCE (no need, when updating PipeCraft)
sudo spctl --master-disable
Open Docker dashboard: Settings -> Resources -> File Sharing; and add the directory where pipecraft.app was installed (it is usually /Appications)
Linux
PipeCraft2 was tested with Ubuntu 20.04 and Mint 20.1. Older OS versions might not support PipeCraft GUI workflow through Docker.
Download PipeCraft2 for Linux: v1.0.0
Right click on the pipecraft_*.deb file and “Open With GDebi Package Installer” (Install Package) or
sudo dpkg -i path_to_deb_file
Install Docker - ONLY ONCE (no need, when updating PipeCraft); follow the guidelines under appropriate Linux distribution
Warning
When installing Docker Engine, make sure you have not Docker Desktop already installed!Installing both might have interfering consequencesIf you are a non-root user complete these post-install steps
Note
When you encounter ERROR during PipeCraft2 installation, then uninstall the previous version of PipeCraft2 sudo dpkg --remove pipecraft-v0.1.3
Run PipeCraft2. If PipeCraft shortcut does not appear on the Desktop, then search the app and generate shortcut manually (installed in /opt/pipecraft directory)
Note
On Linux, Docker can use all available host resources.
Updating PipeCraft2
Auto-updates will be available (hopefully) soon [at least for Windows]!
See removing docker images section.
Warning
Uninstalling PipeCraft2
sudo dpkg --remove pipecraft
Purging ‘old’ Docker installations
sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
rm -r $HOME/.docker/desktop
sudo rm /usr/local/bin/com.docker.cli
sudo apt purge docker-desktop
Removing Docker images
sudo docker images
–> to see which docker images existsudo docker rmi IMAGE_ID
–> to delete selected imageor
sudo docker system prune -a
–> to delete all unused containers, networks, imagessudo docker images
–> check if images were removed