Create wiki with customizing/running/deploying instructions

[gvilarino]

This is sort of done; probably will need to perfect it more but it's a make-do right now: https://github.com/DemocracyOS/notifier/wiki

Next steps: make README.md easier and relying more on the wiki.

Related with #18

[tarasdudar]

@gvilarino,

There are still a couple of items about notifier that are not completely clear to me. It might be helpful to clarify those on wiki for other people as well.

1. From the setup it looks like there should be one notifier app for each democracyOS deployment. Am I right?
2. It's not clear how it is going to work with the separate database for users. Are you planning to add additional environmental variables to handle this?
3. Is the MONGO_CONNECTION path to the users database or the database for the laws?
4. It's not clear how ACCESS_TOKEN is generated. Is this just any random number that just needs to be the same as NOTIFICATIONS_TOKEN for democracyOS app deployment?
5. I could not figure out how to get LOGENTRIES_TOKEN generated. I've added logentries addon to the notifier app, created account with logentries on their web site but could not figure out where to generate the token. This variable = null inside test_config.js. Is this a valid value for this variable on heroku?

[gvilarino]

Answering your questions:

1. Yes, for the time being at least.
2. No need; the idea for a notifier working for a DemocracyOS instance is that all needed data for a notification (apart from user data) should be part of the payload in the call to notifier, and only a user database should be accessed by the latter (for user preferences, email addresses, etc.). In that way, notifier is agnostic to business data and thus can be used even by external services to notifiy DemocracyOS users about stuff.
3. as per 2., users. Check out the latest commits under development.
4. By hand, your own doing (I use a random GUID buy you can use anyting you like). Yes to the rest of your questions. You'd wanna check out the notifier-client for further details on usage.
5. Just a free logentries token. It's not mandatory. You can use the heroku addon, if running on heroku. Instead of null as the value, you can just use an empty string; might prevent unwanted results.

[tarasdudar]

Thanks @gvilarino,

I think I'm doing everything correctly but the notifier still refuses to send emails. Here are all my steps. Perhaps we could figure out what I'm doing wrong and update the wiki with all the right steps.

1. Started a new app on heroku called ukrainianchoice-notifier. This would be the corresponding notifier app for my ukrainianchoice democracyOS deployment on heroku.
2. Added the following add-ons: Mandrill Logentries Mongolab - this would be for "users" database for corresponding ukrainianchoice democrasyOS deployment.
3. Set the following variables: ACCESS_TOKEN = "1234" - just any random number. HOOK_TOKEN = "" - I'm not using hook. I'm not sure what it is and how to use it. HOOK_URL = "" - I'm not using hook. I'm not sure what it is and how to use it. LOCALE = "uk" - Has to match LOCALE variable in the corresponding DemocracyOS app. LOGENTRIES_TOKEN = "" MANDRILL_APIKEY = "random number" - This was automatically generated when I added Mandrill. MANDRILL_FROM_EMAIL = "my email address" MANDRILL_FROM_NAME = "my name" MANDRILL_TOKEN = "random number" - I've copied this from MANDRILL_APIKEY. MANDRILL_USERNAME = "another random number" - This was automatically generated when I added Mandrill. MONGO_CONNECTION = copy of MONGOLAB_URI. I did not see this variable in the production.config.js but it is in the wiki so I've added it. MONGO_URL = copy of MONGOLAB_URI. I did not see this variable in wiki but it is there in production.config.jso so I've added it as well. MONGOLAB_URI = "path to the users mongoDB". This was automatically generated when I added MongoLab.

I have not set the rest of the variables because I'm not using those services. Maybe that's where the problem is. I was not sure if those are optional or mandatory.

1. Add the following variables to the corresponding DemocracyOS app: NOTIFICATIONS_TOKEN = "1234" - Same as ACCESS_TOKEN above. NOTIFICATIONS_URL = "http://ukrainianchoice-notifier.herokuapp.com" - URL to the corresponding notifier app.
2. "npm install notifier-client" on the local machine. Not sure if this step was necessary. Both notifier and DemocracyOS apps are compiling fine without it.
3. Download the latest versions of DemocracyOS and notifier apps to the local machine, install them and push to the corresponding heroku apps.
4. Reload democracyOS page in the browser and see how it works. That's where I did not get any emails when I tried to sign in/register.

[tarasdudar]

I guess I also need to figure out why my text formatting is all getting changed when I submit my comments.

[tarasdudar]

Forgot to add to the following item:

1. Add the following variables to the corresponding DemocracyOS app: MONGO_USER_URL = copy of MONGO_CONNECTION, MONGO_URL or MONGOLAB_URI above.

[gvilarino]

@tarasdudar you just need to specify a valid mandill API key under MANDRILL_TOKEN for the notifier to work. I suggest you try locally first to double-check everything is cool with your settings, before pushing to heroku. You don't need to create new mandril/mongoDB add-ons on heroku if your DemocracyOS deployment already had them.

Also, regarding your comment formatting, I suggest you hit Preview before submitting a comment. For more on how formatting markdon here, read the markdown guide for github, more especially the one on doing unformatted text.

[tarasdudar]

Thanks @gvilarino,

In my latest debug experiment I've tried to copy MANDRILL settings from my DemocracyOS deployment to notifier. The Mandrill used to work fine with those USERNAME and API settings and I was getting all the emails upgrading DemocracyOS to 0.9.0. Doing that did not fix the problem but I still have Mandrill running in my DemocracyOS app with the same settings. Maybe it does not work like that. I'll remove Mandrill from notifier and see if that helps.

Regarding MongoDB. My understanding was that I need a second MongoDB for "users" anyway. So I thought the easy way to get it was to add it to the notifier app. Is there any better way of setting it up?

[gvilarino]

You don't need to remove mandrill from your DemocracyOS; you don't need to set up MANDRILL_USERNAME for notifier, just the API key under MANDRILL_TOKEN. Mails should go out with no problem.

[tarasdudar]

OK, I've removed the Mandrill from notifier, it is still running in DemocracyOS and still no email. Here is the reformatted and updated sequence of steps. I'll try to write it such that we could use it for a wiki.

This guide assumes that you have already installed DemocracyOS version 0.9.1 or higher instance on heroku. To function properly each instance of DemocracyOS needs to be connected to the notifier server and have an additional MongoDB (MongoLab) database setup to store user information. For the purpose of this guide let's assume that the name of your DemocracyOS instance is my-democracyOS-instance. It is up and running with the following URL: my-democracyOS-instance.herokuapp.com.

1. First you need to setup a supporting notifier app for your democracyOS instance on heroku. For the purpose of this guide let's assume the name for your notifier instance is my-democracyOS-instance-notifier. It will be running with the following URL: my-democracyOS-instance-notifier.herokuapp.com.
2. Add the following add-ons to your notifier: Logentries - This is the only required add-on. Mongolab - This add-on is not required for notifier itself but adding it here could be used as a second, "users", database for my-democracyOS-instance deployment. Mandrill - Only one running Mandrill add-on is required between the instance of democracyOS and it's notifier. If you have Mandrill added to your democracyOS deployment there is no need to set it up here. This guide will assume that you have Mandrill running as your democracyOS deployment add-on and you have not set it up for notifier.
3. Set the following variables: ACCESS_TOKEN = "1234" - just any random number. HOOK_TOKEN = "" - This variable is optional. Only set it up if you are using HOOK. HOOK_URL = "" - This variable is optional. Only set it up if you are using HOOK. LOCALE = This variable is the same as LOCALE variable in the corresponding DemocracyOS app. LOGENTRIES_TOKEN = "" MANDRILL_FROM_EMAIL = "email address" MANDRILL_FROM_NAME = "your name or name of your organization" MANDRILL_TOKEN = This variable is the same as MANDRILL_APIKEY variable in the corresponding DemocracyOS app. MONGOLAB_URI = "path to the users mongoDB". This will be automatically generated when you add MongoLab. MONGO_CONNECTION = copy of MONGOLAB_URI. MONGO_URL = copy of MONGOLAB_URI. The rest of the variables are optional.
4. Add the following variables to your DemocracyOS app: NOTIFICATIONS_TOKEN = "1234" - Same as ACCESS_TOKEN above. NOTIFICATIONS_URL = "http://my-democracyOS-instance-notifier.herokuapp.com" - URL to the corresponding notifier app. MONGO_USER_URL = copy of MONGOLAB_URI above.
5. "npm install notifier-client" on your local machine.
6. Download the latest versions of DemocracyOS and notifier apps to the local machine, install them and push to the corresponding heroku apps.
7. Reload democracyOS page in the browser and see how it works. That's where I did not get any emails when I tried to sign in/register.

[gvilarino]

I'm not sure why your deployment isn't working; please send an email to the dev mailing list with your notifier logs; that way I could help.

We already got a wiki in this very repo, with installation instructions and all (feel free to contribute, tho).

Some caveats to what you propose:

• ACCESS_TOKEN isn't a number, it's a string.
• You don't need to setup a MONGOLAB_URI or MONGO_CONNECTION; a MONGO_URL will do.
• As of now, you need to set up every variable described as mandatory in the wiki. If you don't have that service enabled then just put some garbage value into it.
• Point 5. is wrong, you don't need to npm install notifier-client for DemocracyOS to work; it's a node dependency described in DemocracyOS' package.json.
• Logentries isn't required, either.

[tarasdudar]

Thanks @gvilarino,

I've renamed the MONGO_CONNECTION variable to MONGO_URL on the wiki page. I'll try to update it more after we figure everything out. I've sent the email to dev with my log. It looks like notifier app is running as "development" and it should be as "production". How do I change that?

[gvilarino]

@tarasdudar exactly as with DemocracyOS: NODE_ENV