ethorn / eit-web-ar

The project I worked on during my summer internship at Equinor. We explored the potentials of Augmented Reality using web frameworks like A-frame and AR.js.

Emerging IT - Web AR

Summer 2020 Internship Project

The challenges for the average Equinor employee to use dedicated AR devices in a office environment are

• Devices are not easily available
• Devices require setup on dedicated machines
• Equinor managed pcs are a no-go due to the way they are locked down
• Management of both device setup and usage scenarios are too cumbersome for quick and easy show and tell demos, or simply exploration of a 3d design you are working on

To be able to make (a limited subset of) the possibilities of AR available to as many people as possible we can

• Use their mobile phone as device
• Use a web app so that no installations is required
• And then help tracking by using QR codes or GPS coords for where AR should kick in

By using WebXR we trade (advanced) device capabilities to gain user availability - both for end-users and developers. By gaining easy availability we hope to be able to quickly explore use cases where "lightweight" AR can enhance the daily work experience.

Table of contents

For developers

• Technology
• Components
• Security
• Development
• How we work
• Documentation

For users

• User guide

For Equinor

• Final report is available in the following formats
  • docx
  • pdf
• Documentation

Technologies

• A-Frame JS
  Web VR library built on top of three.js

  • Experiment with AR and A-Frame
  • Image Tracking and Location-Based AR with A-Frame and AR.js 3

• AR.js
  Web AR library that works well with A-frame.

• nginx
  Simple web server for static content, handle public routing

• NodeJS
  Serverside javascript

  • Express for creating a REST API.
  • Socket.io for WebSocket communication.

• Redis
  Redis is an open source (BSD licensed), in-memory data structure store, used as a database, cache and message broker

• Docker
  For hosting the web app anywhere and to run local development environments To quickly get up to speed with docker then run through the Learn Docker & Containers using Interactive Browser-Based Scenarios at katacoda

• OAuth2 proxy
  A reverse proxy and static file server that provides authentication using Providers (Google, GitHub, and others) to validate accounts by email, domain or group. We use it as a proxy container in front of the app container to simplify integration with an Azure AD app.

• Omnia Radix
  CICD and hosting

CICD

• webpack
  Build and bundle the web components of the app

• Docker
  We use multistage dockerfiles to build the images. docker-compose is used for development purposes only.

• Omnia Radix
  CICD and hosting in the playground environment. Radix configuration is mainly handled in radixconfiguration.yaml

Components

Core

• frontend
  A client side web app.
  nginx acts as a "backend" in that it

  • Serve static js/css/html to the client
  • Route /api to the backend component

• backend
  Handle business logic for multiplayer scenarios.
  It is a nodejs server running express to expose a REST api.
  Dependent on component storage for, well, data storage.

• storage
  Storage is a simple redis container with no file storage or backup

Additional components when app is available in Radix (public)

• auth-proxy
  Main entry point for the app when making the app available to the public in radix.
  It allows traffic to the frontend component if the aad app authenticate the user. Based on radix auth proxy example

• aad app
  OAuth in Azure

Security

• Authentication

  • Who: All Equinor employees
  • What: auth-proxy
  • Where:
    • Azure AD app EIT Web AR AD App, see configfile azure.env for details
    • Auth proxy configuration in radixconfig.yaml
    • Credentials are set as secrets in each host environment in Radix (see CICD)

• Network

  • What: https
  • Where:
    • Internet facing app use TLS cert provided by Radix
    • Local dev app served by webpack use a selfsigned cert issued by webpack

• Keyvault

  • What: az keyvault
  • Where: eit-web-ar, owned by EIT

• CICD

  • What: Radix Playground
  • Where: https://console.playground.radix.equinor.com/applications/eit-web-ar
  • Who: AZ AD group EIT Web AR (1c15fcc6-3f69-4db7-a8ee-b4d86c293c35)

• Hosting

  • What: Radix Playground
  • Where:
    • Production, (git branch release)
    • Development, (git branch master)
  • Who: See "CICID"

• Docker

  • What: Release image does not have root privilieges
  • Where:
    • dockerfile.frontend
    • dockerfile.backend
    • dockerfile.storage

• Credentials
  The component storage is the only component that use credentials, see storage/security for details.
  The local development share all credentials by using a docker-compose .env file, see README/Storage credentials in shared .env file

Development

Each component has a docker-compose.yaml that contains everything we need to run a development environment for that specific component, while the other components are run using their production dockerfiles. See each component README for how to get it up and running.

If you need to have the development environment for all components available at the same time then use the ./docker-compose.yaml found in repo root.

Storage credentials in shared .env file

We make use of docker-compose .env file to insert credentials as environment variables in the storage and backend container.
This .env file is shared among the development environments (docker-compose) for all the app components.

1. Create your own .env file in root of repo
2. Add variables in key=value format

   REDIS_PASSWORD=<insert-your-password>

3. Make sure .env is gitignored!