144 lines
9.0 KiB
Markdown
144 lines
9.0 KiB
Markdown
# 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](https://www.ubuntu.com/).
|
|
|
|
[VSCode](https://code.visualstudio.com) was used as the editor with the [Prettier - Code Formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode).
|
|
|
|
## macOS
|
|
|
|
You must install the following:
|
|
|
|
- [Git v2.14.1](https://git-scm.com/)
|
|
- [NodeJS v9.11.1](https://nodejs.org/en/)
|
|
- [MongoDB v3.6.3](https://www.mongodb.com/)
|
|
- [RabbitMQ v3.6.12](https://www.rabbitmq.com/)
|
|
- [Redis v4.0.8](https://redis.io/)
|
|
|
|
All of these can be installed with [Homebrew](https://brew.sh/) and managed with the `brew services` command.
|
|
|
|
We recommend using the [snap-tool](https://www.npmjs.com/package/snap-tool) to easily run all the backend systems locally. Run `npm install -g snap-tool`. You will also need to install [iTerm2](https://www.iterm2.com/) which is a scriptable replacement for the macOS Terminal app.
|
|
|
|
Follow the instructions on `npm` for installing additional dependencies for the [`canvas`](https://www.npmjs.com/package/canvas) package.
|
|
|
|
Install [Xcode](https://developer.apple.com/xcode/) and [Android Studio](https://developer.android.com/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](https://facebook.github.io/react-native/) apps. You need to manage their builds and dependencies manually.
|
|
|
|
Once the above software is installed:
|
|
|
|
```bash
|
|
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](https://www.npmjs.com/package/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.js` file.
|
|
- Website config is in the `.env` file.
|
|
- 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](https://docs.viromedia.com/) for the AR viewer
|
|
- [react-native-maps](https://github.com/react-community/react-native-maps) for the Apple & Google maps
|
|
- [react-native-image-picker](https://github.com/react-community/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](https://github.com/viromedia/viro/issues/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](https://www.npmjs.com/package/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](https://www.npmjs.com/) and [Cocopods](https://cocoapods.org/) components.
|
|
|
|
Installation of Cocoapods is covered in the [Cocoapods Getting Started Guide](https://guides.cocoapods.org/using/getting-started.html) We recommend using a Ruby version manager such as [rbenv](https://github.com/rbenv/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](https://facebook.github.io/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](https://github.com/jlyonsmith/HowTo/blob/master/CheatSheets/Apple.md).
|
|
|
|
## 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](https://github.com/jlyonsmith/HowTo/blob/master/Build_React_Native_Android_APK.md). 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](https://console.cloud.google.com/apis/dashboard). 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](https://www.npmjs.com/package/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](http://es6-features.org/) 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](https://github.com/jlyonsmith/HowTo/blob/master/Install_Ubuntu_16.04_LTS_Service_Instance.md). These are general instructions so adapt them to you needs for this project.
|
|
|
|
We recommend using [Let's Encrypt](https://letsencrypt.org/) and [certbot](https://certbot.eff.org/) 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](https://www.npmjs.com/package/pino) with `cat /var/log/deighton-ar/dar-api.log | pino` for example. Install pino with `npm install -g pino`.
|
|
|
|
Install the [mongo-bongo](https://www.npmjs.com/package/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.
|
|
|