1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
|
# Maneage'd projects in Docker
Copyright (C) 2021-2025 Mohammad Akhlaghi <mohammad@akhlaghi.org>\
See the end of the file for license conditions.
For an introduction on containers, see the "Building in containers" section
of the `README.md` file within the top-level directory of this
project. Here, we focus on Docker with a simple checklist on how to use the
`docker.sh` script that we have already prepared in this directory for easy
usage in a Maneage'd project.
## Building your Maneage'd project in Docker
Through the steps below, you will create a Docker image that will only
contain the software environment and keep the project source and built
analysis files (data and PDF) on your host operating system. This enables
you to keep the size of the image to a minimum (only containing the built
software environment) to easily move it from one computer to another.
0. Add your user to the `docker` group: `usermod -aG docker
USERNAME`. This is only necessary once on an operating system.
1. Start the Docker daemon (root permissions required). If the operating
system uses systemd you can use the command below. If you want the
Docker daemon to be available after a reboot also (so you don't have to
restart it after turning off your computer), run this command again but
replacing `start` with `enable` (this is not recommended if you don't
regularly use Docker: it will slow the boot time of your OS).
```shell
systemctl start docker
```
2. Using your favorite text editor, create a `docker-local.sh` in your top
Maneage directory (as described in the comments at the start of the
`docker.sh` script in this directory). Just activate `--build-only` on
the first run so it doesn't go onto doing the analysis and just sets up
the software environment.
3. After the setup is complete, run the following command to confirm that
the `maneage-base` (the OS of the container) and `maneaged` (your
project's full Maneage'd environment) images are available. If you want
different names for these images, add the `--project-name` and
`--base-name` options to the `docker.sh` call.
```shell
docker image list
```
4. You are now ready to do your analysis by removing the `--build-only`
option.
## Script usage tips
The `docker.sh` script introduced above has many options allowing certain
customizations that you can see when running it with the `--help`
option. The tips below are some of the more useful scenarios that we have
encountered so far.
### Docker image in a single file
In case you want to store the image as a single file as backup or to move
to another computer. For such cases, run the `docker.sh` script with the
`--image-file` option (for example `--image-file=myproj.tar.gz`). After
moving the file to the other system, run `docker.sh` with the same option.
When the given file to `docker.sh` already exists, it will only be used for
loading the environment. When it doesn't exist, the script will save the
image into it.
## Docker usage tips
Below are some useful Docker usage scenarios that have proved to be
relevant for us in Maneage'd projects.
### Cleaning up
Docker has stored many large files in your operating system that can drain
valuable storage space. The storage of the cached files are usually orders
of magnitudes larger than what you see in `docker image list`! So after
doing your work, it is best to clean up all those files. If you feel you
may need the image later, you can save it in a single file as mentioned
above and delete all the un-necessary cached files. Afterwards, when you
load the image, only that image will be present with nothing extra.
The easiest and most powerful way to clean up everything in Docker is the
two commands below. The first will close all open containers. The second
will remove all stopped containers, all networks not used by at least one
container, all images without at least one container associated to them,
and all build cache.
```shell
docker ps -a -q | xargs docker rm
docker system prune -a
```
If you only want to delete the existing used images, run the command
below. But be careful that the cache is the largest storage consumer! So
the command above is the solution if your OS's root partition is close to
getting filled.
```shell
docker images -a -q | xargs docker rmi -f
```
### Preserving the state of an open container
All interactive changes in a container will be deleted as soon as you exit
it. This is a very good feature of Docker in general! If you want to make
persistent changes, you should do it in the project's plain-text source and
commit them into your project's online Git repository. But in certain
situations, it is necessary to preserve the state of an interactive
container. To do this, you need to `commit` the container (and thus save it
as a Docker "image"). To do this, while the container is still running,
open another terminal and run these commands:
```shell
# These two commands should be done in another terminal
docker container list
# Get the 'XXXXXXX' of your desired container from the first column above.
# Give the new image a name by replacing 'NEW-IMAGE-NAME'.
docker commit XXXXXXX NEW-IMAGE-NAME
```
### Interactive tests on built container
If you later want to start a container with the built image and enter it in
interactive mode (for example for temporary tests), run the following
command. Just replace `NAME` with the same name you specified when building
the project. You can always exit the container with the `exit` command
(note that all your changes will be discarded once you exit, see below if
you want to preserve your changes after you exit).
```shell
docker run -it NAME
```
### Copying files from the Docker image to host operating system
Except for the mounted directories, the Docker environment's file system is
indepenent of your host operating system. One easy way to copy files to and
from an open container is to use the `docker cp` command (very similar to
the shell's `cp` command).
```shell
docker cp CONTAINER:/file/path/within/container /host/path/target
```
## Copyright information
This file is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.
This file is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along
with this file. If not, see <https://www.gnu.org/licenses/>.
|
