Zazu - Vendor Co-op Reporting [in beta]

An unopinionated, scalable reporting application built on Google Cloud Platform and Data Studio for vendor co-op reporting.

What is Vendor Co-op?

Vendor co-op is a form of joint marketing where organizations pool together resources and expertise to acheive a joint goal. In the classic case, consider a retailer that sells vacuum cleaners from a specific manufacturer. The retailer and the manufacturer might pool together marketing budget, data and creative content to launch a joint marketing campaign to attract consumers to a retail location to purchase vacuums from the manufacturer - a win-win for retailer and manufacturer. In this context, the manufacturer, generally referred to as the vendor, provides resources to the retailer, where the retailer plans and executes the joint marketing campaign.

What is Zazu?

Zazu is an open-source application that can be used as scalable infrastructure to help facilitate reporting between organizations. In the case of the retailer and manufacturer, Zazu is an application that the retailer can deploy such that the retailer can share 1st party data directly to the manufacturer in a controlled, secure and private manner. As an example, the retailer may choose to report impressions, store visits or revenue as a metric to the manufacturer to show the business results driven by the joint marketing campaign.

Dependencies

Zazu integrates several popular production reliable web, data and analytics technologies:

• Google Identity Platform - to authorize and manage accesses
• Data Studio - to design and disseminate web-based reports and dashboards
• BigQuery - data warehouse for staging and querying data for reports
• Angular - application client for web
• Node.js- application server
• MongoDB - document storage for application metadata

Docs

• Website and Documentation
• Business Overview
• Technical Overview
• Repository

Prerequisites

1. Billing method available or already set up on the Google Cloud Platform (GCP).
2. Docker installed: Instructions here.
3. Google Cloud SDK installed: Instructions here.

Installation steps

1. Create a new project in GCP.

2. APIs & Services > Dashboard > If not already enabled, enable the Big Query, Google+ API and Google Container Registry.

3. Run git clone https://github.com/google/zazu.git in a desired directory.

4. cd <directory_of_step_3>/zazu

5. mkdir <directory_of_step_3>/zazu/encryption. Then add your key and certificate, <key_name>.key and <cert_name>.crt for https under this directory. For your key and certificate, talk to your admin.
   Note: If you do not have a key and certificate yet, you can generate a self signed key/certificate for testing purposes, by running the following commands.
   cd <directory_of_step_3>/zazu/encryption
openssl genrsa -des3 -out <key_name>.key 1024
openssl req -new -key <key_name>.key -out <cert_name>.csr
openssl x509 -req -days 365 -in <cert_name>.csr -signkey <key_name>.key -out <cert_name>.crt
   

6. cd <directory_of_step_3>/zazu; docker build -t zazuimg .

7. Push your Docker image to the Google Container Registry.

   • gcloud auth configure-docker
   • docker tag zazuimg gcr.io/<project_id>/zazuimg
   • docker push gcr.io/<project_id>/zazuimg

8. Provision a service account on GCP. No checkbox is needed to be selected.

   • IAM > Service accounts > Create service accounts
     
     • Name: service-zazu-app
       
     • Role: Project -> Owner
       
     • Role: Storage -> Storage Object Viewer
     • Click Done

9. Create a set of OAuth credentials and keep note of the client ID/secret.

   • APIs & Services > Credentials > Create credentials > OAuth client ID.
   • Web application -> Type any client name of preference.
   • Authentication Javascript origin: https://<your_domain_to_be_assigned_to_app>
   • Authentication redirect URI: https://<your_domain_to_be_assigned_to_app>/auth/google/callback

10. Set up firewall rules.

    • VPC Network > Firewall rules > Create firewall rules
      • Name: zazu-db
      • Description: Allow connections to zazu database from zazu app.
      • Target tags: zazu-db
      • Source tags: zazu-app
      • Second source filter > IP ranges: 0.0.0.0/0
      • Protocols and ports: tcp:27017 (which is the default port of mongodb. Change it to a different one, if mongodb is setup to run on a different port.)
    • VPC Network > Firewall rules > Create firewall rules
      • Name: zazu-app
      • Description: Allow connections to zazu app from the web.
      • Target tags: zazu-app, https-server
      • Source IP ranges: 0.0.0.0/0
      • Protocols and ports: tcp:443

11. Create a new VM instance for the mongodb.

    • Deploy a container image.
      • Type mongo as the docker image.
      • Advanced Container Options > Environment variable
        MONGO_INITDB_ROOT_USERNAME <select_root_username>
        MONGO_INITDB_ROOT_PASSWORD <select_root_password>
        MONGO_INITDB_DATABASE zazu
        The above parameters you may choose as desired.
    • Boot Disk > SSD Persistent Disk
    • Service account: Select the one created on step 8.
    • Networking > Network tags > zazu-db.

12. Create a global username and password for the mongoDB user used by the application.

• Compute engine > VM instances > zazu-db > SSH
  • docker exec -it zazu-db sh
  • mongo admin -u <select_root_username> -p <select_root_password> (from step 11a.)
  • use zazu
  • db.createUser({ user: "<select_app_username>", pwd: "<select_app_password>", roles: [ "readWrite" ] })

13. Create a new VM instance for the App

    • Deploy a container image

      • Use path from gcr.io where you published the Docker image on step 7.
      • Advanced Container Options > Environment variables bq_instance <GCP_project_name>
        bq_dataset Zazu_Config_Data
        bq_client_dataset Report_Data
        bq_views_dataset Accessible_Views
        google_client_id <OAuth_client_ID_step_10>
        google_client_secret <OAuth_client_secret_step_10>
        session_secret <choose_any_string_for_sess_encr>
        PORT 443
        https_key_filename <your_https_key_filename_used_in_step_5>
        https_cert_filename <your_https_cert_filename_used_in_step_5>
        https_passphrase <your_https_passphrase_used_in_step_5>
        mongo_connection_string mongodb://<select_app_username>:<select_app_password>@<DNS_NAME>/zazu (from step 12.)
        

      Note: MONGO_INITDB values come from step 12. The DNS_NAME looks like: zazu-db.c.PROJECTNAME.internal . Template: INSTANCENAME.c.PROJECTNAME.internal .
      

      • Boot Disk > SSD Persistent Disk
      • Allow HTTPS.
      • Networking > create a static IP address as the external IP.
      • Networking > Public DNS PTR record: assign the domain you will be assigning to the app without the https:// part.
      • Service account: Select the one created on step 8.
      • Networking > Network tags > zazu-app

14. One time only: Create the first admin user of the application in mongodb.

    • Compute engine > VM instances > zazu-db > SSH
      • docker exec -it zazu-db sh
      • mongo zazu -u <select_app_username> -p <select_app_password> (from step 13)
      • db.users.insert({ name: "<your_admin_name>", googleID: "<your_admin_google_id>", role: "admin" })
      • db.users.find()
      • Copy the _id value of the newly created item, for use in step 15.

15. One time only: Create the same first admin user of the application as in step 14, in Big Query.

    • https://bigquery.cloud.google.com > Select the project > Compose query >
      INSERT INTO <project_name>.Zazu_Config_Data.users (user_id, googleID, role) VALUES ('<_id_value_from_step_15>', '<your_admin_google_id>', 'admin')

Support

This project is in alpha - for questions please contact the project owners amete@google.com & jmattarian@google.com. Note - while in alpha, select organizations will be approved to receive technical, analytical and engineering support from Google. If interested in the alpha, please send requests to amete@google.com. For bugs, comments or enhancements, please submit directly at our public repository. Note we are also interested in collaborators interested in contributing to the application - if you'd like to make a contribution to the code base, please make a pull request.