This is the official Docker image for the [MEME Suite](https://meme-suite.org) collection of tools for motif analysis. 
It is produced by the MEME Suite development team.
The MEME Suite Docker container is available under a limited, non-commercial
use license.  See the [license details](https://meme-suite.org/doc/copyright.html) here.
If you encounter problems with a MEME Suite Docker image, please contact
[meme-suite@uw.edu](mailto:meme-suite@uw.edu).

This Docker image allows you to easily download, install and run a local copy of
- the MEME Suite command line tools AND
- a MEME Suite web server.
The following instructions assume you have installed Docker Desktop on your 
local computer and it is running. We'll cover the instructions for Linux and MacOS
first, and then the instructions for Windows.

******
# For Linux and MacOS
******

## Obtaining the most recent Docker image for the MEME Suite

Type the following command on your computer:

``docker pull memesuite/memesuite:latest``

This will download the latest Docker image for MEME Suite to your computer.
(You can also download <b>previous</b> versions of the MEME Suite by
appending the appropriate tag after `memesuite/memesuite`, e.g., `memesuite/memesuite:5.5.3`.)

******
## Using the MEME Suite command line tools via Docker

Type the following command on your computer:

``docker run -v `pwd`:/home/meme -d memesuite/memesuite:latest``

This will start a Docker container using the latest Docker image for MEME Suite
running on your computer.
Whatever directory (and all its subdirectories) that you run
this command in will be accessible to the container.
(You can also run <b>previous</b> versions of the MEME Suite by
appending the appropriate tag after `memesuite/memesuite`, e.g., `memesuite/memesuite:5.5.3`.)

To run MEME Suite commands, you can open a terminal in the container.
First, go to Docker Desktop and select the running container by clicking on its name.
This should open a page with the tabs `Logs`, `Inspect`, `Bind mounts`, `Exec`, `Files` and `Stats`.
Click on the `Exec` tab.
This will open a terminal where you can run all of the MEME Suite command line tools
including, MEME, MAST, STREME, XSTREME etc.
(Note: On older versions of the Docker Desktop the tabs are `Logs`, `Inspect`,
`Terminal` and `Stats`; click on the `Terminal` tab in that case to open a terminal.)

For example, if the directory where you executed the `docker run`
command contains a FASTA protein sequences file named `adh.fa`,
you can run MEME on the sequences by simply typing the following command in the terminal:

``meme adh.fa``

The result file or folder generated by any MEME Suite commands that you execute 
will be in the directory where you ran the `docker run` command, or in one of its subdirectories
if you redirected the output of the MEME Suite command.

You can list all of the available MEME Suite command line tools by typing the following
command in the container:

``ls /opt/meme/bin ; ls /opt/meme/libexec/5.5.8``

**Note:** If your computer has multiple CPUs you can run MEME in
parallel mode, using `meme -p n` where `n` is the number of CPUs available.
This will greatly reduce running time.  You can also specify the `-meme-p`
switch to MEME-ChiP and the `--meme-p` switch to XSTREME, which will
greatly reduce their running times as well.

**Note:** If you run STREME with large input files, you may need to add 
`-m 10g --memory-swap 10g` to the `docker run` command above.


******
## Running a Local MEME Suite Web Server Using Docker

To run your own MEME Suite web server on your computer, enter the following command in a terminal:

``docker run -v `pwd`:/home/meme -d -p 8080:8080 memesuite/memesuite:latest``

This will run the latest MEME Suite Docker image in a Docker container on your computer.
Allow two or three minutes for the web server to be completely initialized.
The MEME Suite web server will then be available on your computer at URL:

[http://localhost:8080/meme_5.5.8](http://localhost:8080/meme_5.5.8)

**Note:** The web server in the MEME Suite Docker package is not configured to be a secure web server! It should only be used as a personal instance and not exposed to other computers, and certainly not to the broader Internet. In the provided  example starting command the web server will communicate on port 8080 which is generally not exposed by firewalls. **If your computer does pass port 8080 through the firewall you should either close the firewall for that port, or choose another port that is hidden by the firewall.**


(You can also download earlier versions of the MEME Suite and run Docker
appending the appropriate tag after `memesuite/memesuite`, e.g., `memesuite/memesuite:5.5.3`.
You will then access MEME at a URL that includes the appropriate version number.)

You can also open a terminal in the running Docker container (see the previous section)
and run MEME Suite command line tools.

Your local MEME Suite web server will have the motif databases and the GoMo databases installed,
but no sequence databases or T-Gene databases.  However, you can download and install 
sequence databases and/or the T-Gene databases on your local
computer and then make them accessible to the Docker MEME Suite container. 

**Note:** If you run STREME with large input files, you may need to add 
`-m 10g --memory-swap 10g` to the `docker run` command above.

******

## Installing Sequence Databases for Docker

You can download genome sequence database archives for model organisms from 
[https://meme-suite.org/doc/download.html](https://meme-suite.org/doc/download.html#seq_dbs).
There are archives for **Human** (hg16, hg17, hg18, hg19, hg38);
**Mouse** (mm7, mm8, mm9, mm10, mm39);
**Rat** (rn3, rn4, rn5, rn6, rn7);
**Frog** (xenTro1, xenTro2, xenTro3, xenTro7, xenTro9, xenTro10);
**Zebrafish** (danRer3, danRer4, danRer5, danRer6, danRer7, danRer10, danRer11);
**Drosophila** (dm1, dm2, dm3, dm6);
**Worm** (ce2, ce4, ce6, ce10, ce11);
**Yeast** (sacCer1, sacCer2, sacCer3 and Schizosaccaromyces Pombe);
**Arabidoposis thaliana** (TAIR10);
and 
**Rice** (IRGSP-1.0).
There is also an archive containing the three most recent genome versions of each of 
the above **Model Organisms**.
Download the database file archive that you want to your computer and then expand it.
Create a soft link to this database directory with the name `fasta_databases` in 
the directory where you exectued the `docker run` command.
You can download more than one of the archives and switch between them
by simply changing the target of the `fasta_databases` soft link you created:

```
cd some/local/directory 
tar xzvf your_downloaded_archive_name.tgz 
cd directory/where/you/did/docker/run/command
ln -s your_downloaded_archive_name fasta_databases
```

To make the sequence databases visible to your local Docker web server,
restart the Docker container (or start it using the command from the previous section).
You can restart a running container within Docker Desktop using the restart button in
the upper left corner screen after you select the the container.

**Note:** You will only be able to access the FASTA databases you installed if they
are in a directory at or below the directory where you did the Docker run command.

If you require genome, proteome or upstream sequences not available in the archives listed
above, you can use the [update-sequence-db](https://meme-suite.org/doc/update-sequence-db.html) command
from within the running Docker container to create your own sequence archive.
In Docker Desktop, open the `Terminal Tab` of the running container and type

``/opt/meme/libexec/meme-5.5.8/update-sequence-db --the_databases_you_want fasta_databases``

See the help page (above) for more information on `update-sequence-db`.

  
******
## Installing the T-Gene Databases for Docker

The procedure for installing the T-Gene databases is similar to that for sequence
databases (previous section).  Download the T-Gene database archive 
from [https://meme-suite.org/doc/download.html](https://meme-suite.org/doc/download.html).
Expand it using the `tar` command.  Then soft link the expanded directory to `tgene_databases`
in the directory where you will run Docker.  Then start (or restart) the Docker container.


******
# For Windows
******

## Obtaining the most recent Docker image for the MEME Suite

On Windows setting up the MEME Suite Docker image is most done using the Docker Desktop App.
Once you’ve started the Docker Desktop you’ll need to download MEME Suite Docker image (you’ve probably already done this):

1. Go to images tab in Docker Desktop
2. Click on "Search Images to run" button
3. Search for memesuite/memesuite
4. Pull

## Running a Local MEME Suite Web Server and the Command Line Tools on Windows

Once you’ve downloaded the image, you can launch the container from Images tab:
1. Go to images tab
2. Click on run button for memesuite/memesuite
3. Click on Optional settings drop down
4. Choose a name for the container (optional)

If you want to run the web server:

5. Set the 1st host port to 8000:8000/tcp
6. Set 2nd host port to 8080:8080/tcp

If you want to be able to run MEME Suite tools in one of your host directories

7. Click on the "..." next to Host Path under Volumes.
8. Select the host folder that you want to access with MEME Suite tools
9. Set the container path to /home/meme

Finally, 

10. Click the Run button

If may take a while for the web server to start. Once the server has finished starting up you’ll see a message in the log tab about "Catalina.start Server startup in (x) milliseconds”. Note that the MEME web application has an issue with hyper-threading on Windows. It makes MEME think it has twice as many threads as are actually available. If you try to run a MEME job on the web server and get an error message from MPI about trying to run on too many cores, this is the problem. Unfortunately the only way to fix this currently is to turn off hyper-threading on your computer, which has to be done in your BIOS settings, and will degrade performance in other applications. We’re looking for a fix for this, but don’t have one yet.

The MEME Suite web server will then be available on your computer at URL:

[http://localhost:8080/meme_5.5.8](http://localhost:8080/meme_5.5.8)


Click on the “Terminal” tab to get an interactive shell where all the command line MEME Suite tools are available. The shell will start in the directory you set under “Host Path” in the previous step. You may want to do a quick tutorial on the UNIX bash shell to enhance your productivity.
