Improving documentation (#317)

README.md

@@ -5,8 +5,6 @@
 
 This is a Retrospective Idea board, powering [retrospected.com](http://www.retrospected.com).
 
-Documentation [available here](https://docs.retrospected.com).
-
  
 
 <p align="center">
@@ -55,9 +53,10 @@ It features the following technologies:
 - [Yarn](https://yarnpkg.com/en/), replacing NPM
 - [Docker](https://docker.com), for easy deployment
 - [Kubernetes](https://kubernetes.io/), to scale Retrospected for its 10M+ users (not)
-- [Travis](http://travis-ci.org/), for Continuous Integration and Deployment (CI/CD)
+- [GitHub Actions](https://github.com/features/actions), for Continuous Integration and Deployment (CI/CD)
 - [Multi-Architecture](https://github.com/docker/buildx/), for automatic compatibility with ARM-based servers
 - [Stripe](https://stripe.com/), for our payment solution
+- [Docusaurus](http://docusaurus.io/), for our documentation
 
 Previous versions, up to v1.0.1 featured the following libraries:
 
@@ -67,91 +66,29 @@ Previous versions, up to v1.0.1 featured the following libraries:
 - ~~[reselect](https://github.com/reactjs/reselect)~~
 - ~~[ESLint](http://eslint.org/) for JS and JSX~~
 
-## How to try it out 🚀
-
-You must have `docker` and `docker-compose` installed on your system.
-
-- Clone this repository
-- Then run `docker-compose up -d`.
-- Open your browser at [http://localhost:1800](http://localhost:1800)
-- _(then please wait a few minutes the first time for the database to initialise)_
-
-## How to run for development 📝
-
-### Prerequisites 💿
-
-- You must have [docker](https://www.docker.com) and [docker-compose](https://docs.docker.com/compose/) installed on your system.
-- You must also have [Node.js](https://nodejs.org/en/), version 15 (other recent versions will probably work too).
-- `Yarn`: Please install [Yarn](https://yarnpkg.com/en/), as this mono-repo uses **Yarn Workspaces** which won't work with NPM.
-
-### Run 🚀
-
-- Clone this repository
-- Run Postgres, Redis, PGAdmin locally:
-  - `cd ./retro-board` (that is the `retro-board` directory **within** the repository)
-  - `docker-compose up -d`
-  - `cd ..`
-- `yarn` to install the dependencies (_not_ `npm i`!)
-- `yarn build-common` to build the shared module
-- `yarn migrate` to run the database migrations
-- `yarn backend` to start the backend
-- Open another terminal
-- `yarn frontend` on the second terminal to run the frontend
-- Open your browser on [http://localhost:3000](http://localhost:3000)
-
-## Self-Host Retrospected 🐳
-
-### Prerequisites 💿
-
-- You must obtain a self-hosting licence. You can obtain one [here](https://www.retrospected.com/subscribe?product=self-hosted).
-- When buying a licence, a ready-to-run `docker-compose.yml` file will be sent to you by email with installation instructions.
-- You must have [docker](https://www.docker.com) and [docker-compose](https://docs.docker.com/compose/) installed on your system.
-
-### Try it out 🚀
-
-- Edit `docker-compose.yml` to change credentials and secrets
-- _Optional: for ARM-based systems, use biarms/pgadmin4 instead_
-- Run `docker-compose up -d`
-- Voilà!
-
-This will run a production-ready version of Retrospected automatically, using Postgres and Redis.
-You don't need to have anything installed other than Docker. This will install and run:
-
-- Postgres
-- pgAdmin4 (Web UI for postgres)
-- Redis
-- The Retrospected Node.js Backend
-- The Retrospected React Frontend, served by `nginx`.
-
-## How to run for Production using Kubernetes ☸
-
-Please read the [readme](/k8s/readme.md) file in the `k8s` folder. Please note: Kubernetes
-example configs are not maintained, and are only provided as an example.
+## Documentation 📖
 
-## Backups 💾
+You can browse the documentation [here](https://docs.retrospected.com).
 
-When using the Docker deployment, your database runs from a container. But if you still need to make some backup of your data, you can do the following:
+## Using Retrospected 🚀
 
-- Get the docker database container ID by doing: `docker ps`
-- Run `` docker exec -t <docker_container_id> pg_dumpall -c -U postgres > dump_`date +%d-%m-%Y"_"%H_%M\_%S`.sql ``
-- To restore your databases: `cat dump_1234.sql | docker exec -i <docker_container_id> psql -U postgres`
+You have two ways of running Retrospected:
 
-## How to run the tests ✅
+- Using the public version, at [www.retrospected.com](https://www.retrospected.com)
+- Host Retrospected [on your premises](https://docs.retrospected.com/docs/self-hosting/quick-start)
 
-- Clone this repository
-- `yarn` to install the dependencies (_not_ `npm i`!)
-- `yarn test` to run the tests in watch mode
-- **or** `yarn ci-test` to run the tests once
+## Want to host Retrospected on your premises? 🖥
 
-## Road-Map and ideas 🚗 💡
+You can start an instance of Retrospected in 5 minutes by following the [quick-start guide](https://docs.retrospected.com/docs/self-hosting/quick-start).
 
-- Highlight posts where the user voted
+This will run a demo version, which you can turn into a fully licenced version by purchasing a [Self Hosted licence](https://www.retrospected.com/subscribe?product=self-hosted).
 
 ## Versions History
 
 ### Version 4.9.0
 
 - Brand new [documentation website](https://docs.retrospected.com).
+- Migrate all docker images from `antoinejaussoin/retro-board-*` to `retrospected/*`.
 - 🐛 The Unlimited subscription domain check was not accepting valid domains such as `.ventures` or `.agency`.
 
 ### Version 4.8.0

backend/src/admin/router.ts

@@ -22,6 +22,11 @@ router.get('/self-hosting', async (_, res) => {
     adminEmail: config.SELF_HOSTED_ADMIN,
     selfHosted: config.SELF_HOSTED,
     licenced: !!licence,
+    sendGridAvailable:
+      !!config.SENDGRID_API_KEY &&
+      !!config.SENDGRID_RESET_PASSWORD_TID &&
+      !!config.SENDGRID_VERIFICATION_EMAIL_TID &&
+      !!config.SENDGRID_SENDER,
     oAuth: {
       google: !!config.GOOGLE_KEY && !!config.GOOGLE_SECRET,
       github: !!config.GITHUB_KEY && !!config.GITHUB_SECRET,

backend/src/auth/register/register-user.ts

@@ -24,7 +24,10 @@ export default async function registerPasswordUser(
     type: 'password',
     username: details.username,
     password: hashedPassword,
-    emailVerification: config.SELF_HOSTED ? undefined : v4(),
+    emailVerification:
+      config.SENDGRID_API_KEY && config.SENDGRID_VERIFICATION_EMAIL_TID
+        ? v4()
+        : undefined,
     language: details.language,
   });
 

common/src/payloads.ts

@@ -52,6 +52,7 @@ export interface SelfHostedCheckPayload {
 
 export interface SelfHostingPayload {
   selfHosted: boolean;
+  sendGridAvailable: boolean;
   adminEmail: string;
   licenced: boolean;
   oAuth: OAuthAvailabilities;

docs/Dockerfile

@@ -1,8 +1,8 @@
 # This must be run with the Docker context set to the root folder of the repository
 # (the one with the yarn.lock file)
 
-# FROM --platform=$BUILDPLATFORM node:16-alpine as Node
-FROM node:16-alpine as Node
+FROM --platform=$BUILDPLATFORM node:16-alpine as Node
+## FROM node:16-alpine as Node
 
 ENV NODE_ENV=production
 

docs/docs/self-hosting/Troubleshooting.md

@@ -1,4 +1,4 @@
-# Troubleshooting
+# 🐛 Troubleshooting
 
 ## Logs
 

docs/docs/self-hosting/admin.md

@@ -2,9 +2,9 @@
 sidebar_position: 4
 ---
 
-# Admin Panel
+# 🙋‍♂️ Managing Users
 
-When self-hosting, you will not have access to the ability to confirm and reset passwords by email.
+When self-hosting, you will not have access to the ability to confirm and reset passwords by email (unless you setup [Sendgrid](sendgrid)).
 
 If a user forgets their password, you can access a specific admin tool by accessing `/admin` on your Retrospected frontend, and reset your user's password.
 

docs/docs/self-hosting/backup.md

@@ -2,7 +2,7 @@
 sidebar_position: 3
 ---
 
-# Backup your data
+# 💾 Backup your data
 
 Making sure your data is safe is **important**.
 

docs/docs/self-hosting/oauth.mdx

@@ -0,0 +1,72 @@
+# 🔐 OAuth
+
+On the public [Retrospected](https://www.retrospected.com) website, you will have noticed that people can register and login in one click using an OAuth provider:
+
+<img src="/img/self-hosting/oa-1.png" width="300" />
+
+You can provide the same seamless experience on your Self-Hosted instance by following the guide below.
+
+:::tip Local Network
+The following works even if you are self-hosting on a local or corporate network. Your instance doesn't have to
+be reachable over the internet.
+:::
+
+:::info What about other providers?
+We will help you set up OAuth for **Google** and **Github**, but the process is similar for the other 
+providers we support: **Okta**, **Microsoft**, **Twitter** and **Slack**.
+:::
+
+
+## Github
+
+If you are working in tech, chances are your users will have a GitHub account.
+
+To setup OAuth for GitHub, follow the guide:
+
+### Create the keys
+
+- Go to your [GitHub profile](https://github.com/settings/profile) (you need to be logged in)
+- On the left-hand-side, find the `Developer settings` menu:<br />
+<img src="/img/self-hosting/oa-github-1.png" width="200" />
+- Select `OAuth Apps`<br />
+<img src="/img/self-hosting/oa-github-2.png" width="200" />
+- Fill the following information:
+  - **Application name**: A name that you choose
+  - **Home page URL**: the publicly reachable URL for your instance of Retrospected
+  - **Description**: Some description of your choosing
+  - **Authorization callback URL**: This is the most important: it is composed of the domain followed by `/api/auth/github/callback`.<br />
+<img src="/img/self-hosting/oa-github-3.png" width="400" />
+- Click `Register Application`
+- Your app is now created, and you need to now click on `Generate a new client secret`. The page should now look like this:<br />
+<img src="/img/self-hosting/oa-github-4.png" width="400" />
+
+### Install the keys
+- Copy both the `Client ID` and the `Client Secret` from the form above
+- In your `docker-compose.yml` file, set them up respectively as `GITHUB_KEY` and `GITHUB_SECRET` in the backend section. [Look here](optionals) if you are not sure where these should be.
+- Restart your containers (`docker-compose up -d`) and you should now be able to use GitHub to login 🎉.
+
+
+## Google
+
+### Create the keys
+
+- Connect to the [Google Cloud Platform](https://console.cloud.google.com/home/dashboard) dashboard
+- Create a new Project (if you don't have one already)<br />
+<img src="/img/self-hosting/oa-gcp-1.png" width="600" /><br />
+<img src="/img/self-hosting/oa-gcp-2.png" width="300" />
+- Then select this new project (in the page header), and go to `APIs and services` and `Credentials`<br />
+<img src="/img/self-hosting/oa-gcp-3.png" width="400" />
+- Fill the `OAuth Consent Screen` information<br />
+<img src="/img/self-hosting/oa-gcp-4.png" width="400" />
+- Then go back to `Credentials`, click on `Create Credentials` then `OAuth client ID`.<br />
+<img src="/img/self-hosting/oa-gcp-5.png" width="400" />
+- Fill the relevant information, the important bit here will be the `Authorised Redirect URL`. It is composed of the domain followed by `/api/auth/google/callback`.<br />
+<img src="/img/self-hosting/oa-gcp-6.png" width="400" />
+- You will then finally given two keys:<br />
+<img src="/img/self-hosting/oa-gcp-7.png" width="400" />
+
+### Install the keys
+
+- Copy both the `Your Client ID` and the `Your Client Secret` from the form above
+- In your `docker-compose.yml` file, set them up respectively as `GOOGLE_KEY` and `GOOGLE_SECRET` in the backend section. [Look here](optionals) if you are not sure where these should be.
+- Restart your containers (`docker-compose up -d`) and you should now be able to use Google to login 🎉.