{"id":30612620,"url":"https://github.com/evolvedbinary/fordham-ahi-vm-setup","last_synced_at":"2025-09-16T15:18:43.193Z","repository":{"id":257868731,"uuid":"872455522","full_name":"evolvedbinary/fordham-ahi-vm-setup","owner":"evolvedbinary","description":"Virtual Machines for Applied Health Informatics MSc at Fordham University","archived":false,"fork":false,"pushed_at":"2025-03-01T00:26:08.000Z","size":136,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-30T05:41:53.145Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Puppet","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evolvedbinary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-14T13:19:04.000Z","updated_at":"2025-03-01T00:26:12.000Z","dependencies_parsed_at":"2025-02-14T19:28:33.150Z","dependency_job_id":"2441a964-3b0e-457d-b2fe-d0dd2ce44b66","html_url":"https://github.com/evolvedbinary/fordham-ahi-vm-setup","commit_stats":null,"previous_names":["evolvedbinary/fordham-ahi-vm-setup"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/evolvedbinary/fordham-ahi-vm-setup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evolvedbinary%2Ffordham-ahi-vm-setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evolvedbinary%2Ffordham-ahi-vm-setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evolvedbinary%2Ffordham-ahi-vm-setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evolvedbinary%2Ffordham-ahi-vm-setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evolvedbinary","download_url":"https://codeload.github.com/evolvedbinary/fordham-ahi-vm-setup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evolvedbinary%2Ffordham-ahi-vm-setup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275440029,"owners_count":25465044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-16T02:00:10.229Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-30T05:34:42.980Z","updated_at":"2025-09-16T15:18:43.151Z","avatar_url":"https://github.com/evolvedbinary.png","language":"Puppet","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fordham University - AHI (Applied Health Informatics) - Virtual Machine\n\nThe following instructions will enable you to setup two things:\n\n1. An [Apache Guacamole](https://guacamole.apache.org/) server that will provide a website for accessing remote machines through a Web Browser.\n\n2. One or More Virtual Machines configured with all of the software required for the purpose of teaching the AHI MSc.\n\n## Obtaining Servers\n\nThis can be setup either in [AWS EC2](https://aws.amazon.com/ec2/), or another Virtual Environment such as KVM running on a Linux Server.\nThe environment (which provided 1x Guacamole Server, and 15x AHI Virtual Machines) and that was used for the 2024 Cohort of the AHI MSc at Fordham University was Ubuntu 24.04 running on a bare-metal server leased via [Evolved Binary](https://www.evolvedbinary.com) from [Hetzner](https://www.hetzner.com/) in Germany, with the following configuration:\n* Xeon E5-1650 v3 @ 3.50GHz (6 Cores / 12 Threads)\n* 128 GB RAM\n* 2x 480GB SSD in RAID 1\n\nBelow we detail two options for setting up Virtual Machines: 1. Hetzner bare-metal server, and 2. AWS EC2.\n\n### 1. Setting up a new Linux KVM VM (optional)\n\nIf you have leased a server from someone like Hetzner with Ubuntu 24.04 installed and wish to set this all up using KVM to host your VMs, then on the server (KVM host) you should run the following commands (assuming an Evolved Binary Server in Hetzner):\n\n```shell\ngit clone --single-branch --branch hetzner https://github.com/adamretter/soyoustart hetzner\ncd ~/hetzner\n\nsudo uvt-simplestreams-libvirt sync --source=http://cloud-images.ubuntu.com/minimal/releases arch=amd64 release=noble\n```\n\nAs IPv4 addresses are becoming less available and therefore more expensive, you can setup either:\n\n\t1. A VM with a Public IPv6 Address and Private IPv4\n\t\tThis can be directly accessible over IPv6 and on the Internet.\n\t\tIf you wish to access it via IPv4 over the Internet you will need to setup some sort of NAT and/or Port Forwarding from another machine that has a Public IPv4 address, see: [Optional - IPv4 Port Forwarding](#optional---ipv4-port-forwarding).\n\n\t2. A VM with a Public IPv6 Address and Public IPv4\n\t\tThis can be directly accessible over IPv6 and IPv4 on the Internet.\n\n#### Option 1 - VM with Public IPv6 and Private IPv4\n\n```shell\n./create-uvt-kvm.sh --hostname fordham-ahi-01 --release noble --memory 8192 --disk 30 --cpu-model host-passthrough --cpu 4 --bridge virbr1 --ip6 2a01:4f8:140:91f0::201 --gateway6 2a01:4f8:140:91f0::2 --dns 2a01:4ff:ff00::add:1 --dns 2a01:4ff:ff00::add:2 --dns-search evolvedbinary.com --private-1-bridge virbr0 --private-1-ip 192.168.122.201 --private-1-next-network 0.0.0.0/0 --private-1-gateway 192.168.122.1 --private-1-dns 185.12.64.1 --private-1-dns 185.12.64.2 --private-1-dns-search evolvedbinary.com --private-2-bridge virbr2 --private-2-ip 10.0.55.201 --private-2-next-network 10.0.1.254/32 --private-2-gateway 10.0.55.254 --auto-start\n```\n\n**NOTE**: There is an issue at the moment with the 2nd private interface not being activated until the VM is shutdown and re-launched. So before you login to the VM fo rthe first time, please wait a few minutes so the VM finishes starting up, and then run:\n\n```shell\nvirsh shutdown fordham-ahi-01\n```\n\nYou should then check the status of the VM until it is shutdown. You can do that by running: `virsh domstate cityehr-work-01`. When the state is `shut off`, you can then restart the VM by running:\n\n```shell\nvirsh fordham-ahi-01\n```\n\n**NOTE**: The VM specific settings are:\n* `--hostname` `fordham-ahi-01`\n* `--ip6` `2a01:4f8:140:91f0::201`\n* `--private-1-ip` `192.168.122.201` (IANA Private)\n\n**NOTE**: The network settings specific to the host are:\n* `--bridge` `virbr1`\n* `--gateway6` `2a01:4f8:140:91f0::2`\n* `--private-1-bridge` `virbr0`\n* `--gateway` `192.168.122.1` (IANA Private)\n\n**NOTE**: The network settings specific to the hosting provider are:\n* `--dns 2a01:4ff:ff00::add:1`, `--dns 2a01:4ff:ff00::add:2`\n* `--dns 185.12.64.1`, `--dns 185.12.64.2`\n\nSee also: [Optional - IPv4 Port Forwarding](#optional---ipv4-port-forwarding).\n\n#### Option 2 - VM with Public IPv6 and Public IPv4\n\n```shell\n./create-uvt-kvm.sh --hostname fordham-ahi --release noble --memory 8192 --disk 30 --cpu-model host-passthrough --cpu 4 --bridge virbr1 --ip 188.40.179.160 --ip6 2a01:4f8:140:91f0::160 --gateway 46.4.100.114 --gateway6 2a01:4f8:140:91f0::2 --dns 2a01:4ff:ff00::add:1 --dns 2a01:4ff:ff00::add:2 --dns 185.12.64.1 --dns 185.12.64.2 --dns-search evolvedbinary.com  --private-1-bridge virbr0 --private-1-ip 192.168.122.160 --private-2-bridge virbr2 --private-2-ip 10.0.55.201 --private-2-next-network 10.0.1.254/32 --private-2-gateway 10.0.55.254 --auto-start\n```\n\n**NOTE**: There is an issue at the moment with the 2nd private interface not being activated until the VM is shutdown and re-launched. So before you login to the VM fo rthe first time, please wait a few minutes so the VM finishes starting up, and then run:\n\n```shell\nvirsh shutdown fordham-ahi\n```\n\nYou should then check the status of the VM until it is shutdown. You can do that by running: `virsh domstate cityehr-work-01`. When the state is `shut off`, you can then restart the VM by running:\n\n```shell\nvirsh fordham-ahi\n```\n\n**NOTE**: The VM specific settings are:\n* `--hostname` `fordham-ahi`\n* `--ip6` `2a01:4f8:140:91f0::160`\n* `--ip` `188.40.179.160`\n* `--private-1-ip` `192.168.122.160` (IANA Private)\n\n**NOTE**: The network settings specific to the host are:\n* `--bridge` `virbr1`\n* `--gateway6` `2a01:4f8:140:91f0::2`\n* `--gateway` `46.4.100.114`\n\n**NOTE**: The network settings specific to the hosting provider are:\n* `--dns 2a01:4ff:ff00::add:1`, `--dns 2a01:4ff:ff00::add:2`\n* `--dns 185.12.64.1`, `--dns 185.12.64.2`\n\n\n### 2. Setting up a new AWS EC2 Instance (optional)\n\nIf you wish to set this up in AWS EC2, then for each Virtual Machine you need should setup a new EC2 instance with the following properties:\n\n1. Name the instance 'fordham-ahi-01'. (change the `01` as needed for more machines).\n\n2. Select the `Ubuntu Server 24.04 LTS (HVM), SSD Volume Type` AMI image, and the Architecture `amd64`.\n\n3. Select `m6a.large` instance type. (i.e.: 2vCPU, 8GB Memory, 1x237 NVMe SSD, $0.0999 / hour).\n\n4. Select the `fordham-ahi` keypair.\n\n5. Select the `fordham-ahi vm` Security Group.\n\n6. Set the default Root Volume as an `EBS` `30 GiB` volume on `GP3` at `3000 IOPS` and `125 MiB throughput`.\n\n\n## Installing Guacamole Server\n\nApache Guacamole provides a web interface for accessing any virtual machine remotely. This is used so that students only need a web-browser. The student accesses Guacamole, and then Guacamole connects them to the remote virtual machine.\n\nGuacamole should be run in its own virtual machine. To install Guacamole and configure it for AHI run the following commands on a new VM:\n\n```shell\ngit clone https://github.com/evolvedbinary/fordham-ahi-vm-setup.git\ncd fordham-ahi-vm-setup\nsudo ./install-puppet-agent.sh\n\ncd guacamole\n\nsudo FACTER_default_user_password=mypassword2 \\\n     /opt/puppetlabs/bin/puppet apply 01-base.pp\n```\n\n**NOTE:** you should set your own passwords appropriately above! The `default_user_password` is used for the Linux user that can access the machine, the username is `ubuntu`.\n\nWe have to restart the system after the above as it may install a new Kernel and make changes to settings that require a system reboot. So run:\n\n```shell\nsudo shutdown -r now\n```\n\nAfter the system restarts and you have logged in, you need to resume from the `fordham-ahi-vm-setup/guacamole` repo checkout:\n\n```shell\ncd fordham-ahi-vm-setup/guacamole\n\nsudo FACTER_default_user_password=mypassword2 \\\n     FACTER_override_custom_user=adam.retter \\\n\t FACTER_override_custom_user_password=fordham \\\n     /opt/puppetlabs/bin/puppet apply .\n```\n\n**NOTE:** you should set your own passwords appropriately above!\n\n* `default_user_password` this is the password to set for the default linux user on this machine (typically the user is named `ubuntu` on Ubuntu Cloud images).\n* `override_custom_user` should be set to the username of the custom user on the remote (AHI workstation) virtual machines that you are trying to access. If not specified, defaults to: `student`.\n* `override_custom_user_password` should be set to the password of the custom user on the remote (AHI workstation) virtual machines that you are trying to access. If not specified, defaults to: `student`.\n\nAfter installation Guacamole's Web Server should be accessible from: [http://localhost:8080](http://localhost:8080), but should be accessible (via an nginx reverse proxy) from: [https://localhost](https://localhost)\n\n\n## Installing an AHI Workstation\n\nYou can install one or more AHI workstations, each should be configured within its own virtual (or physical) machine. We expect to start from a clean Ubuntu Server, or Ubuntu Cloud Image install. This has been tested with Ubuntu version 24.04 LTS (x86_64).\n\n### AHI Software Environment\n\nThe following software will be configured:\n\n* Desktop Environment\n\t* X.org\n\t* LXQt\n\t* Chromium\n\t* Firefox\n\t* Okular\n\n* Java Development Environment\n\t* JDK 11\n\t* JDK 17\n\t* Apache Maven 3\n\t* IntelliJ IDEA CE\n\t* Apache Tomcat 9\n\t* Quercus\n\n* Python Development Environment\n\t* Python 3\n\t* pip3\n\t* miniconda 3\n\n* Database Environment\n\t* MariaDB Server and Client\n\t* MySQL Workbench\n\t* DBeaver\n\n* cityEHR\n\n* cityEHR Workshop Tools\n\t* Mirth Connect and Mirth Administrator\n\t* Oxygen XML Editor\n\t* LibreOffice\n\t* Protégé\n\t* Inkscape\n\t* GanttProject\n\t* FreeMind\n\t* BOUML\n\t* Modelio\n\n* Visual Studio Code\n\n* Miscellaneous Tools\n\t* Nullmailer\n\t* Zsh and OhMyZsh\n\t* Git\n\t* cURL\n\t* wget\n\t* Screen\n\t* tar, gzip, bzip2, zstd, zip (and unzip)\n\n\n### Installing an AHI Workstation\n\nEach AHI Workstation should be run in its own virtual machine. To install an AHI workstation run the following commands on a new VM:\n\n```shell\ngit clone https://github.com/evolvedbinary/fordham-ahi-vm-setup.git\ncd fordham-ahi-vm-setup\nsudo ./install-puppet-agent.sh\n\ncd workstation\n\nsudo /opt/puppetlabs/bin/puppet apply 00-locale.pp\n\nsudo FACTER_default_user_password=mypassword \\\n     /opt/puppetlabs/bin/puppet apply 01-base.pp\n```\n\n**NOTE:** you should set your own passwords appropriately above!\n\n* `default_user_password` this is the password to set for the default linux user on this machine (typically the user is named `ubuntu` on Ubuntu Cloud images).\n\nWe have to restart the system after the above as it may install a new Kernel and make changes to settings that require a system reboot. So:\n\n```shell\nsudo shutdown -r now\n```\n\nAfter the system restarts and you have logged in, you need to resume from the `fordham-ahi-vm-setup/workstation` repo checkout:\n\n```shell\ncd fordham-ahi-vm-setup/workstation\nsudo FACTER_default_user_password=mypassword \\\n  FACTER_override_custom_user=adam.retter \\\n  FACTER_override_custom_user_password=fordham \\\n  FACTER_mariadb_db_root_password=fordhamahi \\\n  /opt/puppetlabs/bin/puppet apply .\n```\n\n**NOTE:** you should set your own passwords appropriately above!\n\n* `default_user_password` this is the password to set for the default linux user on this machine (typically the user is named `ubuntu` on Ubuntu Cloud images).\n* `override_custom_user` this is the username for the linux user account to add to this machine (e.g. for the Student). This should be the part of their Fordham University email address that appears before the `@` sign, e.g. If their email address is `adam.retter@fordham.edu`, then just use `adam.retter`. If not specified, defaults to: `student`.\n* `override_custom_user_password` this is a password for the custom user account. If not specified, defaults to: `student`.\n* `mariadb_db_root_password` - This is the password to set for the `root` user in MariaDB.\n\nWe have to restart the system after the above as it installs a new desktop login manager.\n\n```shell\nsudo shutdown -r now\n```\n\nAfter installation you should be able to access this instance using either one of two mechanisms:\n\n1. Directly, by using an RDP (Remote Desktop Protocol) client, e.g. Microsoft Remote Desktop. This approach usually gives the most responsive performance for the user.\n\t* Clients:\n\t\t* **Windows** - run `mstsc.exe`\n\t\t* **Mac** - Install and run (Microsoft Remote Desktop](https://apps.apple.com/us/app/microsoft-remote-desktop/id1295203466?mt=12) from the Apple Store.\n\t\t* **Linux** - run `rdesktop` (Ubuntu install: `apt-get install -y rdesktop \u0026\u0026 rdesktop`)\n\t* Connection Settings:\n\t\t* **Host**: The IP address or FQDN of the remote machine (e.g. `fordham-ahi-01.evolvedbinary.com`)\n\t\t* **Username**: The part of your Fordham University email address that appears before the `@` sign, e.g. If you email address is `adam.retter@fordham.edu`, then just use `adam.retter`. This is the username you set above for `override_custom_user`.\n\t\t* **Password**: *the password you set above for `override_custom_user_password`*\n\n\n2. Indirectly via the Guacamole website by visiting the website (e.g. [https://fordham-ahi.evolvedbinary.com](https://fordham-ahi.evolvedbinary.com)) in your web browser.\n\t* Login details:\n\t\t* **Username**: Your Fordham University email address, e.g. `adam.retter@fordham.edu`)\n\t\t* **Password**: *the password you set above for `override_custom_user_password`*\n\n\n### Optional - IPv4 Port Forwarding\n\nIf you are using Private IPv4 addresses for the Virtual Machines, and you want to connect to them using RDP over IPv4, you will need to port-forward from a Public IPv4 address (perhaps that used on the Guacamole Server) to each VM.\n\nOn the host with the Public IPv4 address, edit the the file `/etc/sysctl.conf`, and enable the following:\n```\nnet/ipv4/ip_forward=1\nnet/ipv6/conf/default/forwarding=1\nnet/ipv6/conf/all/forwarding=1\n```\nthen run `sudo sysctl -p \u0026\u0026 sudo sysctl --system`.\n\nOn the host with the Public IPv4 address, add the following to the endo fo the file `/etc/ufw/before.rules`:\n\n```\n# NAT\n*nat :PREROUTING ACCEPT [0:0]\n# Port Forward RDP to Fordham AHI VMs\n-A PREROUTING -p tcp -i enp1s0 --dport 3390 -j DNAT --to-destination 192.168.122.201:3389\nCOMMIT\n```\n\nAdd the following to the end of the file `/etc/ufw/before6.rules`:\n```\n# NAT\n*nat :PREROUTING ACCEPT [0:0]\n# Port Forward RDP to Fordham AHI VMs\n-A PREROUTING -p tcp -i enp1s0 --dport 3390 -j DNAT --to-destination 2a01:4f8:140:91f0::201:3389\nCOMMIT\n```\n\nThe above two changes:\n1. Forward TCP port `3390` on the host with the Public IPv4 address to TCP Port `3389` (i.e. RDP) on the host `192.168.122.201`.\n2. Forward TCP port `3390` on the host with the Public IPv6 address to TCP Port `3389` (i.e. RDP) on the host `2a01:4f8:140:91f0::201`.\nYou can add as many rules as you have Virtual Machines.\n\nThen run: \n\nsudo ufw route allow in on enp1s0 out on enp7s0\nsudo ufw route allow in on enp7s0 out on enp1s0\n\n1. `sudo ufw allow in on enp1s0 proto tcp to any port 3390 comment \"For Port Forward to 3389 on fordham-ahi-01\"`\n2. `sudo systemctl restart ufw`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevolvedbinary%2Ffordham-ahi-vm-setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevolvedbinary%2Ffordham-ahi-vm-setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevolvedbinary%2Ffordham-ahi-vm-setup/lists"}