Web UI Quick Start

🚧

Quick navigation

Time to read: 8 minutes, 38 seconds

Jump to: 1. Before you begin | 2. Launch the Orka UI | 3. Create a user | 4. Create and deploy your first VM instance | 5. Experience your VM instance | 6. Create a new base image | 7. Time to say goodbye

🚧

The ultimate quick start

If you want to skip the detailed explanations, just run through these steps on your own:

1. Launch the Orka UI in your browser at http://<Orka-API-endpoint> or https://<orka-domain> or https://<custom-domain>.
2. Create a user.
3. Go to Nodes.
4. Go to Images.
5. Go to VM Configs and click Create config (90GBVenturaSSH.orkasi for image, 6 for CPU and vCPU, leave VNC enabled).
6. Click Deploy Config and wait for the confirmation.
7. Go to VMs and check the connection information for the instance.
8. Run Apple Screen Sharing to connect to the VM instance. Use vnc://<VM-IP>:<Screenshare-port> with the IP and port from Step 7. Use the admin/admin credentials.
9. On the VM, change the login credentials, apply the latest OS updates, and install (or upgrade) the Orka VM Tools.
10. Return to the UI. On the VMs page, select your VM instance and click More > Save as new image at the top.
11. Return to the UI. Go to the Images page and make sure that your new image appears in the list.
12. On the VMs page, select your VM instance and click More > Delete at the top.
13. Make sure that the list of VMs is empty.
14. Go to VM configs and verify that your template is preserved.

The Orka UI is a user-friendly way to get started with Orka. It provides basic capabilities and a clean UI.

The Orka UI will be most useful to:

• beginner users
• users with predominantly manual workflows

1. Before you begin

1. Get your IP Plan. You can download it from the MacStadium portal.
2. Connect to your Orka cluster via VPN.
   1. Download and install a VPN client.
   2. Note that if you're using your Orka domain or an external custom domain(custom-tls-certificate), you might need to make some additional configuration changes.
   3. Use the server address and credentials from the VPN section of your IP Plan.

2. Launch the Orka UI

• In your browser, navigate to your Orka endpoint.

📘

What's your Orka endpoint?

You can get the IP for your Orka endpoint from your IP Plan:

• For clusters deployed before Orka 2.1, it's the .100 address for your Private-1 network (usually, 10.221.188.100).
• For clusters deployed with Orka 2.1 or later, it's the .20 address for your Private-1 network (usually 10.221.188.20).
  You need to use http with the IP.

To get the Orka domain for your Orka cluster, contact MacStadium. To use an external custom domain, see here.

Note that you can use http://<orka-IP>, https://<orka-domain>, and https://<custom-domain> interchangeably in your workflows.

3. Create a user

Orka requires you to create a dedicated Orka user for your cluster. This also creates a dedicated namespace in the cluster. You are the owner of this namespace. When you create a VM config and/or deploy a VM instance from it, they become associated with your namespace. Other users will not be able to manage your VM configs and your VMs and vice versa. Administrators will be able to list, delete, and purge your VM configs and instances.

• Click Don't have an Orka user? Create and fill in the form.

The license key is required for administrative operations. You can get it from your IP Plan.

After you hit Create, the Orka UI logs you in. This also creates and caches a token in your profile. The token is required for most Orka operations and the UI takes care of passing it along, when needed.

👍

Need the token for your user?

If you need to use your token outside of the web UI, click your initials in the top right corner and select Profile. Just copy your token and start using it.

4. Create and deploy your first VM instance

1. In the sidebar, click Nodes. This page provides information about the current state of you nodes, including the available resources.

📘

Glossary: Node

A genuine Apple physical host that provides computational resources (RAM and CPU) for your workloads.

A host OS runs on top and you have no direct access (via VNC, SSH, or Screen Sharing) to it.

2. In the sidebar, click Images.

You will likely see a 90GBVenturaSSH.orkasi item. This is a fully installed and configured macOS Ventura image with a 90GB disk size. It also has an admin user configured and SSH and Apple Screen Sharing access enabled.

📘

Glossary: Image

A disk image that represents VM storage. Base images are bootable disk images that provide the OS, file system, and storage for your VM configs and VMs. Empty images provide added storage or serve as the base image during manual OS installs from ISO.

Intel-based base images are stored in the .img format.

Apple silicon-based base images are stored in the .orkasi format.

3. In the sidebar, click VM Configs.

If this is the first time you're using Orka, you will get a blank screen.

4. On the VM Configs page, click Create config and fill in the form:

• Name: Set any user-friendly name that will help you recognize the VM.
• Base image: Set to 90GBVenturaSSH.orkasi. (Note that the settings in the dialog change based on the selected image type - .orkasi or .img.)
• CPU: Set to 6. This is the number of CPUs for the VM.
• vCPU: Set to 6. Unless CPU is 3, must be half of or the exact number of CPUs. Basically, this indicates if hyperthreading is enabled. If vCPU equals CPU, hyperthreading is enabled.
• Memory (G): Leave blank.This is the default setting.
  When left blank, Orka automatically assigns the memory for your VMs.
  When you provide a value for Memory, this overrides Orka and alots the specified value to the VM.

📘

VM name limitations

The name you specify under VM Name must meet the following requirements:

• Doesn't exceed 38 characters.
• Contains only lowercase Latin alphanumeric characters (0-9, a-z) and dashes (-).
• Begins and ends with an alphanumeric character.

This creates a VM config.

📘

Glossary: VM config

A template for an Orka virtual machine. You can deploy multiple VM instances (VMs) from a single VM config.
To list all VM configs associated with your user, run orka vm configs.

5. On the VM Configs page, select your newly created template and click Deploy config. Make sure that your template is selected and click Deploy.

Wait for the spinner at the bottom of the screen to complete. A success message should pop up at the bottom of the screen.

This deploys a VM instance from your template.

📘

Glossary: VM instance (VM)

A deployed instance of a VM config. VMs take up resources from your nodes and require a certain amount of CPU and RAM to run.
To deploy more instances of the same config, run orka vm deploy.

6. Go to the VMs page. Now that you have deployed your first VM instance, you will see it in the list.

Note how this screen shows essential information about your VM, including its unique ID (required for some advanced operations) and detailed connection information.

👍

Want to see more details?

If you're looking for more information about your VM, click its name in the list.

7. Go to the Nodes page again. Did the number of available resources change?

5. Experience your VM instance

1. Return to the VMs page and click the Connection button for your VM.

2. Launch Apple Screen Sharing on your local machine (In Finder, press Cmd+K). In the Connect to Server dialog, paste the information from the pop-up. (vnc://10.221.189.13:5903 in the example above).

📘

Not working on macOS?

This step works only on macOS. If you're working on a Linux or Windows machine instead, launch your preferred VNC client and connect to <VM-IP>:<VNC-port> (10.10.10.4:6002 in the example above).

One more thing to remember is that Screen Sharing needs to be already enabled on the macOS. Most of the time, this is not the case (especially on clean OS installs or after an ISO install), and you will need to enable the setting yourself. This is the case for SSH as well.

The good news is that 90GBVenturaSSH.orkasi is already preconfigured for you and you can enjoy out-of-the-box Screen Sharing and SSH connectivity.

📘

Are you not using the 90GBVenturaSSH.orkasi image?

If you're using another image as your starting point or if you are installing your OS from ISO, you will likely not have SSH or Screen Sharing enabled by default (even though the respective ports will be mapped by default). In this case, you need to connect to the VM via VNC. You can then enable SSH and Screen Sharing connectivity in the OS.

3. When prompted by Apple Screen Sharing, provide the credentials for the VM (admin/admin). You will be prompted for the password one more time - when Apple connects to the VM.

4. On the VM, launch System Preferences > Users & Groups. Select the Admin user and click Change password. Set the Admin user password to whatever works for you.

5. (Optional) Launch the Terminal and run the following command.

brew install orka-vm-tools

OR

brew upgrade orka-vm-tools

This action ensures that your VM is running the latest version of the Orka VM Tools. This collection of services lets Orka manage the guest operating system on Apple silicon-based VMs more efficiently and enables key features, such as shared VM storage.

If your cluster is not running the latest Orka version, download and install an Orka VM Tools that matches the version of your cluster.

6. Apply the latest OS updates and restart the VM.

6. Create a new base image

Making changes to the configuration or the file system of a running VM does not affect its base image. As soon as you delete the VM, your changes will be lost, and you will need to recreate them manually on other VMs.

To create changes that stick and appear on future deployments, you can save the changes as a new image.

📘

Glossary: Save changes

Save creates a new base image from the current state of the respective VM instance. To use it, you need to create a new VM config that references the new base image.

This operation restarts the VM.

1. Return to the Web UI. On the VMs page, select your VM. Select More > Save as new image.

2. Provide a name for the new image and click Save.

Wait for the operation to complete. It might take a while. Note that there is no progress indicator, but the operation runs in the background. When the operation completes, the dialog closes and a success notification pops up.

3. After the operation completes, go to the Images page. Did your new image appear there?

👍

TIP

To use your newly created image, you need to create a new VM config.

7. Time to say goodbye

This section is optional.

When your VM configs and instances have served their purpose, you can remove them. Orka provides two ways to do that: delete and purge.

📘

Glossary: Delete VM

This operation removes the specified instance(s). You can delete a VM by:

• name (deletes all VM instances with that name)
• name and node (deletes all VM instances with that name from that node)
• ID (deletes the VM instance with that ID)

Delete always preserves the original VM config and you can deploy new VM instances from it.

📘

Glossary: Purge VM

This operation removes all VM instances and the VM config of that name. You can perform a purge even if there are no VM instances deployed.

• On the VMs page, select your VM. Select More > Delete. When prompted, confirm that you want to delete the VM.

When the page refreshes, you should not see any more VM instances. Your VM config is still available on the VM Configs page and you can deploy new instances from it.

Note that the changes you made to your deleted VM instance will not be present on newly deployed instances.

What's next

You're ready to explore the Orka UI on your own. You might find the following resources helpful:

• If you're looking for more advanced features, see CLI Quick Start and API Quick Start.
• Explore Orka Docs for more advanced tasks and tutorials.
• Seek help from the Orka community in the MacStadium Community Slack.
• Get support in the MacStadium portal.
• Is a feature is missing? Please share your feedback with us.
• If you're looking to tap into Kubernetes, see this page.