Support for running VAO in Docker-friendly containers

.github/workflows/workflow.yml

@@ -0,0 +1,89 @@
+name: Build and Publish Docker image
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ 'v*.*.*' ]
+  workflow_dispatch:
+
+jobs:
+  build-amd64:
+    runs-on: ubuntu-latest   # native x86_64 runner
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Lowercase GITHUB_REPO
+        run: |
+          echo "GITHUB_REPO=${GITHUB_REPOSITORY,,}" >>${GITHUB_ENV}
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push amd64 image
+        run: |
+          docker buildx build \
+            --platform linux/amd64 \
+            -f Dockerfile \
+            -t ghcr.io/${GITHUB_REPO}:amd64 \
+            --push .
+
+  build-arm64:
+    runs-on: ubuntu-22.04-arm   # native ARM64 runner
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Lowercase GITHUB_REPO
+        run: |
+          echo "GITHUB_REPO=${GITHUB_REPOSITORY,,}" >>${GITHUB_ENV}
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push arm64 image
+        run: |
+          docker buildx build \
+            --platform linux/arm64 \
+            -f Dockerfile \
+            -t ghcr.io/${GITHUB_REPO}:arm64 \
+            --push .
+
+  merge-manifest:
+    runs-on: ubuntu-latest
+    needs: [build-amd64, build-arm64]
+    steps:
+
+      - name: Lowercase GITHUB_REPO
+        run: |
+          echo "GITHUB_REPO=${GITHUB_REPOSITORY,,}" >>${GITHUB_ENV}
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create and push multi-arch manifest
+        run: |
+          IMAGE=ghcr.io/${GITHUB_REPO}
+          docker manifest create $IMAGE:latest \
+            --amend $IMAGE:amd64 \
+            --amend $IMAGE:arm64
+          docker manifest push $IMAGE:latest
+
+          # optionally also tag releases
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            VERSION=${GITHUB_REF_NAME}
+            docker manifest create $IMAGE:$VERSION \
+              --amend $IMAGE:amd64 \
+              --amend $IMAGE:arm64
+            docker manifest push $IMAGE:$VERSION
+          fi

Dockerfile

@@ -0,0 +1,18 @@
+# syntax=docker/dockerfile:1
+FROM julia:1.11.7-trixie
+
+# Set env for non-interactive installs
+ENV JULIA_DEPOT_PATH=/usr/local/julia
+
+# Copy your package code
+COPY . /VirtualAcousticOcean
+
+# Precompile your package
+RUN julia --color=yes --project=/VirtualAcousticOcean -e \
+    'using Pkg; Pkg.instantiate(); Pkg.precompile()'
+
+WORKDIR /sims
+
+# Default to Julia REPL (can override with CMD in docker run)
+ENTRYPOINT ["julia", "--color=yes", "-t", "auto", "--project=/VirtualAcousticOcean"]
+CMD []

README.md

@@ -18,6 +18,24 @@ pkg> add VirtualAcousticOcean
 > [!IMPORTANT]
 > You must run `julia` in multi-threading mode (flag `-t auto` or environment variable `JULIA_NUM_THREADS` set to `auto`) for `VirtualAcousticOcean.jl` to provide good performance. While, it will run in a single-threaded mode, the delivery of frames may be delayed and unreliable. `VirtualAcousticOcean.jl` will print out a WARNING if you accidentally run in single-threaded mode.
 
+### Docker
+
+A Docker image is available for users who do not wish to install Julia and the package dependencies. The image is available on [GitHub Container Registry](http://ghcr.io/org-arl/virtualacousticocean) and it can be used to run the example simulation as follows:
+
+```bash
+docker run --rm \
+  -v $PWD:/sims \
+  -p 9809:9809 \
+  -p 9819:9819 \
+  ghcr.io/org-arl/virtualacousticocean.jl:latest \
+  /sims/examples/2-node-network.jl
+```
+
+The Docker container will run the example simulation in [examples/2-node-network.jl](examples/2-node-network.jl) and expose the two nodes on TCP ports `9809` and `9819` on the host machine. You may then connect to these ports using [UnetStack](http://www.unetstack.net) 5 based modems or software-defined modem simulators.
+
+- The `-v $PWD:/sims` mounts the current directory on the host to `/sims` in the container. This allows you to run your own simulation scripts in the container. `/sims` is the working directory in the container.
+- The `-p 9809:9809 -p 9819:9819` exposes the TCP ports on the host machine. You have to expose the ports of all nodes you wish to connect to from outside the container.
+
 ### Setting up a simulation
 
 Setting up a simulation is simple. We first describe an environment and create a propagation model, as one would with the [propagation modeling toolkit](https://org-arl.github.io/UnderwaterAcoustics.jl/quickstart.html):

examples/2-node-network.jl

@@ -30,4 +30,10 @@ addnode!(sim, (1000.0, 0.0,  -5.0), UASP2, 9819, ip"0.0.0.0")
 # run simulation
 
 run(sim)        # start simulation asynchronously
+
+println("Simulation running at $(sim.frequency)Hz with these nodes:")
+for (idx, node) in enumerate(sim.nodes)
+    println(" - Node $(idx) at position $(node.pos) receiving on port $(node.conn.port)")
+end
+
 wait()          # wait forever