Merge pull request #113 from oslokommune/develop

[1.4.2] - 2020-04-22
oslokommune · Apr 22, 2020 · 6c6dcea · 6c6dcea
2 parents 3240373 + 398a386
commit 6c6dcea
Show file tree

Hide file tree

Showing 11 changed files with 280 additions and 101 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file. The format
 
 ## Unreleased
 
+## [1.4.2] - 2020-04-22
+
+### Added
+
+- MIT License
+
+### Changed
+
+- Improve documentation
+
+### Fixed
+
+- Fix issue regarding saving `longDescription` for key results
+
 ## [1.4.1] - 2020-04-17
 
 ### Added

diff --git a/LICENCE b/LICENCE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2020 Oslo kommune
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,107 +1,17 @@
-# okr-tracker
+# OKR Tracker
 
-## Getting started
+**This application is a reporting tool for [OKRs](https://en.wikipedia.org/wiki/OKR) (objectives and key results) using [Vue.js](https://vuejs.org/) and [Google Firebase](https://firebase.google.com/) as a backend.**
 
-### Setting up Firebase
+For help to use this application, please see the [help page](https://okr.oslo.systems/help) (in Norwegian).
 
-- Create a [Google Firebase](https://firebase.google.com) project.
-- Install the Firebase CLI and [initialize the project](https://firebase.google.com/docs/cli).
-- Create a Google service account
-  - From the Project Overview, select 'Service accounts'
-  - Click 'Generate new private key'
+## Set up a new OKR-tracker instance
 
-In order to fetch data from Google Sheets, you must set up environment variables for Firebase Functions:
+To create a new instance of the OKR-tracker, please read the [Setting up Firebase](/documentation/setting-up-firebase.md) guide.
 
-```
-firebase functions:config:set
-  sheets.email="<service account email>"
-  sheets.key="<service account private key>"
-```
+## Connecting to an existing OKR-tracker instance
 
-If you want to add automated backups and restore then you must set up environment variables for Firbase Functions:
-```
-firebase functions:config:set storage.bucket="<bucket name>"
-```
+To set up your local development environment, build and deploy for an existing Firebase backend, please see our guide for [Connecting to an existing Firebase project](/documentation/connecting-to-existing-firebase.md).
 
-**Note: The private key string needs to have actual line breaks as opposed to `\n` because of an issue with how Firebase stores environment variables. [Read more](https://github.com/firebase/firebase-tools/issues/371).**
+## Contributing
 
-### Application environment variables
-
-Grab the project parameters from Settings page on Firebase. Under 'General' and 'Your apps', select 'Config' under 'Firebase SDK snippet' and take note of the `firebaseConfig` object displayed.
-
-Create a `.env.production` file with the following secrets:
-
-| Secret                        | Description                                                     |
-| ----------------------------- | --------------------------------------------------------------- |
-| `VUE_APP_DASHBOARD_USER`      | Any (even made-up) email-address to authorize 'dashboard users' |
-| `VUE_APP_API_KEY`             | _details from firebaseConfig_                                   |
-| `VUE_APP_AUTH_DOMAIN`         | _details from firebaseConfig_                                   |
-| `VUE_APP_DATABASE_URL`        | _details from firebaseConfig_                                   |
-| `VUE_APP_PROJECT_ID`          | _details from firebaseConfig_                                   |
-| `VUE_APP_STORAGE_BUCKET`      | _details from firebaseConfig_                                   |
-| `VUE_APP_MESSAGING_SENDER_ID` | _details from firebaseConfig_                                   |
-| `VUE_APP_APP_ID`              | _details from firebaseConfig_                                   |
-| `VUE_APP_MEASUREMENT_ID`      | _details from firebaseConfig_                                   |
-
-### Setting up the Firebase Firestore
-
-The Firebase Database must be set to Firestore, and needs a few values to get up and running.
-
-Manually insert the following values to the database.
-
-- `/orgs/<new document>`
-  - `name: 'My Organisation Name`
-  - `archived: false`
-  - `missionStatement: 'My Mission Statement'`
-- `/users/<new document>` (ID must be your email address)
-  - `admin: true`
-  - `slug: 'MySlug'`
-- `/users/<new document>` (ID must be the same as the dashboard user's email address)
-  - `admin: false`
-  - `slug: 'MyDashboardUserSlug'`
-
-## Project setup
-
-```
-npm install
-```
-
-### Compiles and hot-reloads for development
-
-```
-npm run serve
-```
-
-### Compiles and minifies for production
-
-```
-npm run build
-```
-
-### Deploy
-
-Deploys project to production environment
-
-```
-npm run deploy
-```
-
-Deploys to development environment
-
-```
-npm run deploy:dev
-```
-
-### Lints and fixes files
-
-```
-npm run lint
-```
-
-```
-npm run lint:style
-```
-
-```
-npm run lint:style:fix
-```
+Please see our [Guidelines](/documentation/contributing.md).
diff --git a/documentation/automated-backups.md b/documentation/automated-backups.md
@@ -0,0 +1,35 @@
+# Automated Backup with Cloud Functions
+
+We use cloud functions to backup our database every night and only keep backup of the last 14 days. If a backup is older than 14 days it gets automatically and permanently deleted from the storage bucket.
+
+## Requirements for automated backups
+
+- Firebase Blaze plan
+- Set IAM Permission
+- Manually create a storage bucket
+- Cloud function
+
+You can follow [this tutorial](https://thecloudfunction.com/blog/firebase-cloud-functions-automated-backups/) on how to create automated backups.
+
+TLDR:
+
+- Navigate to `Google Cloud Console` and choose your project
+- Navigate to IAM & Admin - Your App Engine Service account needs the `Cloud Datastore Import Export Admin` role
+- Navigate to `Storage` - Create a storage bucket - Give it a rule to delete storage that is >14 days old
+- Run the command `firebase functions:config:set storage.bucket="<your-storage-bucket-name>"`
+
+## Automated Restore with Cloud Functions
+
+This is called automated restore but we still need to manually trigger a cloud function that does the restore from the Google Cloud Console
+
+Follow this [tutorial](https://thecloudfunction.com/blog/firebase-cloud-functions-recovery-backups/)
+
+TLDR:
+
+- From your Google Cloud Console navigate to `PubSub`
+- Create a topic and name it `restore-backup`
+- Trigger the topic by publishing a message and the restore will be triggered
+
+Gif of the process:
+![Gif of the process src: thecloudfunction-blog](recovery.gif)
+Src/Citation: [The cloud function blog](https://thecloudfunction.com/blog/firebase-cloud-functions-recovery-backups/)
diff --git a/documentation/automatically-updating-key-results.md b/documentation/automatically-updating-key-results.md
@@ -0,0 +1 @@
+# Automatically updating key results
diff --git a/documentation/connecting-to-existing-firebase.md b/documentation/connecting-to-existing-firebase.md
@@ -0,0 +1,105 @@
+# Connecting to an existing Firebase project
+
+Follow this guide to complete the set up for your local development environment and deploy your application.
+
+## Application environment variables
+
+Grab the project parameters from Settings page on Firebase. Under 'General' and 'Your apps', select 'Config' under 'Firebase SDK snippet' and take note of the `firebaseConfig` object displayed.
+
+Create an `.env.local` file (and an `.env.production` file if you intend to deploy to production) in the root directory and add the following secrets:
+
+| Secret                        | Description                                                     |
+| ----------------------------- | --------------------------------------------------------------- |
+| `VUE_APP_DASHBOARD_USER`      | Any (even made-up) email-address to authorize 'dashboard users' |
+| `VUE_APP_API_KEY`             | _details from firebaseConfig_                                   |
+| `VUE_APP_AUTH_DOMAIN`         | _details from firebaseConfig_                                   |
+| `VUE_APP_DATABASE_URL`        | _details from firebaseConfig_                                   |
+| `VUE_APP_PROJECT_ID`          | _details from firebaseConfig_                                   |
+| `VUE_APP_STORAGE_BUCKET`      | _details from firebaseConfig_                                   |
+| `VUE_APP_MESSAGING_SENDER_ID` | _details from firebaseConfig_                                   |
+| `VUE_APP_APP_ID`              | _details from firebaseConfig_                                   |
+| `VUE_APP_MEASUREMENT_ID`      | _details from firebaseConfig_                                   |
+
+## Automated Backup with Cloud Functions
+
+To set up automated backups, please read the [Setting up Automated backups](/documentation/setting-up-firebase.md) guide.
+
+If you do not want to have automated backups then you need to delete or comment out the code inside `functions/index.js`
+
+```javascript
+/**
+ * Functions for backup and restoring the Firestore database
+ */
+exports.automatedBackups = automatedBackups();
+exports.automatedRestore = automatedRestore();
+```
+
+## Setting up Firebase environment variables
+
+Firebase need certain environment variables for its Cloud Functions, namely for fetching data from Google Sheets (used for _automatically updating key results_).
+
+- Navigate to your [Firebase project](http://console.firebase.google.com/)
+- From the Project Overview, select 'Service accounts'
+- Click 'Generate new private key'
+
+Then run the following command using your new key
+
+```
+firebase functions:config:set
+  sheets.email="<service account email>"
+  sheets.key="<service account private key>"
+```
+
+**Note: The private key string needs to have actual line breaks as opposed to `\n` because of an issue with how Firebase stores environment variables. [Read more](https://github.com/firebase/firebase-tools/issues/371).**
+
+Additionally, if you want to add automated backups and restore then you must set up environment variables for Firebase Functions:
+
+```
+firebase functions:config:set storage.bucket="<bucket name>"
+```
+
+# Project setup
+
+```
+npm install
+```
+
+## Compiles and hot-reloads for development
+
+```
+npm run serve
+```
+
+## Compiles and minifies for production
+
+```
+npm run build
+```
+
+## Deploy
+
+Deploys project to production environment
+
+```
+npm run deploy
+```
+
+Deploys to development environment
+
+```
+npm run deploy:dev
+```
+
+## Lints and fixes files
+
+```
+npm run lint
+```
+
+```
+npm run lint:style
+```
+
+```
+npm run lint:style:fix
+```
diff --git a/documentation/contributing.md b/documentation/contributing.md
@@ -0,0 +1,34 @@
+# Contributing
+
+## Bug reports
+
+Keep bug reports short but descriptive. Include all details that are relevant and what the exepected outcome should be.
+
+Example:
+
+> **Short and descriptive example bug report title**
+>
+> A summary of the issue and the browser/OS environment in which it occurs. If suitable, include the steps required to reproduce the bug.
+>
+> 1. This is the first step
+> 1. This is the second step
+> 1. Further steps, etc.
+>
+> \<url> - a link to the reduced test case
+>
+> Any other information you want to share that is relevant to the issue being reported. This might include the lines of code that you have identified as causing the bug, and potential solutions (and your opinions on their merits).
+
+## Pull requests
+
+Contributions to this repository are welcomed. Please ensure your pull requests adheres to the following guidelines:
+
+- Make individual pull requests for each of your suggested changes.
+- Code (including comments) and documentation should be in English. Check spelling and grammar
+- Make sure you lint your code before commiting.
+- Add an entry in CHANGELOG.md describing your changes.
+- Merge the `develop` branch into your branch before opening a pull request.
+- Include a clear title and description
+
+## Feature requests
+
+Feature requests are welcome. But take a moment to find out whether your idea fits with the scope and aims of the project. It's up to you to make a strong case to convince the project's developers of the merits of this feature. Please provide as much detail and context as possible.
diff --git a/documentation/recovery.gif b/documentation/recovery.gif
diff --git a/documentation/setting-up-firebase.md b/documentation/setting-up-firebase.md
@@ -0,0 +1,59 @@
+# Setting up Firebase
+
+**Follow this guide to set up a new clean instance of the OKR-tracker.**
+
+- Create a [Google Firebase](https://firebase.google.com) project.
+- Install the Firebase CLI and [initialize the project](https://firebase.google.com/docs/cli).
+- Create a Google service account
+  - From the Project Overview, select 'Service accounts'
+  - Click 'Generate new private key'
+
+This key is used for fetching data from Google Sheets (for [automatically updating key results](automatically-updating-key-results.md)). In order to fetch data from Google Sheets, you must set up environment variables for Firebase Functions:
+
+```
+firebase functions:config:set
+  sheets.email="<service account email>"
+  sheets.key="<service account private key>"
+```
+
+**Note: The private key string needs to have actual line breaks as opposed to `\n` because of an issue with how Firebase stores environment variables. [Read more](https://github.com/firebase/firebase-tools/issues/371).**
+
+If you want to add automated backups and restore then you must set up environment variables for Firbase Functions:
+
+```
+firebase functions:config:set storage.bucket="<bucket name>"
+```
+
+**Note: The private key string needs to have actual line breaks as opposed to `\n` because of an issue with how Firebase stores environment variables. [Read more](https://github.com/firebase/firebase-tools/issues/371).**
+
+## Application environment variables
+
+Grab the project parameters from Settings page on Firebase. Under 'General' and 'Your apps', select 'Config' under 'Firebase SDK snippet' and take note of the `firebaseConfig` object displayed. Some of these values need to be included in your env-file.
+
+## Setting up the Firebase Firestore
+
+The Firebase Database must be set to Firestore, and needs a few values to get up and running.
+
+Manually insert the following values to the database.
+
+- `/orgs/<new document>`
+  - `name: 'My Organisation Name`
+  - `archived: false`
+  - `missionStatement: 'My Mission Statement'`
+- `/users/<new document>` (ID must be your email address)
+  - `admin: true`
+  - `slug: 'MySlug'`
+- `/users/<new document>` (ID must be the same as the dashboard user's email address)
+  - `admin: false`
+  - `slug: 'MyDashboardUserSlug'`
+
+## Enable Google Auth in Firebase
+
+We use Google Auth to authenticate users and this needs to be enabled in the Firebase Console.
+
+- Navigate to your project in Firebase console
+- Press the `Authentication`-button in the side menu
+- `Sign-in Method`-tab
+- Enable Google Auth
+
+Next, proceed to [Connecting to an existing firebase project](connecting-to-existing-firebase.md) for our guide to setting up your environments.