Merge branch 'main' into jontyms-add-License

.github/workflows/ci.yml

@@ -1,8 +1,8 @@
-name: ci 
+name: ci
 on:
   push:
     branches:
-      - master 
+      - master
       - main
 permissions:
   contents: write
@@ -18,12 +18,7 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
-      - uses: actions/cache@v4
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
-      - run: pip install mkdocs-material 
-      - run: mkdocs gh-deploy --force
+          cache: "pip"
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

.github/workflows/pre-commit.yaml

@@ -0,0 +1,18 @@
+---
+name: pre-commit
+
+on: [pull_request, push]
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          cache: pip
+      - run: python -m pip install pre-commit
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit/
+          key: pre-commit-4|${{ env.pythonLocation }}|${{ hashFiles('.pre-commit-config.yaml') }}
+      - run: pre-commit run --show-diff-on-failure --color=always --all-files

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+---
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.18.4
+    hooks:
+      - id: gitleaks
+        args: [--baseline-path, .github/workflows/gitleaks-baseline.json]

docs/guides/How to Launch an Instance.md

@@ -2,6 +2,11 @@
 
 Launching an instance in OpenStack GUI is a straightforward process that allows you to deploy virtual machines within your cloud infrastructure. Below is a detailed guide on how to create an instance using the Horizon dashboard.
 
+## Prerequisites
+
+- [Setup Guide](./Openstack Setup Guide.md)
+- [Security Groups](./Security Groups.md)
+
 ## Step 1: Navigate to the Instance Tab
 
 1. Go to the **Instance** tab in the Horizon dashboard.
@@ -27,7 +32,7 @@ Launching an instance in OpenStack GUI is a straightforward process that allows
 ## Step 5: Network
 
 1. Specify the **Network** to which you want your instance to connect.
-   - Choose the network that provides the desired connectivity and access for your instance.
+   - Choose External Network unless you know what you are doing
 
 ## Note: * denotes required fields
 
@@ -47,7 +52,24 @@ Launching an instance in OpenStack GUI is a straightforward process that allows
 - After launching the instance, you can monitor its status in the Horizon dashboard.
 - Once the instance is in the "Active" state, click on its name to access its details.
 - From the instance details page, click on the **Console** tab to open a console and access your instance remotely.
-
+
+# Using SSH
+Get the ip address of your instance from horizon. 
+Open up a terminal. For windows I recommend the [new windows terminal](https://aka.ms/terminal). Type ssh then the username for your distro. For example ubuntu is ``ubuntu`` alama is ``alamalinux``. A quick google for ``username cloud image {{distro name}}`` should do the trick. Then type ``ssh {{username}}@{{ip address}}``. Like this ``ssh [email protected]``. 
+
+## Troubleshooting SSH
+
+Adding ``-v`` will show more details about what is going on. ``ssh -v [email protected]``. You can add more ``-vv`` for more details ``ssh -vvv [email protected]``.
+
+1. Is your openvpn on? 
+2. Do you have the right ip adddress?
+3. Is your instance connected to the correct network? ``External Network``
+4. Is your security groups setup correctly?
+5. Is you ssh key added correctly? 
+6. Is ssh trying to use the correct ssh key?
+7. Do you have the correct user name?
+8. Ask for help in #infra-helpdesk on discord. 
+
 ## Conclusion
 
 By following these steps, you can successfully launch an instance in OpenStack GUI, enabling you to deploy virtual machines to meet your computing needs within your cloud environment. Remember to configure your instance with the appropriate settings and resources to optimize its performance and functionality.

docs/guides/How to access Windows Instances.md

@@ -0,0 +1,112 @@
+# How to access Windows Instances on Openstack #
+
+There are 2 main ways to get access and control a Windows Instance on Openstack. This tutorial will cover both methods.
+
+## Prerequesites ##
+
+* A newly created Windows Server Instance on Openstack
+* Access to Infra via OpenVPN OR On the Cyberlab Secure Network
+
+
+
+# Method 1: Using the Openstack Console (Must be used for initial Windows Setup)
+
+Openstack has a built-in console viewer for Instances which allows you to get a true console view of the Instance allowing for easier debugging of the Instance. You will have to use this method to initially setup Windows Server.
+
+## Steps:
+1. On the left plane, choose `Compute` and then `Instances`
+![Instance page](../img/win-guide/instancespage.png)
+2. Click on the Instance to view
+![Instance page](../img/win-guide/instancespage2.png)
+3. Click on the `Console` tab
+![Instance page](../img/win-guide/consoletab.png)
+4. You now have a console view of the Instance! From here you can add an Administrator password to Windows and use the Instance!
+![Instance page](../img/win-guide/consoleview.png)
+
+# Method 2: Using Remote Desktop Connection
+
+Remote Desktop Connection (Also known as RDP somtimes) is a program in Microsoft Windows that allows you to access another Windows computer over a network. Using this method has added benefits such as easy folder sharing, viewing the Instance in full-screen mode, clipboard sharing and more!
+
+By default, Openstack blocks all inbound connections to Instances and therefore we need to make a security group to allow inbound RDP access
+
+Important Note: You cannot directly use this method on the very first time you startup your Instance as Windows requires you to set an Administrator password upon Instance creation. Follow Method 1 to gain initial access to the machine and add a password.
+
+## Step 1: Creating a security group
+1. Connect to Infra via OpenVPN or `Cyberlab Secure`
+2. Go to `horizon.hackucf.cloud` and log into your account
+3. Click on `Network` on the left-hand pane and then `Security Groups`
+![Instance page](../img/win-guide/network_secgroup.png)
+4. On the right-hand side, click on `Create Security Group` and give it a name and description, then press `Create Security Group`
+![Instance page](../img/win-guide/creategroup.png)
+![Instance page](../img/win-guide/creategroup2.png)
+5. On the Manage Security Group Rules screen, click `Add rule`
+![Instance page](../img/win-guide/addrule.png)
+6. Choose the `RDP` Rule in the Rule dropdown, leave all other options as default and click `Add`
+![Instance page](../img/win-guide/addrule2.png)
+
+This new group can be applied to any future Windows Instances to quickly allow RDP access
+
+## Step 2: Adding the security group to your Instance
+1. On the left plane, choose `Compute` and then `Instances`
+![Instance page](../img/win-guide/instancespage.png)
+
+
+2. Click on the Instance to add the security group to
+![Instance page](../img/win-guide/instancespage2.png)
+
+
+3. Click the dropdown arrow on the right and select `Edit Security Groups`
+![Instance page](../img/win-guide/editsecgroup.png)
+
+
+4. Select the appropriate security group and select `Save`
+
+![Instance page](../img/win-guide/choosesecgroup.png)
+
+
+RDP will now be allowed through the Openstack firewall for the instance!
+
+## Step 3: Connecting to the instance
+1. Open your remote desktop client
+    * Windows Clients: Open Start Menu > type in "Remote Desktop Connection"
+    * MacOS Clients: [Windows App](https://apps.apple.com/us/app/microsoft-remote-desktop/id1295203466?mt=12)
+    * Linux Clients: [Remmina](https://remmina.org/)
+2. Enter the IP address of your Instance and press `Connect` (You can find this in Compute > Instances)
+
+![Instance page](../img/win-guide/rdp.png)
+
+3. Enter the credentials for the Instance and select OK
+
+![Instance page](../img/win-guide/rdp2.png)
+
+4. You will be successfully connected to the Instance!
+
+![Instance page](../img/win-guide/rdp_final.png)
+
+
+# Retrieving Windows Password
+
+To retrieve the Windows password for an instance in OpenStack Horizon, you need to follow these steps. This process assumes that you have created the instance with an SSH key, which is necessary for decrypting the password.
+
+## Step 1: Creating an Instance with an SSH Key
+
+1. On the left pane, choose `Compute` and then `Instances`.
+2. Click on `Launch Instance`.
+3. Fill in the necessary details for your instance, such as the instance name and flavor.
+4. Under the `Key Pair` section, select an existing key pair or create a new one. This key pair will be used to decrypt the Windows password. **Ensure the key is a RSA key.**
+![RSA_key](../img/win-guide/rsa_key.png)
+
+
+## Step 2: Retrieving the Windows Password
+
+1. On the left pane, choose `Compute` and then `Instances`.
+![Instance page](../img/win-guide/instancespage.png)
+2. Click on the instance for which you want to retrieve the password.
+![Instance page](../img/win-guide/instancespage2.png)
+3. Click on the `Actions` dropdown menu on the right and select `Retrieve Password`.
+![dropdown password](../img/win-guide/dropdown_password.png)
+4. In the `Retrieve Password` dialog, click on `Choose File` and upload the private key file associated with the SSH key pair used during instance creation.
+![retrieve password](../img/win-guide/retrieve_password.png)
+5. Click on `Decrypt Password`. The decrypted password will be displayed.
+
+You can now use this password to log in to your Windows instance via the OpenStack console or Remote Desktop Connection.

docs/guides/OpenStack Stepup Guide.md → docs/guides/OpenStack Setup Guide.md

@@ -11,35 +11,35 @@
 1. Go to [https://openvpn.net/client/](https://openvpn.net/client/).
 2. Download the appropriate version of OpenVPN for your operating system and install it.
 
-   ### For Windows:
+### For Windows:
 
    - Press the Windows key and search for OpenVPN.
    - Run OpenVPN.
    ![alt text](<../img/Run Openvpn.png>)
    - On the bottom right of your screen, open the overflow icon menu.
    - Right-click on the OpenVPN icon and select "Import Profile".
    ![alt text](<../img/Import profile.png>)
-   - Click on the "FILE" tab.
+   - Click on the "UPLOAD FILE" tab.
    - Press "Browse" and navigate to where you downloaded the HackUCF OpenVPN profile.
    - Select the profile and press "Open".
    - Press "Connect".
    - In the future, navigate to the OpenVPN client and select the on switch labeled "vpn.hackucf.org".
 
-   ### For Windows 10 Users:
+### For Windows 10 Users:
 
    - If you don't already have the new Windows Terminal, download it from [https://aka.ms/terminal](https://aka.ms/terminal).
 
 ## Step 3: Create SSH Key
 
 1. Open a terminal.
-2. Run `ssh-keygen`.
+2. Run `ssh-keygen -t rsa`.
 3. Press Enter to save the key in the default location.
 4. Press Enter for an empty passphrase.
 5. Press Enter again to confirm.
 ![alt text](<../img/ssh KeyGen.png>)
 
 ## Step 4: Login With Keycloak
-0. Navigate to https://horizon.hackucf.cloud
+0. Navigate to [https://horizon.hackucf.cloud](https://horizon.hackucf.cloud)
 1. Select login with Hack@UCF SSO
 ![alt text](<../img/Login With SSO.png>)
 2. (These other steps are just for the first time)
@@ -51,8 +51,12 @@
 ## Step 5: Horizon.hackucf.cloud Configuration
 
 1. In OpenStack, navigate to "Compute" -> "Key Pairs".
-2. Click "Import Key Pair".
+2. Click "Import Public Key".
 3. Name it something reasonable.
 4. Set "Key Type" to "SSH Key".
 5. Paste the contents of your id_rsa.pub file here, or use "Load Public Key from a file" to upload it.
-![alt text](<../img/Key pairs Page.png>)
+![alt text](<../img/Key pairs Page.png>)
+
+# Next Steps
+
+- Go to [Security Groups](./Security Groups.md)

docs/guides/Overview of OpenStack GUI.md

@@ -49,3 +49,7 @@ Used for redundant, scalable data storage using clusters of standardized servers
 - **Projects**: Lists available projects.
 - **Users**: Lists all users in the project.
 - **Application Credentials**: Temporary credentials allowing applications to authenticate to OpenStack.
+
+# Next Steps
+
+- Go to [OpenStack Setup Guide](./OpenStack Setup Guide.md)