AR Cloud OVA Image Deployment
The provided image contains all the necessary infrastructure and services pre-configured to be able to manage and work with the Magic Leap devices. This allows to set up a Virtual Machine (VM) quickly and access the services without a complex deployment process. For this to work certain, compromises had to be taken:
- The AR Cloud bundle needs to be installed when running the virtual machine for the first time
- High-availability for the services is disabled to limit the required resources
- The observability stack is not installed
The above limitations can be overcome by reconfiguring the infrastructure and services, but it requires additional steps to be taken.
Taking all the above into consideration, the provided image is not suitable for scalable and fault-tolerant deployments in production environments! Instead, it is a means of quickly testing the services and devices.
Download
The images are available on the Magic Leap 2 Developer Portal.
You must be logged in to the Developer Portal for these links to appear. You can log in by clicking the "person" icon in the upper-right corner of the window at the link above.
To download an image the approval of the Software License Agreement is required.
Download the latest version of an image for the runtime environment of your choice. The OVA image supports the majority of the environments, except for MacBooks with Apple Silicon chipsets, in which case the UTM image should be used.
Requirements
Virtualization Support
Make sure hardware-assisted virtualization is enabled for the host machine's CPU:
- Debian/Ubuntu
- Windows
- MacOS
grep -cw vmx /proc/cpuinfo
The output should be 1.
Using Command Prompt
Run Command Prompt as administrator and run:
systeminfo.exe
The Hyper-V Requirements should be shown at the end with all the values set to Yes.
If the Hyper-V Requirements display the message "A hypervisor has been detected. Features required for Hyper-V will not be displayed." instead of the actual requirements, it means a hypervisor is already running on the machine and it will prevent VirtualBox from using hardware-assisted virtualization.
Using PowerShell
Run PowerShell as administrator and run:
Get-ComputerInfo -property "HyperVRequirement*"
The output should be True for all of the properties.
If the output is empty, it means a hypervisor is already running on the machine and it will prevent VirtualBox from using hardware-assisted virtualization.
(Optional) Disable the Hypervisor Launch
In case the hypervisor is running, it should be disabled in the boot configuration:
bcdedit /set "{current}" hypervisorlaunchtype Off
The machine will need to be restarted for the changes to take effect.
sysctl machdep.cpu.features | grep -cwi vmx
sysctl kern.hv_support
One of the commands should output 1.
If virtualization is not enabled, follow these steps to enable it:
- Generic Steps
- Windows
- HP
- Dell
- Restart your computer
- Enter BIOS while the computer is booting up
- Find the Virtualization Technology (VTx) setting, e.g. from different versions of BIOS:
- "Security -> System Security"
- "System Configuration -> Device Configuration"
- Enable the setting
- Save changes and boot your OS
Windows Instructions for enabling the Virtualization Technology (VTx).
HP Instructions for enabling the Virtualization Technology (VTx)
DELL Instructions for enabling the Virtualization Technology (VTx)
After enabling the Virtualization Technology (VTx) verify that it is now supported by your OS by re-running the corresponding command.
If the host machine does not support hardware-assisted virtualization, the virtual machine will not be able to run.
Resources
To be able to comfortably use the virtual machine, the following resources are needed for the guest system:
- CPUs: 8
- Memory: 16GB
- Disk: 100GB
In case of performance issues, the resources can be increased after stopping the VM.
The resources mentioned above only include the virtual machine itself. If you are running it on a local machine, you need more resources for the operating system and other running software.
Firewall
The following ports need to be exposed to use the provided services:
80
- HTTP443
- HTTPS1883
- MQTT8883
- MQTTS
Additionally, a SSH server is configured on the virtual machine and is running on port 22
. The traffic on port 22
is
forwarded to port 2222
when using VirtualBox or UTM.
Depending on the runtime environment, the firewall configuration might differ:
- Configure your local firewall (if you have one) when running on a local machine
- Configure a cloud firewall based on documentation from your cloud provider otherwise
Runtime Environments
The virtual machine image can be run on a variety of local or cloud environments. Choose from the following supported platforms:
Environment | Platform | Image type |
---|---|---|
Local | Linux - VirtualBox | OVA |
Windows - VirtualBox | OVA | |
macOS Intel (x86_64) - VirtualBox | OVA | |
macOS Apple Silicon (arm64) - UTM | UTM | |
Cloud | GCP - Compute Engine | OVA |
AWS - EC2 | OVA |
Local Machine
The virtual machine image can be run on a laptop/desktop computer or a server that is either not virtualized or that supports nested virtualization. This approach might be suitable for developers that need to run AR Cloud locally or when it is required to have the services running inside a private network.
- Debian/Ubuntu
- Windows
- MacOS
Download VirtualBox for Linux or for Debian-based Linux distributions on amd64 CPUs you can install VirtualBox with the following commands:
curl -sSL https://www.virtualbox.org/download/oracle_vbox_2016.asc | sudo gpg --dearmor --yes --output /usr/share/keyrings/oracle-virtualbox-2016.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/oracle-virtualbox-2016.gpg] http://download.virtualbox.org/virtualbox/debian $(lsb_release -cs) contrib" | sudo tee /etc/apt/sources.list.d/virtualbox.list
sudo apt update
sudo apt install VirtualBox-7.0
VirtualBox Limitations
When running on Linux/MacOS using VirtualBox from a user account, ports below 1024
will not be forwarded by default
due to lack of permissions.
The VirtualBox binary has the setuid
bit set, so setting capabilities on it will not work. Instead, it provides an
override which allows forwarding the privileged ports.
When running VirtualBox in headless mode, set the following environment variable before starting the virtual machine:
export VBOX_HARD_CAP_NET_BIND_SERVICE=1
When using the graphical interface, add the above line to one of your user profile files (~/.profile
,
~/.bash_profile
or ~/.zprofile
depending on your configuration), so it is set on login. Make sure to log out and log
in again for the changes to take effect.
Alternatively, install socat
and run it from the root
account to forward traffic on these ports to the virtual
machine:
When using an IP address and/or HTTP, only:
sudo socat TCP-LISTEN:80,fork TCP:localhost:8080
When using a domain with a TLS certificate:
sudo socat TCP-LISTEN:443,fork TCP:localhost:8443
Make sure the socat
process is running while you are using the image.
Importing the Appliance
- Start VirtualBox
- Select File > Import Appliance... from the menu
- Select the downloaded OVA file from your disk and click Next
- Uncheck the Import hard drives as VDI option
- Click Finish
- When the appliance has finished loading, select it from the left panel and click on Start
When the virtual machine starts log in by using the credentials provided below, select a deployment option and continue from there.
You can also run the imported virtual machine in headless mode:
vboxmanage startvm arcloud-ova --type=headless
Download VirtualBox for Windows.
Importing the Appliance
- Start VirtualBox
- Select File > Import Appliance... from the menu
- Select the downloaded OVA file from your disk and click Next
- Uncheck the Import hard drives as VDI option
- Click Finish
- When the appliance has finished loading, select it from the left panel and click on Start
When the virtual machine starts log in by using the credentials provided below, select a deployment option and continue from there.
You can also run the imported virtual machine in headless mode:
vboxmanage startvm arcloud-ova --type=headless
Intel Chip - VirtualBox
All newer MacBooks have non-Intel architectures, instead using "Apple Silicon" chipsets (M1 or M2). If you have one of these M1 or M2 processors in your Mac, VirtualBox will not run and you need to follow the instructions for UTM below.
Download VirtualBox for MacOS and Intel CPUs.
VirtualBox Limitations
When running on Linux/MacOS using VirtualBox from a user account, ports below 1024
will not be forwarded by default
due to lack of permissions.
The VirtualBox binary has the setuid
bit set, so setting capabilities on it will not work. Instead, it provides an
override which allows forwarding the privileged ports.
When running VirtualBox in headless mode, set the following environment variable before starting the virtual machine:
export VBOX_HARD_CAP_NET_BIND_SERVICE=1
When using the graphical interface, add the above line to one of your user profile files (~/.profile
,
~/.bash_profile
or ~/.zprofile
depending on your configuration), so it is set on login. Make sure to log out and log
in again for the changes to take effect.
Alternatively, install socat
and run it from the root
account to forward traffic on these ports to the virtual
machine:
When using an IP address and/or HTTP, only:
sudo socat TCP-LISTEN:80,fork TCP:localhost:8080
When using a domain with a TLS certificate:
sudo socat TCP-LISTEN:443,fork TCP:localhost:8443
Make sure the socat
process is running while you are using the image.
Importing the Appliance
- Start VirtualBox
- Select File > Import Appliance... from the menu
- Select the downloaded OVA file from your disk and click Next
- Uncheck the Import hard drives as VDI option
- Click Finish
- When the appliance has finished loading, select it from the left panel and click on Start
When the virtual machine starts log in by using the credentials provided below, select a deployment option and continue from there.
You can also run the imported virtual machine in headless mode:
vboxmanage startvm arcloud-ova --type=headless
Apple Chip - UTM
UTM offers native support for running images on Apple Silicon-based hardware.
Download UTM
Open the
.dmg
image and follow the instructions to install UTM on your systemExtract the downloaded AR Cloud UTM file:
tar xzf arcloud-ova.utm.tgz
Open the extracted AR Cloud UTM file - the UTM app should import it automatically
Click on the Play button to start the virtual machine
When the virtual machine starts log in by using the credentials provided below, select a deployment option and continue from there.
Cloud Providers
In case local machines are not available or the services need to be available publicly, it is also possible to deploy the virtual machine image to the supported cloud providers described below.
- GCP
- AWS
Make sure you have the Google Cloud CLI installed.
Check the GCP documentation or follow the steps below:
Prepare details about your GCP project and user account:
export GCP_PROJECT_ID=my-project-id
export GCP_PROJECT_NUMBER=1234567890
export GCP_USER_EMAIL=me@my-domain.comEnable the Cloud Build API (this creates the Cloud Build service account automatically):
gcloud services enable cloudbuild.googleapis.com --project $GCP_PROJECT_ID
If your user account already has the
roles/owner
role on the project:gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
--member "user:$GCP_USER_EMAIL" \
--role 'roles/storage.objectAdmin'Otherwise, grant the required IAM roles:
to your user account:
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
--member "user:$GCP_USER_EMAIL" \
--role 'roles/storage.admin'
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
--member "user:$GCP_USER_EMAIL" \
--role 'roles/viewer'
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
--member "user:$GCP_USER_EMAIL" \
--role 'roles/resourcemanager.projectIamAdmin'
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
--member "user:$GCP_USER_EMAIL" \
--role 'roles/cloudbuild.builds.editor'to the Cloud Build service account:
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
--member "serviceAccount:$GCP_PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role 'roles/compute.admin'
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
--member "serviceAccount:$GCP_PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role 'roles/iam.serviceAccountUser'
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
--member "serviceAccount:$GCP_PROJECT_NUMBER@cloudbuild.gserviceaccount.com" \
--role 'roles/iam.serviceAccountTokenCreator'to the Compute Engine service account:
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
--member "serviceAccount:$GCP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role 'roles/compute.storageAdmin'
gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
--member "serviceAccount:$GCP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
--role 'roles/storage.objectAdmin'
Create a GCS bucket:
export GCP_BUCKET_NAME=my-bucket
export GCP_BUCKET_LOCATION=us
gcloud storage buckets create gs://$GCP_BUCKET_NAME --project $GCP_PROJECT_ID --location $GCP_BUCKET_LOCATIONUpload the OVA image to the GCS bucket:
export GCP_OVA_IMAGE='arcloud-1.2.3.ova'
gsutil -o GSUtil:parallel_composite_upload_threshold=250M \
-o GSUtil:parallel_composite_upload_component_size=50M \
cp $GCP_OVA_IMAGE gs://$GCP_BUCKET_NAMECreate a new Compute Engine instance based on the imported OVA image:
export GCP_INSTANCE_NAME=my-instance
export GCP_ZONE=us-central1-c
gcloud compute instances import $GCP_INSTANCE_NAME \
--source-uri gs://$GCP_BUCKET_NAME/$GCP_OVA_IMAGE \
--project $GCP_PROJECT_ID \
--zone $GCP_ZONEMake sure the necessary firewall rules are configured.
When importing a new image in the same project, you can start from step 6, but make sure to export all the variables.
Make sure you have the AWS CLI installed.
Check the AWS documentation or follow the steps below:
Prepare details about your AWS account:
export AWS_ACCOUNT_ID=123456789012
The account ID can be obtained by running:
aws sts get-caller-identity --query Account --output text
Create an S3 bucket:
export AWS_BUCKET_NAME=my-bucket
export AWS_BUCKET_REGION=us-east-1
aws s3api create-bucket --bucket $AWS_BUCKET_NAME --region $AWS_BUCKET_REGION --acl privateBucket RegionWhen importing an OVA image the S3 bucket has to be in the same region as the AWS AMI image that is created. Adjust the bucket region to the one where the EC2 instance should be running.
Grant the required permissions:
create a service role with a trust relationship document:
cat >vmimport-trust-policy.json <<EOF
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "vmie.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:Externalid": "vmimport",
"aws:SourceAccount": "$AWS_ACCOUNT_ID"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:vmie:*:$AWS_ACCOUNT_ID:*"
}
}
}
]
}
EOF
aws iam create-role --role-name vmimport \
--assume-role-policy-document "file://vmimport-trust-policy.json"attach a policy to the created role:
cat >vmimport-role-policy.json <<EOF
{
"Version":"2012-10-17",
"Statement":[
{
"Effect": "Allow",
"Action": [
"s3:GetBucketLocation",
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::$AWS_BUCKET_NAME",
"arn:aws:s3:::$AWS_BUCKET_NAME/*"
]
},
{
"Effect": "Allow",
"Action": [
"ec2:ModifySnapshotAttribute",
"ec2:CopySnapshot",
"ec2:RegisterImage",
"ec2:Describe*"
],
"Resource": "*"
}
]
}
EOF
aws iam put-role-policy --role-name vmimport \
--policy-name vmimport \
--policy-document "file://vmimport-role-policy.json"Multiple BucketsThe role policy above will overwrite any previously attached ones. If you would like to import OVA images in multiple regions, create separate buckets for each region and include them in the
Resource
list above.
Upload the OVA image to the S3 bucket:
export AWS_OVA_IMAGE='arcloud-1.2.3.ova'
aws s3 cp $AWS_OVA_IMAGE s3://$AWS_BUCKET_NAMEImport the OVA image as an AWS AMI image:
cat >ec2-containers.json <<EOF
[
{
"Description": "AR Cloud OVA",
"Format": "ova",
"Url": "s3://$AWS_BUCKET_NAME/$AWS_OVA_IMAGE"
}
]
EOF
aws ec2 import-image --description "arcloud-ova" --disk-containers "file://ec2-containers.json"Note down the import task ID returned by the command.
Monitor the status of the import task until it is in the
completed
status by using the ID from the previous step:aws ec2 describe-import-image-tasks --import-task-ids import-ami-1234567890abcdef0
Find the ID of the imported image (use the date to find the correct image):
aws ec2 describe-images \
--owners $AWS_ACCOUNT_ID \
--filters 'Name=name,Values=import-ami*' \
--query 'Images[*].[ImageId,CreationDate]' \
--output text
export AWS_IMAGE_ID=ami-0abcdef1234567890Generate an updated block device mappings file based on the imported image and modify it to use a Provisioned IOPS SSD volume:
aws ec2 describe-images --image-ids $AWS_IMAGE_ID --query 'Images[0].BlockDeviceMappings' > block-device-mappings.json
sed -ri 's/^(\s+)("VolumeType": )"(.+)"/\1\2"io2",\n\1"Iops": 2000/' block-device-mappings.jsonGNU sedThe above command requires GNU sed to be installed on your system.
Run an EC2 instance using the imported image and the custom volume configuration file:
aws ec2 run-instances \
--image-id $AWS_IMAGE_ID \
--instance-type c5d.2xlarge \
--associate-public-ip-address \
--ebs-optimized \
--block-device-mappings file://block-device-mappings.jsonMake sure the necessary firewall rules are configured.
When importing a new image in the same account, you can start from step 4, but make sure to export all the variables.
Credentials
The virtual machine includes a dedicated arcloud
user with a password set to changeme
.
After initial login, it is encouraged to set a new password using:
passwd
Password access should be disabled entirely for all publicly accessible deployments (e.g. on GCP or AWS). Key-based authentication can be used instead.
Accessing the Running Virtual Machine
To access the virtual machine, the IP address of your machine is needed.
The IP address might differ depending on the target platform:
- for local machines - the loopback interface address (
127.0.0.1
) or the address of another network interface on the machine (e.g.192.168.1.101
) - for cloud providers - the configured/assigned public IP of the instance
To list the available IPv4 addresses on your machine/instance, try the following command:
- Debian/Ubuntu
- Windows
- MacOS
ip -br a | awk '/UP / { print $1, $3 }'
ipconfig /all | findstr /i "ipv4"
scutil --nwi | awk '/flags/ { i=$1; next } /address/ { print i, $3 }'
Verify that your Magic Leap device has an IP address assigned from the same subnet as your machine or the device is able to access one of the IP addresses from the list above (your router allows connectivity between different subnets).
Apart from using the graphical interface directly, you can also access the machine using SSH (this makes it easier to copy the generated credentials):
to a local virtual machine:
ssh arcloud@<ip-address> -p 2222
e.g.:
ssh arcloud@192.168.1.101 -p 2222
to a cloud instance:
ssh arcloud@<ip-address>
e.g.:
ssh arcloud@1.2.3.4
Deployment Options
The remaining commands in this guide will be executed from the instantiated virtual machine, all from the home (~/
)
directory.
The image can be configured to use an IP address or the default arcloud-ova.local
domain with HTTP only.
Alternatively, a custom domain can be used which will trigger the creation of a TLS certificate.
Simple Deployment
With this approach we limit the configuration needed to access the services, but with the cost of lowered security.
Option 1. Use the IP Address Only
If you want to be able to connect to the machine from other devices, the services need to be configured to use an IP address directly.
Run the set_ip.sh
script from inside the virtual machine and provide your IP address as argument:
./set_ip.sh --accept-sla <ip-address>
e.g. :
./set_ip.sh --accept-sla 192.168.1.101
Option 2. Use the Default Domain and Configure Local DNS Overrides
In case you want to use the default domain, run the set_default.sh
script from inside the virtual machine:
./set_default.sh --accept-sla
To be able to access the services, the IP address of the machine where the image is deployed can be set as the target of the pre-configured domain.
The requirement is that the IP should be accessible from the machine in a browser.
Add the following to the bottom of your /etc/hosts
file (may require sudo
):
# arcloud-ova
<IP-address> arcloud-ova.local
<IP-address> smtp.arcloud-ova.local
This will only make the services available on the devices that have the override configured.
Advanced Deployment - Use a Custom Domain with a TLS Certificate
This allows the services to use a custom domain and issue a TLS certificate.
Point your custom domain to the IP address where the virtual machine is available and make sure that all the ports mentioned above are accessible
Run the
set_domain.sh
script from inside the virtual machine and provide your domain as argument:./set_domain.sh --accept-sla <domain>
e.g. :
./set_domain.sh --accept-sla my.domain.com
This is the recommended approach for all publicly accessible deployments (e.g. on GCP or AWS).
Verify Installation
Once the AR Cloud deployment completes, the deployment script will print out the cluster information similar to:
------------------------------
Cluster Installation (arcloud)
------------------------------
Enterprise Web:
--------------
http://<DOMAIN>/
Username: aradmin
Password: <base64-encoded string>
Keycloak:
---------
http://<DOMAIN>/auth/
Username: admin
Password: <base64-encoded string>
MinIO:
------
kubectl -n arcloud port-forward svc/minio 8082:81
http://127.0.0.1:8082/
Username: <base64-encoded string>
Password: <base64-encoded string>
PostgreSQL:
------
kubectl -n arcloud port-forward svc/postgresql 5432:5432
psql -h 127.0.0.1 -p 5432 -U postgres -W
Username: postgres
Password: <base64-encoded string>
Network:
--------
NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
istio-system istio-ingressgateway LoadBalancer <IPv4> <IPv4> 80:31456/TCP,443:32737/TCP,15021:31254/TCP,1883:30231/TCP,8883:32740/TCP 1d
Log in to the Enterprise Console
- Open the Enterprise Console URL (
http://<DOMAIN>/
) in a browser - Enter the credentials for Enterprise Web provided by the deployment script
- Verify the successful login
Register an ML2 device
Web console
Perform the following steps using the web-based console:
- Log in to the Enterprise Console
- Select Devices from the top menu
- Click Configure to display a QR code unique for your AR Cloud instance
ML2 device
Perform the following steps from within your ML2 device:
- Open the Settings app
- Select Perception
- Select the QR code icon next to AR Cloud
- Scan the QR code displayed in the web console
- Wait for the process to finish and click on the Login button
- Enter the user account credentials in the ML2 device web browser
The Enterprise Console should show the registered device on the list.
Display Cluster Information
If you ever need to display the cluster information again, run the following script:
./show_info.sh --accept-sla
Preserving the Virtual Machine State
The virtual machine is configured to preserve all the data created, changes made and configuration set during its usage (e.g. registered devices, generated maps).
For this to work, it needs to be powered off safely as is required for all physical machines. To do it, connect to the virtual machine using SSH and run the following command in the terminal:
sudo poweroff
It might take around 2 minutes to stop all the services and and turn off the virtual machine completely.
If you shut the virtual machine off from VirtualBox, UTM or the cloud vendor interface or will not wait until it closes, your data might be lost.