2.1. Install with Docker
A Docker container that includes all the external dependencies MDMC needs can be downloaded.
Instructions on how to install Docker for Windows, Mac OS X, and Linux distributions is here. If you experience problems with this installation, perhaps due to your specific OS version or otherwise, please do not hesitate to ask us questions about this.
The following installation instructions will enable MDMC to run using the Docker
container. This will allow molecular visualization using the 'X3DOM'
viewer, which displays within a Jupyter notebook (which is automatically started
by the Docker container). However, to use the external 'ASE' viewer for
molecular visualization, X11 forwarding must additionally be enabled before
the instructions below are followed. The difference between
these viewers is explained in the
Molecular Visualization
tutorial. Instructions on how to enable X11 forwarding are in
X11 Forwarding for Docker. X11 forwarding occurs by default on Linux, so
on that platform no additional steps are required.
As MDMC is currently private, Github credentials are required for access. This is via a personal access token that you can generate on Github.com. Instructions are here <https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>, or short instructions are the following:
Log into Github.com.
Go to https://github.com/settings/tokens <https://github.com/settings/tokens>.
Click ‘Generate new token’ and enter your password.
In the ‘note’ field, enter “MDMC access”
Let the expiration time be whatever you want (although we highly advise against making it permanent, for user security)
Check the ‘repo’ box in the ‘select scopes’ section.
Scroll to the bottom and click ‘generate token’.
Copy your personal access token and save it somewhere secure.
You now have a personal access token!
2.1.1. Windows
To simplify running Docker with the required ports and volumes, please download the compressed file below, which contains a docker-compose configuration file (docker-compose.yml) and an empty token file (token.txt)). Unzip the file wherever you wish to run MDMC.
Download mdmc docker-compose zip
Then, open the empty file ‘token.txt’ and paste your personal access token into it.
At the command line, in the directory where the docker-compose.yml and the token
file is located, do the following (please ensure that Docker Desktop is running, test
this e.g. by running docker run hello-world):
To download the latest MDMC container (this might take a few minutes), run:
docker-compose pull
To run the container, use the up command. On the first occasion this
will take 30-60 s as MDMC is downloaded.
docker-compose up
This will start a Jupyter notebook server which will generate some URLs. To
access the server, open the URL starting with http://127.0.0.1:8888
into a browser. The MDMC tutorials will also be included within the directory
in which the Jupyter server is started. This directory will also exist outside
of the container (in the directory from which you ran
docker-compose up), and can be accessed outside of the container;
however you will not be able to run any of the MDMC commands from outside of
the container.
To test MDMC and GUI visualisation copy and paste Python code from the tutorial Molecular Visualization into the Jupyter notebook.
Recommended: When finished using Jupyter, in terminal where the Jupyter server was started, please press ctrl-c and then answer “y” to shutdown the Jupyter server; this will exit Jupyter gracefully and help avoid conflict when running this setup again.
To restart the container, simply run:
docker-compose up
It is not necessary to download the latest version of the MDMC container before
running the up command; however if you would like to then please precede
it with docker-compose pull.
Note that docker-compose pull and docker-compose up commands
will overwrite the contents of the local folder mdmc_sync_with_docker,
resulting in any modifications to the existing tutorial notebooks being
overwritten. Any new notebooks which had been previously saved will still be
available, unless you explicitly remove the Docker volume (using
docker volume rm).
2.1.2. Mac OS X
To simplify running Docker with the required ports and volumes, please download the compressed file below, which contains a docker-compose configuration file (docker-compose.yml) and an empty token file (token.txt)). Unzip the file wherever you wish to run MDMC.
Download mdmc docker-compose zip
Then, open the empty file ‘token.txt’ and paste your personal access token into it.
Then in a terminal, in the directory where the docker-compose.yml and the token file is located, do the following (please ensure that Docker Desktop is running, test
this e.g. by running docker run hello-world):
To download the latest MDMC container (this might take a few minutes), run:
docker-compose pull
To run the container, use the up command. On the first occasion this
will take 30-60 s as MDMC is downloaded.
docker-compose up
This will start a Jupyter notebook server which will generate some URLs. To
access the server, open the URL starting with http://127.0.0.1:8888
into a browser. The MDMC tutorials will also be included within the directory
in which the Jupyter server is started. This directory will also exist outside
of the container (in the directory from which you ran
docker-compose up), and can be accessed outside of the container;
however you will not be able to run any of the MDMC commands from outside of
the container.
To test MDMC and GUI visualisation copy and paste Python code from the tutorial Molecular Visualization into the Jupyter notebook.
Recommended: When finished using Jupyter, in terminal where the Jupyter server was started, please press ctrl-c and then answer “y” to shutdown the Jupyter server; this will exit Jupyter gracefully and help avoid conflict when running this setup again.
To restart the container, simply run:
docker-compose up
It is not necessary to download the latest version of the MDMC container before
running the up command; however if you would like to then please precede
it with docker-compose pull.
Note that docker-compose pull and docker-compose up commands
will overwrite the contents of the local folder mdmc_sync_with_docker,
resulting in any modifications to the existing tutorial notebooks being
overwritten. Any new notebooks which had been previously saved will still be
available, unless you explicitly remove the Docker volume (using
docker volume rm).
2.1.3. Linux
Docker-compose is not included by default when Docker is installed on Linux. It is possible to install docker-compose using pip3:
pip3 install docker-compose
Alternatively, there are other methods for installing docker-compose.
Download mdmc docker-compose tar
Then, open the empty file ‘token’ and paste your personal access token into it.
Then in a terminal, in the directory where the docker-compose.yml and the token file is located, do the following:
To download the latest MDMC container (this might take a few minutes), run:
docker-compose pull
To run the container, use the up command. On the first occasion this
will take 30-60 s as MDMC is downloaded.
docker-compose up
This will start a Jupyter notebook server which will generate some URLs. To
access the server, open the URL starting with http://127.0.0.1:8888
into a browser. The MDMC tutorials will also be included within the directory
in which the Jupyter server is started. This directory will also exist outside
of the container (in the directory from which you ran
docker-compose up), and can be accessed outside of the container;
however you will not be able to run any of the MDMC commands from outside of
the container.
To test MDMC and GUI visualisation copy and paste Python code from the tutorial Molecular Visualization into the Jupyter notebook.
Recommended: When finished using Jupyter, in terminal where the Jupyter server was started, please press ctrl-c and then answer “y” to shutdown the Jupyter server; this will exit Jupyter gracefully and help avoid conflict when running this setup again.
To restart the container, simply run:
docker-compose up
It is not necessary to download the latest version of the MDMC container before
running the up command; however if you would like to then please precede
it with docker-compose pull.
Note that docker-compose pull and docker-compose up commands
will overwrite the contents of the local folder mdmc_sync_with_docker,
resulting in any modifications to the existing tutorial notebooks being
overwritten. Any new notebooks which had been previously saved will still be
available, unless you explicitly remove the Docker volume (using
docker volume rm).
2.1.4. X11 Forwarding for Docker
By default, Docker is not configured to enable GUI visualisation (a feature of
Docker and containers). To enable this use the X11 system, described below. GUI
is for example needed for using the 'ASE' viewer for visualising
molecule / universe setups with MDMC. However, the 'X3DOM' viewer, which
has almost all of the functionality of the 'ASE' viewer, can be used in
a Jupyter notebook without enabling X11 forwarding. The difference between
these viewers is explained in the
Molecular Visualization
tutorial.
2.1.4.1. Windows
To use X11, either of the following can be installed:
VcXsrv - After installation, In Extra Settings select “Native opengl” and “Disable access control”.
Xming - After installation, run XLaunch to configure Xming. Use the provided defaults except in the “Specify parameter settings” window, select “No Access Control”. Optionally, use the generated config.xlaunch file when re-running Xming.
X11 forwarding will now be enabled, and molecular visualization with the ‘ASE’ viewer will be possible. Please continue with the Docker installation instructions in Install with Docker.
2.1.4.2. Mac OS X
To use X11, xQuartz can be installed. In the xQuartz Preferences -> Security select “Allow connections from network clients”.
To allow the Docker container to access the local display using X11, run:
xhost +localhost
If you exit XQuartz at any point, you will need to run the above command again
before running docker-compose up (see the OS X installation instructions
in Install with Docker).
X11 forwarding will now be enabled, and molecular visualization with the ‘ASE’ viewer will be possible. Please continue with the Docker installation instructions in Install with Docker.
2.1.4.3. Linux
As X11 is built-in to Linux, no additional software needs to be installed for X11 forwarding.