Installation

1. Install compiled PhyloSuite

Installers for all platforms can be downloaded from https://github.com/dongzhang0725/PhyloSuite/releases.

1.1. Windows

Windows 7, 8 and 10 are supported, just double click the PhyloSuite_xxx_win_setup.exe to install, and run “PhyloSuite.exe” file after the installation. If the installation fails, download PhyloSuite_xxx_Win64/32.rar, unzip it, and run PhyloSuite directly from this folder.

1.2. Mac OSX or Linux

Unzip PhyloSuite_xxx_Mac.zip/PhyloSuite_xxx_Linux.tar.gz to anywhere you like, and double click “PhyloSuite” (in PhyloSuite folder) to start, or use the following command:

1 2	cd [PhyloSuite_installation_path]/PhyloSuite ./PhyloSuite

If you encounter an error of “permission denied”, try to use the following command:

1	bash [PhyloSuite_installation_path]/assign_permission.sh

Note that both 64 bit and 32 bit Windows is supported (Windows 7 and above), whereas only 64 bit has been tested in Linux (Ubuntu 18.04.6 LTS) and Mac OSX (macOS Sierra version 10.12.3 and above).
We strongly encourage you to use conda, docker or singularity to install PhyloSuite in Linux (see section 3 and 4), especially for version 1.2.3 and upper.

2. Install using pip

First, Python (version 3.6) should be installed and added to the environment variables in your computer. Then open the terminal and type:

1	pip install PhyloSuite==1.2.3rc4

It will take some time to install. If it installs successfully, PhyloSuite will be automatically added to the environment variables. Then open the terminal again and type:

1	PhyloSuite

3. Install using conda

First, Miniconda3 (https://docs.conda.io/en/latest/miniconda.html) should be installed and added to the environment variables in your computer. Then open the terminal and create an evironment for python 3.6:

1	conda create -n py367 python=3.6.7

Now you can install PhyloSuite using “py367” environment:

1 2	conda activate py367 pip install PhyloSuite==1.2.3rc4

It will take some time to install. If it installs successfully, PhyloSuite will be installed into the [Miniconda_installation_path]/envs/py367/bin folder and will be automatically added to the environment variables. Then open the terminal again and type:

1 2	conda activate py367 # execute this if you are not in py367 environment PhyloSuite

4. Install all-in-one PhyloSuite virtual environment

4.1. What are the advantages of using PhyloSuite virtual environment

All plugins are pre-configured and can be directly used.
You can run the PhyloSuite interface in the background, i.e. you can close the VNCViewer window and reconnect to it anytime you wish.

4.2. Install using Docker

4.2.1. Docker configuration and run

First, Docker (https://www.docker.com/) should be installed and added to the environment variables in your computer.

Then pull the all-in-one PhyloSuite image using the following command:

1	docker pull dongzhang0725/phylosuite:1.2.3rc4

Note that 1.2.3rc4 is the version number of PhyloSuite, you can change it according to your requirements. For all versions, see https://hub.docker.com/repository/docker/dongzhang0725/phylosuite/tags.

Change to a folder where you want to store your working files and results of PhyloSuite, and then create a docker container and run PhyloSuite using the above pulled image:

1
2

cd [PhyloSuite_work_folder] # change to a folder that PhyloSuite works on
docker run -u $(id -u):$(id -g) -v /etc/group:/etc/group:ro -v /etc/passwd:/etc/passwd:ro -d -v $HOME:$HOME -w $PWD --net=host dongzhang0725/phylosuite:1.2.3rc4 bash -c "export DISPLAY=:105; bash vncserver.sh PASSWORD=phylsuit VNC_PORT=6123 RUN=start; bash PhyloSuite.sh"

Note that for PASSWORD option, a password with more than 8 characters is not allowed.

Once docker run command is finished, it will generate a container ID (4aa09be44c8325ebff6eaadc9bcd8931af999b4ff24917be09250812b66fbe88 in the figure below), which may be useful for downstream steps.

Now PhyloSuite is running in the background, you need to use VNCViewer to view it, see below for more details.

4.2.2. View PhyloSuite using VNCViewer

To view PhyloSuite interface, users need to download and install VNCViewer at https://www.realvnc.com/en/connect/download/viewer/linux/. Here we took Standalone x64 Linux version as an example:

1	./VNC-Viewer-6.22.826-Linux-x64

Follow the steps below to enter the session:

Note that 6123 in the first step is corresponding to the port number that we set in VNC_PORT=6123 of the docker run command. In the same step, we also set the password: PASSWORD=phylsuit.

If all steps were successful, you will see an interface like this:

If you failed, you need to check the log of your container using:

1	docker logs -ft --tail 20 4aa09be44c8325ebff6eaadc9bcd8931af999b4ff24917be09250812b66fbe88

Note that the ID at the end of the command corresponds to that generated in the docker run command, so you need to replace it with yours. If you forgot the ID, you can check it using the docker ps command.

If you get the A VNC server is already running as :105 error in your log, try to change export DISPLAY=:105 to another display number in your docker run command, such as export DISPLAY=:106.

If you get the ListenOnTCPPort: Address already in use error in your log, try to change VNC_PORT=6123 to another port number (allowed from 5900 to 65536) in your docker run command, such as VNC_PORT=6124.

4.2.3. How to find the results that PhyloSuite generated?

All results will be available in the current directory of your local system, in the workplace folder that you set when start PhyloSuite.

4.2.4. How to stop PhyloSuite and clean the docker container？

First close PhyloSuite interface, then kill the VNC server using:

1	docker exec -d -u $(id -u):$(id -g) 4aa09be44c8325ebff6eaadc9bcd8931af999b4ff24917be09250812b66fbe88 bash -c "export DISPLAY=:105; bash vncserver.sh PASSWORD=phylsuit VNC_PORT=6123 RUN=stop"

Kill the docker container if it is running:

1	docker kill 4aa09be44c8325ebff6eaadc9bcd8931af999b4ff24917be09250812b66fbe88

Finally clean the container:

1	docker container prune

4.3. Install using Singularity

First, Singularity (https://docs.sylabs.io/guides/3.0/user-guide/index.html or https://singularity-tutorial.github.io/01-installation/) should be installed and added to the environment variables in your computer.

Then pull the all-in-one PhyloSuite image using the following command:

1	singularity -d build phylosuite.simg docker://dongzhang0725/phylosuite:1.2.3rc4

Then use the following command to run PhyloSuite:

1	singularity exec ./phylosuite.simg bash -c "bash PhyloSuite.sh"

If you want to use VNCViewer to view PhyloSuite, run:

1	singularity exec ./phylosuite.simg bash -c "export DISPLAY=:105; bash vncserver.sh PASSWORD=phylsuit VNC_PORT=6123 RUN=start; bash PhyloSuite.sh"

Other operations are the same as above.

If the above pip, conda, docker or singularity commands failed to install PhyloSuite, you can use compiled PhyloSuite (see section 1) or find and download the source codes here (https://pypi.org/project/PhyloSuite/#files or https://github.com/dongzhang0725/PhyloSuite), and install it manually.