# Docker container (base) for the converter software

This directory contains all the files needed to create the base [Docker](https://www.docker.com) image used for the converter software in [`projects`](projects/).

A specific project's translation script can be executed either in an app like manner (*I.O.U. a link to the anchor here*), calling it directly from within the container, using a local copy executed by the container (*I.O.U. a link to the anchor here*), or in an interactive shell within the container (*I.O.U. a link to the anchor here*).

[[_TOC_]]

## Building & running the Docker container

This is a quick tour on how to build and run the Docker container through different scenarios. This is not a lecture on containerisation in general, nor Linux/ Unix, shell scripting or programming. But if you encounter a specific problem, feel free to ping the [MA team](https://modelarchive.org/contact).

This section describes three use cases of the Docker container (including a build-how to per use case) but starts with a short primer of what is common to all scenarios described here.

### Prerequisites

For building the Docker image, you need a local copy of the [Git repository](/.). After that, this guide assumes you are in the [`projects`](projects/) subdirectory (we skip the output of the commands here):

```terminal
$ git clone https://git.scicore.unibas.ch/schwede/modelcif-converters.git modelcif-converters.git
$ cd modelcif-converters.git/projects
$
```

Since the Docker container will run as a dedicated, non-root user, it is advisable to create this user with the ID of your local user. That way, file permission issues will be avoided. Get your user ID with the following command and note it down - it will be needed in the build steps:

```terminal
$ whoami
localuser
$ id
uid=12345(localuser) ...
$
```

Look for the `uid` in the output of `id`. In the example above, `12345` is the ID of user `localuser`, currently logged in and executing the commands.

One last thing that is needed for the example runs of the Docker container is data. For simplicity, we assume that a directory `/home/user/models` exists on the local computer executing a converter, full of modelling data.

<!--
- Do single example call
- show how to loop
- all build use local UID!

1. App like
- special build
- own run command
2. Local copy
- works with every build
- own run command
3. Interactive shell
- works with every build
- most complicated run bit
- include history!
4. Development environment
- include pylint, black and pyproject.toml
-->

<!--
build:
- go into repo projects dir
- execute: docker build -f docker/Dockerfile -t mmcifconverter:20220427 .
- explain how to install a dedicated converter script in the container
- mention how to change user
- mention dev stuff
- mention script is copied to a unified name for the container to work with a single entrypoint script

run interactive shell for development:
- make sure files exist: /Users/stefan/Projects/ma-converters.git/projects/pointmutations-haddock/.docker-bash-history
- execute:
docker run --rm -i -v /Users/stefan/.bash_profile:/home/mmcif/.bash_profile -v /Users/stefan/.bash_aliases:/home/mmcif/.bash_aliases -v /Users/stefan/.bashrc:/home/mmcif/.bashrc -v /Users/stefan/Projects/ma-converters.git/projects/pointmutations-haddock/.docker-bash-history:/home/mmcif/.bash_history -v /Users/stefan/Projects/ma-converters.git/:/develop -t mmcifconverter:20220427 bash

-->