Deighton AR Training System
This is the repository for the Deighton AR Training System.
Each section below outlines the steps required to set up, build and deploy the software on different operating systems.
In development you run local copies of the web server, backend REST API, image processing and email services. In production, these backend services run on an Ubuntu server.
All development for this system was done on macOS 10.3.4. Production deployment was done on Ubuntu v16.04 LTS.
VSCode was used as the editor with the Prettier - Code Formatter.
macOS
You must install the following:
All of these can be installed with Homebrew and managed with the brew services command.
We recommend using the snap-tool to easily run all the backend systems locally. Run npm install -g snap-tool. You will also need to install iTerm2 which is a scriptable replacement for the macOS Terminal app.
Follow the instructions on npm for installing additional dependencies for the canvas package.
Install Xcode and Android Studio. For development, it's easier to do the initial builds of the apps inside Xcode or Android Studio. Production builds can then be done on the command line.
Note that both iOS and Android apps are "ejected" React Native apps. You need to manage their builds and dependencies manually.
Once the above software is installed:
git clone https://<user>:<password>@git.kss.us.com/deighton/deighton-ar.git
cd deighton-ar
snap install
snap start -a
The <user>:<password> will have been supplied to you separately.
If all is well you should see a new terminal window start containing the website server, API service, image service and email service and the Metro bundler for development builds of the mobile apps. A local instance of the website will be open in your default browser.
Versioning
For versioning you'll need to install the stampver tool. Before doing production builds and deployments run stampver -u to update the version numbers across all components of the app. Commit the changed files.
Configuration
In addition to the package.json files, the app has configuration in several places:
- Mobile config is in the
config.jsfile. - Website config is in the
.envfile. - Server config is in the
config/directories.
You'll need to familiarize yourself with the settings in each of these files. On the server side there is a lot of configuration related to the sending of emails for email and password management.
There is also a secret backend selector in the app. Simply tap on the Deighton logo on the login screen 9 times to open up a panel that will let you select either a production, test or local backend for development.
Mobile
The mobile apps are written using React Native. The apps are "ejected" so they require manual steps to build and release.
They use the following third party components that include native code:
- ViroAR for the AR viewer
- react-native-maps for the Apple & Google maps
- react-native-image-picker for photo selection.
Because of ViroAR the app can only run on a physical device, not a simulator or emulator. By conditionally excluding the <ViroXxx> components you may be able to again run the app in a simulator or emulator. See Issue #175.
Each of these components requires modifications to the native build files of the iOS and Android projects. Please review each of the above project's installation instructions for more details in case you need to modify anything after a future upgrade of these components.
The mobile app uses react-form-binder to bind controlled components to the data objects received from and sent to the API.
iOS App
This iOS app uses a combination of npm and Cocopods components.
Installation of Cocoapods is covered in the Cocoapods Getting Started Guide We recommend using a Ruby version manager such as rbenv.
To build and run the Xcode application in a development mode, first ensure that you have run snap start as mentioned above.
Then start Xcode, open the DeightonAR.xcworkspace, plug in a iPhone and select it as the build target and run the project. The project should start, connect to the Metro bundler, and run the app.
You'll need an Apple Developer account to do production builds and releases. Set up appropriate appID's, certificates, devices and profiles in the developer portal, then use to build an archive for the production scheme (the one that does not end in Dev). Upload to Apple. More information on Apple certificates, identifiers & profiles can be found here.
Android App
Install Android Studio and install version 26 of the Android SDK (corresponding to Android v8.0 Orea release)
Before running the app in development mode, run adb reverse tcp:8081 tcp:8081.
To run the Android mobile app, start Android Studio, open the mobile/android project, plug in an Android device and run the project.
To build a release version of the Android app run:
cd mobile
npm run build:android
You'll need to first create a release keystore. The script will display the full file name of the .apk file.
Application keys
ViroAR needs an application key which you can apply for on their website and place in the config.js file.
Google Maps needs an application key which you can apply for from the Google API Console. You'll need a key for Android and a key for the Google Geocoding API.
You need to place the Geocoding API key in the config.js file and the map key in the AndroidManifest.xml file.
Website
The website is written in React. It does not use Redux, but instead uses the react-form-binder to bind react controlled components to data from an API. Aside from that it is a fairly standard React application. Note that it is written in Javascript ES6 including experimental decorators. Babel is used to transpile to compatible Node or browser syntax.
Ubuntu
On a clean Ubuntu machine you'll need to follow the instructions in Install Ubuntu 16.04 LTS Service Instance. These are general instructions so adapt them to you needs for this project.
We recommend using Let's Encrypt and certbot to manage SSL certificates on your system. See their instructions on how to create a key for your domain.
The file server/nginx.conf gives an example of the correct nginx configuration.
Don't forget to manually create service log file directories with permissions for the ubuntu user:
sudo mkdir /var/log/deighton-ar
sudo chown ubuntu:ubuntu /var/log/deighton-ar
The log files are in JSON format. You can dump them using pino with cat /var/log/deighton-ar/dar-api.log | pino for example. Install pino with npm install -g pino.
Install the mongo-bongo tool to manage passwords for MongoDB. Follow the instructions for that tool to create admin and user database users. Insert the generated passwords from the ~/.bongo/credentials.json5 file into the service/config/local-production.json5 file.
Start the deighton-ar service with sudo systemctl start deighton-ar, which will start the API, image and email services simultaneously. Then run sudo systemctl status deighton-ar. If all is well you should see a green active (running) message.
For subsequent deployments of the service, run cd service && npm run build && npm run deploy. For the website, run cd website && npm run build && npm run deploy You will need to modify the package.json scripts in those directories to specify the correct target system to deploy too.
Backup the database periodically with bongo backup <db-name> and store the archive on a different system.