go/golang-saas-starter-kit
1
0
Fork 0
mirror of https://github.com/raseels-repos/golang-saas-starter-kit.git synced 2025-08-08 22:36:41 +02:00
Code Issues Releases Activity

Enhance the readme

Browse Source
This commit is contained in:
huyng
2019-08-09 22:25:16 +07:00
committed by huyntsgs
parent 169ecf0b1c
commit 367c9f05a0
1 changed files with 37 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
README.md
View File

@ -6,7 +6,7 @@ twins@geeksaccelerator.com
## Description ## Description
The SaaS Starter Kit is a set of libraries for building scalable software-as-a-service (SaaS) applications while The SaaS Starter Kit is a set of libraries for building scalable software-as-a-service (SaaS) applications that help
preventing both misuse and fraud. The goal of this project is to provide a proven starting point for new preventing both misuse and fraud. The goal of this project is to provide a proven starting point for new
projects that reduces the repetitive tasks in getting a new project launched to production that can easily be scaled projects that reduces the repetitive tasks in getting a new project launched to production that can easily be scaled
and ready to onboard enterprise clients. It uses minimal dependencies, implements idiomatic code and follows Golang and ready to onboard enterprise clients. It uses minimal dependencies, implements idiomatic code and follows Golang
@ -18,8 +18,8 @@ This project should not be considered a web framework. It is a starter toolkit t
to handle some of the common challenges for developing SaaS using Golang. Coding is a discovery process and with that, to handle some of the common challenges for developing SaaS using Golang. Coding is a discovery process and with that,
it leaves you in control of your project’s architecture and development. it leaves you in control of your project’s architecture and development.
SaaS product offerings typically provide two main components: an API and a web application. Both facilitate delivering a SaaS product offerings typically provide two main components: a REST API and a web application. Both facilitate delivering a
valuable software based product to clients ideally from a single code base on a recurring basis delivered over the valuable software, based product to clients ideally from a single code base on a recurring basis delivered over the
internet. internet.
To see screen captures of the web app and auto-generated API documentation, check out this Google Slides deck: To see screen captures of the web app and auto-generated API documentation, check out this Google Slides deck:
@ -30,8 +30,8 @@ https://docs.google.com/presentation/d/1WGYqMZ-YUOaNxlZBfU4srpN8i86MU0ppWWSBb3pk
[![Google Slides of Screen Captures for SaaS Starter Kit web app](resources/images/saas-webapp-screencapture-01.jpg)](https://docs.google.com/presentation/d/1WGYqMZ-YUOaNxlZBfU4srpN8i86MU0ppWWSBb3pkejM/edit#slide=id.p) [![Google Slides of Screen Captures for SaaS Starter Kit web app](resources/images/saas-webapp-screencapture-01.jpg)](https://docs.google.com/presentation/d/1WGYqMZ-YUOaNxlZBfU4srpN8i86MU0ppWWSBb3pkejM/edit#slide=id.p)
There are five areas of expertise that an engineer or her engineering team must do for a project to grow and scale. There are five areas of expertise that an engineer or engineering team must do for a project to grow and scale.
Based on our experience, a few core decisions were made for each of these areas that help you focus initially on writing Based on our experience, a few core decisions were made for each of these areas that help you focus initially on working
the business logic. the business logic.
1. Micro level - Since SaaS requires transactions, project implements Postgres. Implementation facilitates the data 1. Micro level - Since SaaS requires transactions, project implements Postgres. Implementation facilitates the data
semantics that define the data being captured and their relationships. semantics that define the data being captured and their relationships.
@ -45,12 +45,12 @@ responsive service for clients.
The example project is a complete starter kit for building SasS with GoLang. It provides two example services: The example project is a complete starter kit for building SasS with GoLang. It provides two example services:
* Web App - Responsive web application to provide service to clients. Includes user signup and user authentication for * Web App - Responsive web application to provide service to clients. Includes user signup and user authentication for
direct client interaction via their web connected devices. direct client interaction via their web browsers.
* Web API - REST API with JWT authentication that renders results as JSON. This allows clients and other third-pary companies to develop deep * Web API - REST API with JWT authentication that renders results as JSON. This allows clients and other third-pary companies to develop deep
integrations with the project. integrations with the project.
And these tools: The example project also provides these tools:
* Schema - Initializing of Postgres database and handles schema migration. * Schema - Creating, initializing tables of Postgres database and handles schema migration.
* Dev Ops - Deploying project to AWS with GitLab CI/CD. * Dev Ops - Deploying project to AWS with GitLab CI/CD.
It contains the following features: It contains the following features:
@ -58,17 +58,17 @@ It contains the following features:
* Auto-documented REST API. * Auto-documented REST API.
* Middleware integration. * Middleware integration.
* Database support using Postgres. * Database support using Postgres.
* Key value store using Redis * Cache and key value store using Redis
* CRUD based pattern. * CRUD based pattern.
* Role-based access control (RBAC). * Role-based access control (RBAC).
* Account signup and user management. * Account signup and user management.
* Distributed logging and tracing. * Distributed logging and tracing.
* Integration with Datadog for enterprise-level observability. * Integration with Datadog for enterprise-level observability.
* Testing patterns. * Testing patterns.
* Use of Docker, Docker Compose, and Makefiles. * Build, deploy and run application using Docker, Docker Compose, and Makefiles.
* Vendoring dependencies with Modules, requires Go 1.12 or higher. * Vendoring dependencies with Modules, requires Go 1.12 or higher.
* Continuous deployment pipeline. * Continuous deployment pipeline.
* Serverless deployments. * Serverless deployments with AWS ECS Fargate.
* CLI with boilerplate templates to reduce repetitive copy/pasting. * CLI with boilerplate templates to reduce repetitive copy/pasting.
* Integration with GitLab for enterprise-level CI/CD. * Integration with GitLab for enterprise-level CI/CD.
@ -81,9 +81,8 @@ Accordingly, the project architecture is illustrated with the following diagram.
With SaaS, a client subscribes to an online service you provide them. The example project provides functionality for With SaaS, a client subscribes to an online service you provide them. The example project provides functionality for
clients to subscribe and then once subscribed they can interact with your software service. clients to subscribe and then once subscribed they can interact with your software service.
The initial contributors to this project are building this saas-starter-kit based on their years of experience building The initial contributors to this project are building this saas-starter-kit based on their years of experience building enterprise B2B SaaS. Particularily, this saas-starter-kit is based on their most recent experience building the
building enterprise B2B SaaS. Particularily, this saas-starter-kit is based on their most recent experience building the B2B SaaS for [standard operating procedure software](https://keeni.space) (written entirely in Golang). Please refer to the Keeni.Space website,
B2B SaaS for [standard operating procedure software](https://keeni.space) (100% Golang). Reference the Keeni.Space website,
its [SOP software pricing](https://keeni.space/pricing) and its signup process. The SaaS web app is then available at its [SOP software pricing](https://keeni.space/pricing) and its signup process. The SaaS web app is then available at
[app.keeni.space](https://app.keeni.space). They plan on leveraging this experience and build it into a simplified set [app.keeni.space](https://app.keeni.space). They plan on leveraging this experience and build it into a simplified set
example services for both a web API and a web app for SaaS businesses. example services for both a web API and a web app for SaaS businesses.
@ -147,8 +146,8 @@ need to be using Go >= 1.11.
You should now be able to clone the project. You should now be able to clone the project.
```bash ```bash
git clone git@gitlab.com:geeks-accelerator/oss/saas-starter-kit.git $ git clone git@gitlab.com:geeks-accelerator/oss/saas-starter-kit.git
cd saas-starter-kit/ $ cd saas-starter-kit/
``` ```
If you have Go Modules enabled, you should be able compile the project locally. If you have Go Modulels disabled, see If you have Go Modules enabled, you should be able compile the project locally. If you have Go Modulels disabled, see
@ -162,13 +161,13 @@ This project is using Go Module support for vendoring dependencies.
We are using the `tidy` command to maintain the dependencies and make sure the project can create reproducible builds. We are using the `tidy` command to maintain the dependencies and make sure the project can create reproducible builds.
```bash ```bash
GO111MODULE=on go mod tidy $ GO111MODULE=on go mod tidy
``` ```
It is recommended to use at least Go 1.12 and enable go modules. It is recommended to use at least Go 1.12 and enable go modules.
```bash ```bash
echo "export GO111MODULE=on" >> ~/.bash_profile $ echo "export GO111MODULE=on" >> ~/.bash_profile
``` ```
@ -184,8 +183,8 @@ https://docs.docker.com/install/
There is a `docker-compose` file that knows how to build and run all the services. Each service has its own a There is a `docker-compose` file that knows how to build and run all the services. Each service has its own a
`dockerfile`. `dockerfile`.
When you run `docker-compose up` it will run all the services including the main.go file for each Go service. The Before using `docker-compose`, you need to copy `sample.env_docker_compose` to `.env_docker_compose` that docker will use. When you run `docker-compose up` it will run all the services including the main.go file for each Go service. The
services the project will run are: following services will run:
- web-api - web-api
- web-app - web-app
- postgres - postgres
@ -198,7 +197,8 @@ Use the `docker-compose.yaml` to run all of the services, including the 3rd part
command, Docker will download the required images for the 3rd party services. command, Docker will download the required images for the 3rd party services.
```bash ```bash
$ docker-compose up --build $ cp sample.env_docker_compose .env_docker_compose
$ docker-compose up
``` ```
Default configuration is set which should be valid for most systems. Default configuration is set which should be valid for most systems.
@ -208,7 +208,7 @@ Use the `docker-compose.yaml` file to configure the services differently using e
#### How we run the project #### How we run the project
We like to run the project where the services run in the background of our CLI. This can be done by using the -d with We like to run the project where the services run in the background of our CLI. This can be done by using the -d with
the `docker-compose up` command: the `docker-compose up --build` command:
```bash ```bash
$ docker-compose up --build -d $ docker-compose up --build -d
``` ```
@ -226,7 +226,7 @@ $ docker-compose logs -f
### Stopping the project ### Stopping the project
You can hit <ctrl>C in the terminal window running `docker-compose up`. You can hit `ctrl-C` in the terminal window that ran `docker-compose up`.
Once that shutdown sequence is complete, it is important to run the `docker-compose down` command. Once that shutdown sequence is complete, it is important to run the `docker-compose down` command.
@ -251,7 +251,7 @@ services again with 'docker-compose up'.
To restart a specific service, first use `docker ps` to see the list of services running. To restart a specific service, first use `docker ps` to see the list of services running.
```bash ```bash
docker ps $ docker ps
CONTAINER ID IMAGE COMMAND NAMES CONTAINER ID IMAGE COMMAND NAMES
35043164fd0d example-project/web-api:latest "/gosrv" saas-starter-kit_web-api_1 35043164fd0d example-project/web-api:latest "/gosrv" saas-starter-kit_web-api_1
d34c8fc27f3b example-project/web-app:latest "/gosrv" saas-starter-kit_web-app_1 d34c8fc27f3b example-project/web-app:latest "/gosrv" saas-starter-kit_web-app_1
@ -259,23 +259,23 @@ fd844456243e postgres:11-alpine "docker-entrypoint.s…"
dda16bfbb8b5 redis:latest "redis-server --appe…" saas-starter-kit_redis_1 dda16bfbb8b5 redis:latest "redis-server --appe…" saas-starter-kit_redis_1
``` ```
Then use `docker-compose down` for a specific service. In the command include the name of the container for the service Then use `docker-compose stop` for a specific service. In the command including the name of service in `docker-compose.yaml` file for the service
to shut down. In the example command, we will shut down down the web-api service so we can start it again. to shut down. In the example command, we will shut down the web-api service so we can start it again.
```bash ```bash
docker-compose down saas-starter-kit_web-api_1 $ docker-compose stop web-app
``` ```
If you are not in the directory for the service you want to restart navigate to it. We will go to the directory for the If you are not in the directory for the service you want to restart then navigate to it. We will go to the directory for the
web-api. web-api.
```bash ```bash
cd cmd/web-api/ $ cd cmd/web-api/
``` ```
Then you can start the service again by running main.go Then you can start the service again by running main.go
```bash ```bash
go run main.go $ go run main.go
``` ```
@ -283,7 +283,7 @@ go run main.go
By default the project will compile and run without AWS configs or other third-party dependencies. By default the project will compile and run without AWS configs or other third-party dependencies.
As you use start utilizing AWS services in this project and/or ready for deployment, you will need to start specifying As you start utilizing AWS services in this project and/or ready for deployment, you will need to start specifying
AWS configs in a docker-compose file. You can also set credentials for other dependencies in the new docker-compose file AWS configs in a docker-compose file. You can also set credentials for other dependencies in the new docker-compose file
too. too.
@ -291,7 +291,7 @@ The sample docker-compose file is not loaded since it is named sample, which all
configs. configs.
To set AWS configs and credentials for other third-party dependencies, you need to create a copy of the sample To set AWS configs and credentials for other third-party dependencies, you need to create a copy of the sample
docker-compose file without "sample" prepending the file name. environment docker-compose file without "sample" prepending the file name.
Navigate to the root of the project. Copy `sample.env_docker_compose` to `.env_docker_compose`. Navigate to the root of the project. Copy `sample.env_docker_compose` to `.env_docker_compose`.
@ -311,20 +311,20 @@ $ DD_API_KEY=
``` ```
In your new copy of the example docker-compose file ".env_docker_compose", set the AWS configs by updating the following In your new copy of the example docker-compose file ".env_docker_compose", set the AWS configs by updating the following
environmental variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION. Remember to remove the $ before the environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION. Remember to remove the $ before the
variable name. variable name.
As noted in the Local Installation section, the project is integrated with Datadog for observability. You can specify As noted in the Local Installation section, the project is integrated with Datadog for observability. You can specify
the API key for you Datadog account by setting the environmental variable: DD_API_KEY. the API key for your Datadog account by setting the environment variable: DD_API_KEY.
## Web API ## Web API
[cmd/web-api](https://gitlab.com/geeks-accelerator/oss/saas-starter-kit/tree/master/cmd/web-api) [cmd/web-api](https://gitlab.com/geeks-accelerator/oss/saas-starter-kit/tree/master/cmd/web-api)
REST API available to clients for supporting deeper integrations. This API is also a foundation for third-party REST API is available to clients for supporting deeper integrations. This API is also a foundation for third-party
integrations. The API implements JWT authentication that renders results as JSON to clients. integrations. The API implements JWT authentication that renders results as JSON to clients.
Once the web-app service is running it will be available on port 3001. Once the web-api service is running it will be available on port 3001.
http://127.0.0.1:3001/ http://127.0.0.1:3001/
This web-api service is not directly used by the web-app service to prevent locking the functionally required for This web-api service is not directly used by the web-app service to prevent locking the functionally required for
@ -334,7 +334,7 @@ client expectations.
The web-app will have its own internal API, similar to this external web-api service, but not exposed for third-party The web-app will have its own internal API, similar to this external web-api service, but not exposed for third-party
integrations. It is believed that in the beginning, having to define an additional API for internal purposes is worth integrations. It is believed that in the beginning, having to define an additional API for internal purposes is worth
the additional effort as the internal API can handle more flexible updates. for the additional effort as the internal API can handle more flexible updates.
For more details on this service, read [web-api readme](https://gitlab.com/geeks-accelerator/oss/saas-starter-kit/blob/master/cmd/web-api/README.md) For more details on this service, read [web-api readme](https://gitlab.com/geeks-accelerator/oss/saas-starter-kit/blob/master/cmd/web-api/README.md)