Using Orka, at a Glance

🚧

Time to read: 5 minutes, 22 seconds

Every Orka user has a unique use case and requirements. Whether you're looking to run single Xcode builds or create an automated CI/CD pipeline with daily and nightly builds, your Orka journey will go through the following simple steps.

1. Get ready

1. Get an Orka subscription.
   Contact MacStadium to discuss your requirements. Based on your use case, the team will recommend and provide the best hardware option for your business.

2. Choose your tools.

   • The Orka Web UI provides a quick and user-friendly way to manage your Orka cluster. The Web UI is currently in Beta and provides limited functionality compared to the Orka CLI and the Orka API.
   • The Orka CLI is the easiest way to get started with Orka. It's perfect for manual use and one-time tasks that don't require a lot of automation.
   • If you're looking to build an automated CI/CD system, look into the available Orka integrations - from Jenkins to Drone, the Orka team is continuously adding to the list of supported solutions.
   • The Orka API gives you the freedom to be tool-agnostic or develop an in-house solution. It's ideal for advanced users or more complex use cases that require more control and automation.

3. Learn to speak Orka.

2. Get set

1. Connect to your cluster via VPN. Make sure that you have an up and running VPN connection every time you work with Orka.

   1. Get your IP Plan.
   2. Get a VPN client.
   3. Keep the VPN connection to your cluster live.

2. Configure your environment. This step is a one-time effort.

   • In the Orka CLI, run orka config. Provide your Orka API endpoint and your Orka license key (available in your IP Plan).
   • For Orka API calls, target your Orka API endpoint.
   • For CI/CD integrations, configure your Orka API endpoint as prompted during the setup.

📘

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 and obtain a token. Keep your license key handy. Your token authenticates you uniquely with Orka. It's required for non-administrative operations.
   • In the Orka CLI, run orka user create and choose to log in immediately. This operation caches your token locally.
   • With the Orka API, send a POST request to /users with an email and password in the body. This operation creates a user, but you still need to get a token. Next, send a POST request to /token with the email and password for your user. Grab the token from the response and pass it with your Authorization: Bearer <token> headers from now on.
   • For CI/CD integrations, use the CLI or the API to create a user. Most Orka integrations will let you provide the user credentials, and will take care of getting and caching the token.

3. Go

1. Create a VM config. For CI/CD, you might need to create an SSH-enabled VM config.

To create a VM config, you need an image. Check what images are available. If nothing looks good, check out the remote and pull an image from there. The images available out-of-the-box provide a pre-configured disk size and a pre-installed OS.

If you want to use a different disk size or a different OS that you install yourself, you can go the ISO way. Create an empty image of sufficient size and attach an ISO to your config.

2. Deploy instances from the config. Deploy as many or as few as you need.

You can connect to your VMs via VNC, SSH, or Apple Screen Sharing. Once connected, you can make changes to the VM, such as installing extra software, enabling OS features, and others. For more information, see VNC, SSH, and Screen Sharing for Orka VMs.

You can preserve the changes from one VM and deploy new VMs with these exact changes on them. Save or commit your changes to preserve them and make them available for future configs and deployments. If you used commit, you can keep using your original VM config to deploy new VMs. If you used save, you need to create a new VM config.

3. (Optional) Destroy unused instances and configs.

Delete instances you no longer need and, if your workload demands it, deploy fresh instances from your config. If you no longer need a config, you can purge it.

What's next

Choose how you want to get started with Orka.