Skip to content

Commit

Permalink
update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
biologger committed Apr 30, 2020
1 parent 9b48545 commit 0f5b071
Showing 7 changed files with 176 additions and 112 deletions.
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -31,13 +31,14 @@ New in SpeciesPrimer v2.2
* [Citation](https://github.com/biologger/speciesprimer/tree/master#citation)

## Docs
* [Table of contents](https://github.com/biologger/speciesprimer/tree/speciesprimerv2.2/docs/tableofcontents.md)
* [Pipeline and Docker tutorial](https://github.com/biologger/speciesprimer/tree/speciesprimerv2.2/docs/tutorial.md)
* [Advanced command line usage](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/cmdlineonly.md)
* [Pipeline setup](https://github.com/biologger/speciesprimer/tree/speciesprimerv2.2/docs/pipelinesetup.md)
* [Primerdesign](https://github.com/biologger/speciesprimer/tree/speciesprimerv2.2/docs/primerdesign.md)
* [Troubleshooting](https://github.com/biologger/speciesprimer/tree/speciesprimerv2.2/docs/troubleshooting.md)
* [Custom BLAST DB tutorial](https://github.com/biologger/speciesprimer/tree/speciesprimerv2.2/docs/customdbtutorial.md)
* [More troubleshooting (Docker)](https://github.com/biologger/speciesprimer/tree/speciesprimerv2.2/docs/dockertroubleshooting.md)
* [Advanced command line usage](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/cmdlineonly.md)
* [Troubleshooting Docker](https://github.com/biologger/speciesprimer/tree/speciesprimerv2.2/docs/dockertroubleshooting.md)
* [Docker and proxy settings](https://github.com/biologger/speciesprimer/tree/speciesprimerv2.2/docs/dockerproxy.md)

## Minimum system requirements
78 changes: 38 additions & 40 deletions docs/dockertroubleshooting.md
Original file line number Diff line number Diff line change
@@ -15,7 +15,7 @@
|docker attach \{container\} | attach to a container terminal |
|docker exec -it \{container\} bash | open a new terminal in a running container |

#### Conflict with the container name or with the ports
#### Conflict with container name or port
"docker: Error response from daemon: Conflict. The container name "/speciesprimer_pipeline" is already in use by container "e9d0de003ce8eff06b34f8f46e4934797052e16dcdbd7e60214d05ea3828a70", You have to remove (or rename) that container to be able to reuse that name"

or
@@ -24,20 +24,20 @@ or

1. Display your containers
* __HOST:__

$ sudo docker ps -a

2. Stop the container with the container ID or the container name
*
*

$ sudo docker stop {ContainerID/containername}

3. Delete the container
*
*

$ sudo docker rm {ContainerID/containername}



Now you can try again to create a container with the sudo docker run command

@@ -58,7 +58,7 @@ __Example:__
-v /home/biologger/primerdesign:/primerdesign \
-p 5000:5000 -p 9001:9001 \
--name speciesprimer_pipeline -it biologger/speciesprimer


## Docker setup

@@ -69,37 +69,37 @@ see the docs for installation instructions <https://docs.docker.com/>
### Download images from docker hub

1. Open a terminal:

* __HOST:__

$ sudo docker pull biologger/speciesprimer

2. Now you have the image, you can display the image with

* __HOST:__

$ sudo docker images

3. If there is more than one image from the repository __biologger/speciesprimer__, you can remove the image with the <none\> Tag

* __HOST:__

$ sudo docker rmi {image_id}

### Choose directories

1. Decide which directories (on the host) should be used by the container

* If the pre-formatted nucleotide (nt) database from NCBI is already downloaded and unpacked on your computer, just add the path to the directory in the docker run command (-v path\_to\_host\_blastdb_dir:/blastdb)
* If the pre-formatted nucleotide (nt) database from NCBI is already downloaded and unpacked on your computer, just add the path to the directory in the docker run command (-v path\_to\_host\_blastdb_dir:/blastdb)

* Create a directory for primerdesign and one for the BLAST database

* __Example:__

* Create two new directories in the home directory

* __HOST:__

# one for the primer design files
$ mkdir /home/biologger/primerdesign
# one for the nucleotide blast database
@@ -135,7 +135,7 @@ In the terminal you see that the server in the container was started.
Afterwards you can open the address [http://localhost:5000] or what port you have choosen for {hostport1} in your webbrowser.

#### docker stop
You can shutdown the container by opening a terminal and the command
You can shutdown the container by opening a terminal and the command

$ sudo docker stop {containername/id}

@@ -147,7 +147,7 @@ __Example:__

#### docker start
The next time you do not have to repeat the docker run command (this would create a new container, without your modified settings)
Instead you simply start the container with the command
Instead you simply start the container with the command

$ sudo docker start {containername/id}

@@ -156,7 +156,7 @@ __Example:__
* __HOST:__

$ sudo docker start speciesprimer_pipeline

Afterwards you can open the address [http://localhost:5000] or what port you have choosen for {hostport1} in your webbrowser.

#### docker attach
@@ -169,12 +169,12 @@ __Example:__
* __HOST:__

$ sudo docker attach speciesprimer_pipeline

#### docker exec
If you w to access the container with the terminal you can use (the -it option is for the interactive terminal)

$ sudo docker exec -it {containername/id} bash

__Example:__

* __HOST:__
@@ -189,54 +189,54 @@ __Example:__
* __CONTAINER:__

$ exit


### Test the container

If not already started
If not already started

$ sudo docker start {containername/id}
$ sudo docker start {containername/id}

$ sudo docker exec -it {containername/id} bash

If you see __root@{containerID}:/primerdesign#__ in the terminal, you have now access to the terminal of the container.

Test if you have mounted the volumes correctly
Test if you have mounted the volumes correctly

* __CONTAINER:__

$ echo test > test.txt

* Check if you find test.txt
$ ls -l

$ ls -l

* __HOST:__

* Check if you find test.txt on the host

$ ls -l /home/{linux_username}/primerdesign

If you want to delete this test.txt file there are two options

1. Do it in the container
1. Do it in the container
* __CONTAINER:__

$ rm test.txt

2. Do it on the host
* Change the owner of the files in the primerdesign directory on the host (recursively).

* __HOST:__

$ sudo chown -R {linux_username} {path_to_primerdesign_dir}

* Now you can move and delete the files and directories.

__Example__:

* __HOST:__

$ sudo chown -R biologger /home/biologger/primerdesign

### Time settings
@@ -246,16 +246,14 @@ Run a container with your local time settings
-v $HOME/blastdb:/blastdb -v $HOME/primerdesign:/primerdesign \
--name speciesprimertime -p 5000:5000 -p 9001:9001 -it biologger/speciesprimer

Or in an existing container
Or in an existing container

* __HOST:__

$ sudo docker start {containername/id}
$ sudo docker start {containername/id}

$ sudo docker exec -it {containername/id} bash

* __CONTAINER:__

$ dpkg-reconfigure tzdata


19 changes: 3 additions & 16 deletions docs/pipelinesetup.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
## Pipeline setup

### Download the pre-formatted nucleotide collection (nt) BLAST database from NCBI
### Download a BLAST database from NCBI

If you do not yet have a local copy of the nucleotide collection (nt) BLAST database:
If you do not yet have a local copy of a BLAST database:

In your internetbrowser [http://localhost:5000](http://localhost:5000) Navigate to the BLAST DB link.

To download the database with the update_blastdb perl script just click on the Start download button below. On the next page Click Start Blast DB download. This will download the pre-formatted nt BLAST database from NCBI to your blastdb directory (specified with the docker run command). You can follow the progress by clicking stream log in new tab.
To download the database just click on the Start download button below. On the next page Click Start Blast DB download. This will download the pre-formatted nt or the ref\_prok\_rep_genomes BLAST database from NCBI to your blastdb directory (specified with the docker run command). You can follow the progress by clicking stream log in new tab.

#### Troubleshooting:
The script changes to the "/blastdb" directory in the container and runs the command below
@@ -83,19 +83,6 @@ __Example:__
Pediococcus acidilactici
...

------------------------

### Optional:

### Update the taxid list for the BLAST search with the nt BLAST database Version 5
The taxid list contains all NCBI taxonomic ids for bacteria (NCBI:txid2). From time to time NCBI may add new taxids if new species are added.

As an alternative if the __Entrez EDirect Utility__ and __the BLAST+ command line application__ are installed on the host computer, the __get_species_taxids.sh__ script from the BLAST+ program can be used to create this list.

__Example__

$ get_species_taxids.sh -t 2 > /pipeline/dictionaries/2.txids

------------------------------------------------------
### Abbreviations of genus names
If you wish to use abbreviations of genus names for the pipeline output files,
63 changes: 63 additions & 0 deletions docs/tableofcontents.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
* [Tutorial (Ubuntu 16.04):](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/tutorial.md#tutorial-ubuntu-1604)
* [Docker setup](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/tutorial.md#docker-setup)
* [Download and install docker](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/tutorial.md#download-and-install-docker)
* [Download images from docker hub](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/tutorial.md#download-images-from-docker-hub)
* [Choose directories](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/tutorial.md#choose-directories)
* [Run a container instance](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/tutorial.md#run-a-container-instance)
* [Troubleshooting Docker](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/tutorial.md#troubleshooting-docker)
* [Conflict with the container name](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/tutorial.md#conflict-with-the-container-name)

* [Pipeline setup](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/pipelinesetup.md#pipeline-setup)
* [Download a BLAST database from NCBI](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/pipelinesetup.md#download-a-BLAST-database-from-ncbi)
* [Create a species_list.txt file](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/pipelinesetup.md#create-a-species_listtxt-file)
* [Abbreviations of genus names](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/pipelinesetup.md#abbreviations-of-genus-names)
* [Primer3 settings](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/pipelinesetup.md#primer3-settings)
* [Exclude geneidentifier from BLAST](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/pipelinesetup.md#exclude-geneidentifier-from-blast)

* [Primerdesign](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/primerdesign.md#primerdesign)
* [First run](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/primerdesign.md#first-run)
* [Directory tree](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/primerdesign.md#directory-tree)
* [Using user provided genomes](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/primerdesign.md#using-user-provided-genomes)
* [batchassist.py](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/primerdesign.md#batchassistpy)
* [Additional info blastseqs option](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/primerdesign.md#additional-info-blastseqs-option)

* [Troubleshooting](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#troubleshooting)
* [Report bugs and problems](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#report-bugs-and-problems)
* [GUI trouble](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#gui-trouble)
* [Delete files created by the docker container from the host.](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#delete-files-created-by-the-docker-container-from-the-host)
* [Setting the timezone for the container](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#setting-the-timezone-for-the-container)
* [Troubleshooting pipeline runs](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#troubleshooting-pipeline-runs)
* [Primer quality control](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#primer-quality-control)
* ["fatal error while working on {genus_species} check logfile "](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#fatal-error-while-working-on-genus_species-check-logfile-)
* [Naming of user provided genome assemblies](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#naming-of-user-provided-genome-assemblies)
* [Errors during download of genome assemblies](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#errors-during-download-of-genome-assemblies)
* [Restart / continue stopped pipeline runs](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#restart--continue-stopped-pipeline-runs)
* [Error during quality control of genome assemblies](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#error-during-quality-control-of-genome-assemblies)
* [Only a few core genes are reported](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#only-a-few-core-genes-are-reported)
* [Thousands of primer are reported and primer QC takes forever](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#thousands-of-primer-are-reported-and-primer-qc-takes-forever)
* [Exclude gene identifier (GI) from BLAST results](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#exclude-gene-identifier-gi-from-blast-results)
* [Taxonomic vagueness](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#taxonomic-vagueness)
* [nt BLAST DB / nt BLAST DB version 5](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#nt-blast-db---nt-blast-db-version-5)
* [Problems with BLAST results](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/troubleshooting.md#problems-with-blast-results)

* [Custom DB tutorial](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/customdbtutorial.md#custom-db-tutorial)

* [Advanced command line usage](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/cmdlineonly.md#advanced-command-line-usage)

* [Troubleshooting Docker](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockertroubleshooting.md#troubleshooting-docker)
* [Overview Docker commands](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockertroubleshooting.md#overview-docker-commands)
* [Conflict with container name or port](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockertroubleshooting.md#conflict-with-container-name-or-port)
* [Docker setup](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockertroubleshooting.md#docker-setup)
* [Download and install docker](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockertroubleshooting.md#download-and-install-docker)
* [Download images from docker hub](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockertroubleshooting.md#download-images-from-docker-hub)
* [Choose directories](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockertroubleshooting.md#choose-directories)
* [Run a container instance](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockertroubleshooting.md#run-a-container-instance)
* [Test the container](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockertroubleshooting.md#test-the-container)
* [Time settings](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockertroubleshooting.md#time-settings)

* [Configuration of Docker with DNS and proxy server](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockerproxy.md#configuration-of-docker-with-dns-and-proxy-server)
* [DNS server (Docker daemon)](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockerproxy.md#dns-server-docker-daemon)
* [Proxy server (Docker daemon)](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockerproxy.md#proxy-server-docker-daemon)
* [DNS server (Docker container)](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockerproxy.md#dns-server-docker-container)
* [Proxy server (Docker container)](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockerproxy.md#proxy-server-docker-container)
* [TLS termination (Docker container)](https://github.com/biologger/speciesprimer/blob/speciesprimerv2.2/docs/dockerproxy.md#tls-termination-docker-container)
Loading

0 comments on commit 0f5b071

Please sign in to comment.