Meteor Mantra Kickstarter

tl, dr!

This is a starter app for Meteor developers who want to structure their work according to the Mantra Specification.

Please feel welcome to comment on any experience you have with it in the Meteor Forum, but flag with @warehouseman to get my attention. ( for reference, prior discussion venues are available here and, even earlier, here )

Features

You get :

a thoroughly tested application from which to launch your application development.
Use it as a git submodule of your application. Dynamic loading hooks and shell scripts link your app's npm modules into the Kickstarter at build time. Since, it's a git submodule within your app, you can benefit from new improvements made to it, without being forced to to alter your code with each later release.
single command installation of all dependencies and support services
single command build of Android APK, with download from app menu bar.
database flexibility ready with SQLite for development and PostgreSQL or MySql for production, thanks to Sequelize and Apollo.
database seeding with knex
full end to end, functional testing with Chimp and Cucumber
continuous integration and test in CircleCI. (Latest build result :: )
unit testing with Mocha, Chai, Sinon
client side and server side logging to Loggly:
- logatim: isomorphic multilevel logging, that feeds into
- winston server side transports
Mailgun ready password reset example
several different CRUD examples, including
- an isomorphic MongoDB CRUD module in a single NPM package, which contains all client and server elements, as well as all Chimp tests
- a isomorphic Apollo CRUD module in a single NPM package, which contains all client and server elements, as well as all Chimp tests
- user management CRUD module: user registration, password reset, login, logout
full multi-level access control authorizations:
- levels: Owner, Administrator, Staff, Member, Customer, Registered
- acts on: menu items, React components and server side methods
uses mantra-core modularization, with application wide state, composed in pure React JS components with react-komposer (Blaze is not used at all)
Astronomy v2 model schema AND/OR GraphQL model schema
forms based development examples with:
- uniforms: in the 'books' module
- tcomb-form: for most of the CRUD modules
- formsy-react: for user login, registration and password forms. Also formsy-react-components
Switchable Bootstrap Swatches bootstrap theme modules can be switched in and out.
completely linted with eslint, with specs available to editors such as Sublime Text 3

Getting started

My default development, test and run environment is a virtual machine running Xubuntu Xenial Xerus, with 12Gb of disk, 3Gb memory and 2 processors.

If you are in a disposable virtual machine with a recent fresh Ubuntu installation, you can follow the steps below more or less blindly. Please, do NOT do this in a machine that has stuff you care about!

Pull in your GitHub SSH credentials from somewhere, for example a sister VM...
```
pushd ~/.ssh;
scp -r 192.168.122.xxx:/home/you/.ssh .;
popd;
```

Ensure dependencies are clean and up-to-date :

sudo apt-get -y update && sudo apt-get -y upgrade && sudo apt-get -y dist-upgrade && sudo apt-get -y clean && sudo apt-get -y autoremove;

Install and configure git :

sudo apt -y install git;
git config --global user.name "You Yourself";
git config --global user.email "yourself.yourorg@gmail.com";
git config --global credential.helper cache;
git config --global credential.helper 'cache --timeout=36000';
git config --global push.default simple;

Make a parent directory and step into it :
```
mkdir -p ~/projects;
cd ~/projects;
```

Clone our repository and step into it :

git clone git@github.com:warehouseman/meteor-mantra-kickstarter.git;
cd meteor-mantra-kickstarter;

Switch over to our branch :

git checkout AsSub;
git branch # verify being on AsSub;

Run the script to set up for development and testing (installs Java, NodeJS, Chimp, Meteor and the project's NodeJS package dependencies) :
```
meteor npm run install_all;
```
Prepare your settings.json file :

Using template.settings.json.sh you can generate your settings.json file automatically from environment variables. So, if you edit the file settings.sh and then source it, you will load the entries as environment variables
```
cat EXAMPLE_settings.sh;
    export MAILGUN_DOMAIN="";
    export MAILGUN_KEY="";
    export LOGGLY_SUBDOMAIN="";
    export LOGGLY_TOKEN="";
    export PG_DB=""; # PostgreSQL database name
    export PG_UID=""; # PostgreSQL user ID of Meteor app
    export PG_PWD=""; # PostgreSQL user password of Meteor app
    export PG_HST=""; # PostgreSQL server host name
    export PG_BKP=""; # HTTP URL of a PostgreSQL database backup

cp EXAMPLE_settings.sh settings.sh;
nano settings.sh;
source settings.sh;
```
You can keep that file out of harm's way, and using template.settings.json.sh when needed to create settings.json just before launching your Meteor app.
```
./template.settings.json.sh > `settings.json`
```
Obviously, you'll need to go get your Mailgun API key. and your Loggly domain token, to set the corresponding values in settings.sh.
- Note : If you don't care whether password reset works, you don't need Mailgun. In that case, you can use this as your API key ... key-dead0dead0dead0dead0dead0dead000.
Now we can run Meteor and explore at http://localhost:3000 :
```
meteor npm run run_development;
```
(The first time through, you may see it terminate with the message killed. Just run it again.)
Open a new terminal window to run linting and unit-tests :
```
cd ~/projects/meteor-mantra-kickstarter;
npm test;
```
A goodly portion of the client side is fully tested using the familiar tools Mocha, Chai and Sinon.

Open another terminal window and run acceptance tests :

source ~/.profile; # if you haven't logged out since running 'install_all'
cd ~/projects/meteor-mantra-kickstarter;
meteor npm run acceptance;

See the scripts section of package.json for details of other testing and setup commands.

Return to your original terminal window and build for Android :

export KEYSTORE_PWD="obscuregobbledygook";
export HOST_SERVER_NAME="http://moon.planet.sun:3000/";
export ROOT_URL="${HOST_SERVER_NAME}";
export YOUR_FULLNAME="You Yourself";
export YOUR_ORGANIZATION_NAME="YourOrg";

meteor npm run build_all;
meteor npm run run_development;

Debug in Android in a Xubuntu virtual machine :

To see how to debug an Android app between two virtual machines watch Meteor / CircleCI Tutorial -- Bonus - Debug your Android App in a Virtual Machine

Set up server IP address in KitKat machine from the server ...

you@yours:~$ ifconfig                           # Grab IP address to clipboard
you@yours:~$ adb connect 192.168.122.174        # Start a connection to KitKat host (as shown in video)
you@yours:~$ adb devices -l                     # Make sure the host is listed
you@yours:~$ adb shell                          # Get into the Android terminal shell
uid=2000(shell)@x86:/ $ su                      ## Get root privileges
uid=0(root)@x86:/ $ mount -o remount,rw /system ## Allow to write
uid=0(root)@x86:/ $ vi /system/etc/hosts        ### Edit to add the server (paste in IP addresss and whatever you used for ${HOST_SERVER_NAME})
uid=0(root)@x86:/ $ mount -o remount,ro /system ## Go back to read-only
uid=0(root)@x86:/ $ exit                        ## Get out
uid=2000(shell)@x86:/ $ ping moon.planet.sun    # See if it worked

Serve up occasional public demos directly from your developer machine via NGrok:

If you want to see an Android phone running the app from a server on the web, without having to go through all the server setup effort, ngrok makes it easy:
1. Use you GitHub gredentials to log in through NGrok's login/sign-up page
2. Download NGrok
3. Install it somewhere...
```
cd ~;
mkdir -p utilities;
cd utilities;
unzip ~/Downloads/ngrok*.zip;
```
4. Copy Your Tunnel Authtoken from the Auth tab
5. Install your token :
```
./ngrok authtoken 2RCuUd7C8Qi5qMJJQAmD6_25xo9VDPpfiZXgTk2kY8X;
```
6. Start an http tunnel to port 3000 :
```
./ngrok http 3000;
```
7. Return to your project root and build for Android, specifying the ngrok "forwarding" address for the HOST_SERVER_NAME to which remote mobile devices should connect :
```
export EXTERNAL_DOMAIN="a9a18d90.ngrok.io";
export HOST_SERVER_NAME="http://${EXTERNAL_DOMAIN}/";

./build_all.sh;
```
8. Start up meteor on localhost:3000 as usual, but specify ROOT_URL to match HOST_SERVER_NAME.
```
export ROOT_URL="${HOST_SERVER_NAME}";
meteor --settings=settings.json;
```
  You should see :
```
[[[[[ ~/projects/meteor-mantra-kickstarter ]]]]]

=> Started proxy.
=> Started MongoDB.
=> Started your app.
=> App running at: http://a9a18d90.ngrok.io/
```
  You can then tap on the little android robot icon in the menu bar to download the app version for installation in the device.
  
  Note : You can still access the app locally as before.

Other Notes

For my own use, I keep open at least 4 terminal windows, with these commands, ready to run :

For running Meteor

cd projects/meteor-mantra-kickstarter/
meteor --settings=settings.json

For running acceptance tests

cd projects/meteor-mantra-kickstarter/
meteor npm run acceptance

For checking changes in the database

cd projects/meteor-mantra-kickstarter/
meteor mongo
# then
 db.users.findOne({ "emails.address" : "member@example.com" });
 db.getCollection("_colors").find({});

For searching for keywords in the code

cd projects/meteor-mantra-kickstarter/
grep -R --exclude=\*.{css,txt,min.js} --exclude-dir={.git,.meteor,node_modules} "key" -A 1

I tend to use the above commands daily. To get quickly ready to work, I open this README page, open the four terminal windows and cut and paste into them.