Skip to content

Commit 6083404

Browse files
zakkakzakkak
committed
[docker] Use docker-sync on all platforms for ease of use and speed
1 parent 0e89a2a commit 6083404

File tree

4 files changed

+54
-143
lines changed

4 files changed

+54
-143
lines changed

‎docker/README.md

+1-79
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,4 @@
1-
# Running maxineVM in docker
2-
3-
## Creating the docker container
4-
5-
From the directory `maxine-src` (created in [Prerequisites](#prerequisites)) run:
6-
7-
```
8-
docker create \
9-
-p 9873:873 \
10-
--mount src="/tmp/.X11-unix",target="/tmp/.X11-unix",type=bind \
11-
-e DISPLAY=unix$DISPLAY --cap-add=SYS_PTRACE \
12-
--name maxine-dev -ti beehivelab/maxine-dev
13-
```
14-
15-
This will create a container named `maxine-dev`.
16-
17-
- `-p 9873:873` maps port 9873 of the host to port 873 of the docker container.
18-
- `--mount src="/tmp/.X11-unix",target="/tmp/.X11-unix",type=bind` mounts the host X11 socket to the container socket.
19-
- `-e DISPLAY=unix$DISPLAY` passes in the `DISPLAY` environment variable.
20-
- `--cap-add=SYS_PTRACE` enables `ptrace` capability for the container.
21-
- `--name maxine-dev` names the new image so that it can later be referenced (to start it, stop it, attach to it etc.).
22-
- `-ti` instructs docker to create an interactive session with a pseudo-tty, to allow us to interact with the container.
23-
24-
## Initializing the container
25-
26-
The docker image expects the source code to be in the layout shown below:
27-
28-
```
29-
$ tree -L 1 maxine-src
30-
maxine-src
31-
├── maxine
32-
└── mx
33-
```
34-
35-
To get the source code in this layout execute:
36-
37-
```
38-
$ mkdir maxine-src
39-
$ git clone https://github.com/graalvm/mx.git maxine-src/mx
40-
$ git clone https://github.com/beehive-lab/Maxine-VM.git maxine-src/maxine
41-
```
42-
43-
Then copy the `maxine-src` directory to the container using:
44-
45-
```
46-
$ rsync -avP maxine-src --delete rsync://localhost:9873/maxine-src/
47-
```
48-
49-
### Optionally copy over your `~/.mx` directory
50-
51-
If you use `mx` locally as well you can use the same cache to avoid fetching again large files:
52-
53-
```
54-
$ rsync -avP ~/.mx --delete rsync://localhost:9873/mx/
55-
```
56-
57-
## Using the docker container
58-
59-
To use the container issue:
60-
61-
```
62-
docker start -i maxine-dev
63-
```
64-
65-
This will start the container and open a `bash` shell in it.
66-
From this shell you can build and run maxine.
67-
68-
To exit the shell and stop the container type `Ctrl-D`.
69-
70-
## Keeping your data on the host in sync with your data on the docker container
71-
72-
If you use the container for development purposes you most probably will be interested in editing the source code locally and building and running on the docker container.
73-
To automatically synchronize your files from the host to the container use:
74-
75-
```
76-
fswatch -0 maxine-src | xargs -0 -n 1 -I {} rsync -avP maxine-src --delete rsync://localhost:9873/maxine-src/
77-
```
78-
79-
## Build the docker image
1+
# Build the docker image
802

813
The image can be found at https://hub.docker.com/r/beehivelab/maxine-dev, however if you want to build it yourself,
824
enter the directory with the Dockerfile and run:

‎docker/docker-compose.yml

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
version: "3"
2+
services:
3+
maxine-dev:
4+
# build: .
5+
image: beehivelab/maxine-dev:latest
6+
container_name: maxine-dev
7+
cap_add:
8+
- SYS_PTRACE
9+
stdin_open: true
10+
tty: true
11+
environment:
12+
DISPLAY: unix${DISPLAY}
13+
ports:
14+
- "9873:873"
15+
volumes:
16+
- maxine-dev-mx-sync:/root/.mx:nocopy # nocopy is important
17+
- maxine-dev-src-sync:/root/maxine-src:nocopy # nocopy is important
18+
- /tmp/.X11-unix:/tmp/.X11-unix
19+
20+
# that the important thing
21+
volumes:
22+
maxine-dev-mx-sync:
23+
external: true
24+
maxine-dev-src-sync:
25+
external: true

‎docker/docker-sync.yml

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
version: "2"
2+
3+
options:
4+
verbose: true
5+
syncs:
6+
maxine-dev-mx-sync: # tip: add -sync and you keep consistent names as a convention
7+
src: '~/.mx'
8+
maxine-dev-src-sync: # tip: add -sync and you keep consistent names as a convention
9+
src: '../../'
10+
sync_excludes: ['*.class']

‎docs/build.rst

+18-64
Original file line numberDiff line numberDiff line change
@@ -26,87 +26,41 @@ To get the source code in this layout execute::
2626
$ git clone https://github.com/graalvm/mx.git maxine-src/mx
2727
$ git clone https://github.com/beehive-lab/Maxine-VM.git maxine-src/maxine
2828

29-
Creating the docker container
30-
-----------------------------
31-
32-
GNU/Linux
33-
~~~~~~~~~
34-
35-
On GNU/Linux distributions we can simply mount the host directories on the container.
36-
37-
From the directory ``maxine-src``, that we created in the previous step, run::
38-
39-
docker create -u=$(id -u):$(id -g) \
40-
--mount src="$(pwd)",target="/maxine-src",type=bind \
41-
--mount src="$HOME/.mx",target="/.mx",type=bind \
42-
--mount src="/tmp/.X11-unix",target="/tmp/.X11-unix",type=bind \
43-
-e DISPLAY=unix$DISPLAY --cap-add=SYS_PTRACE \
44-
--name maxine-dev -ti beehivelab/maxine-dev
45-
46-
This will create a container named ``maxine-dev``.
47-
48-
- ``-u=$(id -u):$(id -g)`` instructs docker to write and read files as the current user instead of root which is the default.
49-
- ``--mount src="$(pwd)",target="/maxine-src",type=bind`` essentially mounts the current directory to the docker container under the `/maxine-src` directory.
50-
Similarly, `--mount src="$HOME/.mx",target="/.mx",type=bind` does the same for the `~/.mx` directory.
51-
Any changes performed to mounted folders outside the docker container are visible in the container and vice versa.
52-
- ``--mount src="/tmp/.X11-unix",target="/tmp/.X11-unix",type=bind`` mounts the host X11 socket to the container socket.
53-
- ``-e DISPLAY=unix$DISPLAY`` passes in the ``DISPLAY`` environment variable.
54-
- ``--cap-add=SYS_PTRACE`` enables ``ptrace`` capability for the container.
55-
- ``--name maxine-dev`` names the new image so that it can later be referenced (to start it, stop it, attach to it etc.).
56-
- ``-ti`` instructs docker to create an interactive session with a pseudo-tty, to allow us to interact with the container.
57-
58-
macOS
59-
~~~~~
60-
61-
On macOS unfortunately simply mounting host directories on docker containers, although functional, is slow.
62-
As an alternative we run an rsync daemon on the docker container and rsync the source code from the host to the container.
29+
Developing using a docker container
30+
-----------------------------------
6331

64-
To create a docker container from the ``beehivelab/maxine-dev`` docker image run::
32+
On macOS (and Windows) unfortunately simply mounting host directories on docker containers, although functional, is slow.
33+
To work arround this issue we use `docker-sync <https://docker-sync.readthedocs.io/en/latest/index.html>`__.
34+
Additionally we run an rsync daemon on the docker container, this way users that don't want to use docker-sync can manualy rsync files from the host to the container and vice versa (through ``rsync://localhost:9873/root`` which maps to ``/root/`` on the container).
6535

66-
docker create \
67-
-p 9873:873 \
68-
--cap-add=SYS_PTRACE \
69-
--name maxine-dev -ti beehivelab/maxine-dev
36+
To create a docker container named ``maxine-dev`` from the ``beehivelab/maxine-dev`` docker image enter ``maxine-src/maxine/docker`` and run::
7037

71-
This will create a container named ``maxine-dev``.
38+
docker-compose up --no-start
7239

73-
- ``-p 9873:873`` maps port 9873 of the host to port 873 of the docker container.
74-
- ``--cap-add=SYS_PTRACE`` enables ``ptrace`` capability for the container.
75-
- ``--name maxine-dev`` names the new image so that it can later be referenced (to start it, stop it, attach to it etc.).
76-
- ``-ti`` instructs docker to create an interactive session with a pseudo-tty, to allow us to interact with the container.
40+
Note that the container is now created but does not contain the source code.
7741

78-
Initializing the container
79-
''''''''''''''''''''''''''
80-
81-
Then start the container (on a different terminal) with::
82-
83-
docker start -i maxine-dev
84-
85-
Return back to the main terminal and copy the ``maxine-src`` directory to the container using::
86-
87-
rsync -avP maxine-src --delete rsync://localhost:9873/root/
42+
Keeping your data on the host in sync with your data on the docker container
43+
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
8844

89-
Optionally copy over your ``~/.mx`` directory as well
90-
'''''''''''''''''''''''''''''''''''''''''''''''''''''
45+
Install `docker-rsync <https://docker-sync.readthedocs.io/en/latest/index.html>`__::
9146

92-
If you use ``mx`` locally as well you can use the same cache to avoid fetching again large files::
47+
gem install docker-sync
9348

94-
rsync -avP ~/.mx --delete rsync://localhost:9873/root/
49+
To start it enter ``maxine-src/maxine/docker/`` and run::
9550

96-
Keeping your data on the host in sync with your data on the docker container
97-
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
51+
docker-sync start
9852

99-
If you use the container for development purposes you most probably will be interested in editing the source code on the host.
100-
To automatically synchronize your files from the host to the container use::
53+
To stop it::
10154

102-
fswatch -0 maxine-src | xargs -0 -n 1 -I {} rsync -avP maxine-src --delete rsync://localhost:9873/root/
55+
docker-sync stop
10356

10457
Using the ``maxine-dev`` container
105-
----------------------------------
58+
''''''''''''''''''''''''''''''''''
10659

10760
To use the container issue ``docker start -i maxine-dev``.
10861
This will start the container and open a ``bash`` shell in it.
10962
From this shell you can build and run maxine.
63+
As long as docker-sync is running any changes you make on the host or the container will become visible to the counterpart as well.
11064

11165
To exit the shell and stop the container type ``Ctrl-D``.
11266

0 commit comments

Comments
 (0)