From 292ba6e0c384432e206352e24a4d31c9077674d7 Mon Sep 17 00:00:00 2001 From: Danny August Ramaputra Date: Sat, 6 Feb 2021 13:18:40 +1000 Subject: [PATCH] docs: updated README --- README.md | 63 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 36 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index f6a653e..22b8ff8 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,12 @@ [![Docker Pulls](https://img.shields.io/docker/pulls/daystram/ratify)](https://hub.docker.com/r/daystram/ratify) [![MIT License](https://img.shields.io/github/license/daystram/ratify)](https://github.com/daystram/ratify/blob/master/LICENSE) -Ratify is a Central Authentication Service (CAS) implementing OAuth 2.0 and OpenID Connect (OID) protocols, as defined in [RFC 6749](https://tools.ietf.org/html/rfc6749). +__Ratify__ is a Central Authentication Service (CAS) implementing OAuth 2.0 and OpenID Connect (OID) protocols, as defined in [RFC 6749](https://tools.ietf.org/html/rfc6749). ## Features - Implements various authorization flows - Implements OpenID Connect protocol layer -- Register new applications to use Ratify +- Register new applications to use __Ratify__ - Manage registered users (with email verification) - Multi-factor authentication using Time-based One-Time Password (TOTP) - Universal login @@ -22,44 +22,50 @@ Ratify is a Central Authentication Service (CAS) implementing OAuth 2.0 and Open - _WIP: Client Credentials_ ## Client Libraries -Use the following libraries to easily integrate your application with Ratify's authentication service. -- JavaScript: [ratify-client-js](https://github.com/daystram/ratify-client-js) +Use the following libraries to easily integrate your application with __Ratify__'s authentication service. +- JavaScript/TypeScript: [ratify-client-js](https://github.com/daystram/ratify-client-js) + +## Services +The application comes in two parts: + +|Name|Code Name|Stack| +|----|:-------:|-----| +|Back-end|`ratify-be`|[Go](https://golang.org/), [Gin](https://github.com/gin-gonic/gin) + [Gorm](https://github.com/go-gorm/gorm), [PostgreSQL](https://www.postgresql.org/), [Redis](https://redis.io/)| +|Front-end|`ratify-fe`|[TypeScript](https://www.typescriptlang.org/), [Vue.js](https://vuejs.org/)| ## Develop -Ratify is split into two sub-applications, `ratify-be` (backend) and `ratify-fe` (frontend). `ratify-fe` itself acts as stand-alone application to `ratify-be` and thus utilizes an access token it self-issued via the _Authorization Code with PKCE_ flow to authenticate users. +`ratify-fe` itself acts as stand-alone application to `ratify-be`, thus it utilizes an access token it self-issued via the _Authorization Code with PKCE_ flow to authenticate users. ### ratify-be -`ratify-be` is developed for Go with [Gin](https://github.com/gin-gonic/gin) framework. The project uses [Go Modules](https://blog.golang.org/using-go-modules) module/dependency manager, hence at least Go 1.11 is required. To ease with development, [comstrek/air](https://github.com/cosmtrek/air) is used to live-reload the application. Create and populate the `config.yaml` file based on the provided template. +`ratify-be` uses [Go Modules](https://blog.golang.org/using-go-modules) module/dependency manager, hence at least Go 1.11 is required. To ease development, [comstrek/air](https://github.com/cosmtrek/air) is used to live-reload the application. Install the tool as documented. To begin developing, simply enter the sub-directory and run the development server: -```console +```shell $ cd ratify-be $ go mod tidy $ air ``` ### ratify-fe -`ratify-fe` is written in TypeScript and uses [Vue](https://github.com/vuejs/vue) framework. The `.env.development` file needs to be populated with the Client ID that `ratify-be` provides. +Populate `.env.development` with the required credentials. Use the Client ID that `ratify-be` provides. To begin developing, simply enter the sub-directory and run the development server: -```console +```shell $ cd ratify-fe $ yarn $ yarn serve ``` ## Deploy -Both `ratify-be` and `ratify-fe` are containerized and pushed to [Docker Hub](https://hub.docker.com/r/daystram/ratify). They are tagged based on their application name and version, e.g. `daystram/ratify:be` or `daystram/ratify:be-v0.9.1`. - -For `ratify-be`, a configuration file has to be bound to the container. Use the provided template [example.config.yaml](./ratify-be/config/example.config.yaml). +Both `ratify-be` and `ratify-fe` are containerized and pushed to [Docker Hub](https://hub.docker.com/r/daystram/ratify). They are tagged based on their application name and version, e.g. `daystram/ratify:be` or `daystram/ratify:be-v1.1.0`. To run `ratify-be`, run the following: -```console +```shell $ docker run --name ratify-be --env-file ./.env -p 8080:8080 -d daystram/ratify:be ``` And `ratify-fe` as follows: -```console +```shell $ docker run --name ratify-fe -p 80:80 -d daystram/ratify:fe ``` @@ -71,39 +77,42 @@ The following are required for `ratify-be` to function properly: Their credentials must be provided in the configuration file. -UUID support is also required in PostgreSQL. For modern PostgreSQL versions (9.1 and newer), the contrib module `uuid-ossp` can be enabled as follows: -```sql -CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; -``` - ### Docker Compose For ease of deployment, the following `docker-compose.yml` file can be used to orchestrate the stack deployment: ```yaml version: "3" services: - ratify-fe: - image: daystram/ratify:fe - ports: - - 80:80 - restart: unless-stopped ratify-be: image: daystram/ratify:be ports: - - 8080:8080 + - "8080:8080" env_file: - /path_to_env_file/.env restart: unless-stopped + ratify-fe: + image: daystram/ratify:fe + ports: + - "80:80" + restart: unless-stopped postgres: image: postgres:13.1-alpine volumes: - - /path_to_pg_data:/var/lib/postgresql/data + - /path_to_postgres_data:/var/lib/postgresql/data restart: unless-stopped redis: image: redis:6.0-alpine + expose: + - 6379 volumes: - - /path_to_rd_data:/data + - /path_to_redis_data:/data restart: unless-stopped ``` +### PostgreSQL UUID Extension +UUID support is also required in PostgreSQL. For modern PostgreSQL versions (9.1 and newer), the contrib module `uuid-ossp` can be enabled as follows: +```sql +CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; +``` + ## License This project is licensed under the [MIT License](./LICENSE).