doc: Add working with Cilicon section

doc/manual/Makefile

@@ -43,6 +43,7 @@ SOURCES = \
 	source/tracing.rst \
 	source/troubleshoot.rst \
 	source/utilities.rst \
+	source/working-with-cilicon.rst \
 	source/working-with-cmake.rst \
 	source/working-with-docker.rst \
 	source/working-with-git.rst \

doc/manual/source/develop.rst

@@ -18,3 +18,4 @@ This chapter describes the development ecosystem generally used to create new mo
    profiling
    working-with-gitlab-ci-local
    working-with-docker
+   working-with-cilicon

doc/manual/source/working-with-cilicon.rst

@@ -0,0 +1,115 @@
+.. include:: replace.txt
+.. highlight:: bash
+
+.. _Working with Cilicon:
+
+Working with Cilicon
+--------------------
+
+.. _continuous integration (CI) : https://docs.gitlab.com/ee/ci/
+.. _Cilicon : https://github.com/traderepublic/Cilicon/
+.. _Cilicon releases : https://github.com/traderepublic/Cilicon/releases/
+
+The ns-3 project repository is currently hosted in GitLab, which includes
+`continuous integration (CI)`_ tools to automate build, tests, packaging and
+distribution of software. The CI works based on jobs, that are defined
+in YAML files and run inside containers.
+
+While we can run most Linux containers everywhere without much problem,
+that is not the case for Windows and MacOS. You can run gitlab-runner as a
+local user, taking proper precautions to avoid that user from escalating privileges,
+then taking over your own network and other systems on it.
+
+That is typically harder than just enforce network security, and virtualization-based security.
+GitLab doesn't offer a way to do that, other than their own runners, which cost up to 6x more
+than linux ones.
+Which is why Trade Republic created the `Cilicon`_ application for MacOS, which creates an ephemeral virtual
+machine, executes a gitlab job, then destroys the VM, and creates a fresh new one.
+
+To set it up, first go to System Settings->Energy and enable all options to prevent sleep, wake on
+network traffic, and restart after power failure (assuming the Mac will be used exclusively as a CI server).
+
+After this, download the latest release in `Cilicon releases`_.
+Put the application in Applications directory and start it. It will ask you to install MacOS virtualization framework.
+
+If you only have a single CI runner that you wish to run, follow their easy settings and create a
+``~/cilicon.yml`` file at the user directory containing:
+
+.. sourcecode:: yaml
+
+    source: oci://ghcr.io/cirruslabs/macos-runner:sequoia
+    provisioner:
+      type: gitlab
+      config:
+        gitlabURL: <GITLAB_INSTANCE_URL>
+        runnerToken: <RUNNER_TOKEN>
+
+If you have multiple CI runners that you wish to run from a single machine, one job at a time,
+you need a custom configuration file, first create a folder that will be shared with the VM.
+
+.. sourcecode:: console
+
+    mkdir /Users/nsnam/gitlab-ephemeral
+
+Then add your GitLab runner ``config.toml`` file there, for example, containing:
+
+.. sourcecode:: toml
+
+    concurrent = 1
+    check_interval = 0
+    connection_max_age = "15m0s"
+    shutdown_timeout = 0
+
+    [session_server]
+      session_timeout = 1800
+
+    [[runners]]
+      name = "MacOsRunnerForProjectA"
+      url = "https://gitlab.com/"
+      token = "<RUNNER_TOKEN_A>"
+      executor = "shell"
+      cleanup_policy = "always"
+
+    [[runners]]
+      name = "MacOsRunnerForProjectB"
+      url = "https://gitlab.com/"
+      token = "<RUNNER_TOKEN_B>"
+      executor = "shell"
+      cleanup_policy = "always"
+
+
+Then create a ``cilicon.yml`` file at the user directory containing:
+
+.. sourcecode:: yaml
+
+    source: oci://ghcr.io/cirruslabs/macos-sonoma-xcode:15
+    provisioner:
+      type: script
+      config:
+        run: |
+          cp /Volumes/My\ Shared\ Files/gitlab-runner/config.toml /Users/admin/.gitlab-runner/config.toml
+          gitlab-runner run
+    consoleDevices:
+      - tart-version-2
+    hardware:
+      ramGigabytes: 20
+      connectsToAudioDevice: false
+    directoryMounts:
+      - hostPath: /Users/nsnam/gitlab-ephemeral
+        guestFolder: gitlab-runner
+        readOnly: true
+
+Note: If you want to create a new VM for every CI job, replace ``gitlab-runner run``
+with ``gitlab-runner run-single``. Not very recommended, because it will hit SSD hard.
+And recent Macs have soldered storage.
+
+After configuring everything, execute Cilicon. It will setup MacOS virtualization framework, then fetch the VM image.
+It will then start the VM.
+
+At this point, MacOS will query you for being visible in network.
+You need to say yes, so the VM can access the shared directory.
+
+Otherwise, you need to either write the TOML with the cilicon.yml, or download it from a remote server.
+
+At this point, you should have your native MacOS runners fully working.
+Try starting a job and see if they respond via GitLab web interface.