golang-saas-starter-kit/example-project/README.md

# SaaS Service

Copyright 2019, Geeks Accelerator  
twins@geeksaccelerator.com


## Description

This is a project that provides a starter-kit for a REST based web service. It provides best practices around Go web services using POD architecture and design. It contains the following features:

* Minimal application web framework.
* Middleware integration.
* Database support using MongoDB.
* CRUD based pattern.
* Distributed logging and tracing.
* Testing patterns.
* User authentication.
* POD architecture with sidecars for metrics and tracing.
* Use of Docker, Docker Compose, and Makefiles.
* Vendoring dependencies with Modules, requires Go 1.11 or higher.

This project has the following example services:

* web api - Used to publically expose handlers
* web app - Display and render html.
* schema - Tool for initializing of db and schema migration.


## Local Installation

This project contains three services and uses 3rd party services: 
* redis - key / value storage for sessions and other web data. Used only as emphemeral storage.
* postgres - transaction database for persitance of all data.
* datadog - metrics, logging, and tracing

Docker is required to run this software on your local machine.

An AWS account is required for the project to run because of the following dependancies on AWS:
* secret manager
* s3

Required for deploymenet:
* ECS Fargate
* RDS 
* Route

### Getting the project

You can use the traditional `go get` command to download this project into your configured GOPATH.

```
$ go get -u gitlab.com/geeks-accelerator/oss/saas-starter-kit
```

### Go Modules

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. This project assumes the source code will be inside your GOPATH within the traditional location.

```
cd $GOPATH/src/geeks-accelerator/oss/saas-starter-kit/example-project
GO111MODULE=on go mod tidy
```

It's recommended to set use at least go 1.12 and enable go modules.

```bash
echo "export  GO111MODULE=on" >> ~/.bash_profile
```

### Installing Docker

Docker is a critical component to managing and running this project. 

https://docs.docker.com/install/

If you are having problems installing docker reach out or jump on [Gopher Slack](http://invite.slack.golangbridge.org/) for help.

## Running The Project

There is a `docker-compose` file that knows how to build and run all the services. Each service has it's own a `dockerfile`.

A `makefile` has also been provide to make building, running and testing the software easier.

### Building the project

Navigate to the root of the project and use the `makefile` to build all of the services.

```
$ cd $GOPATH/src/geeks-accelerator/oss/saas-starter-kit/example-project
$ make all
```

### Running the project

Navigate to the root of the project and use the `makefile` to run all of the services.

```
$ cd $GOPATH/src/geeks-accelerator/oss/saas-starter-kit/example-project
$ make up
```

The `make up` command will leverage Docker Compose to run all the services, including the 3rd party services. The first time to run this command, Docker will download the required images for the 3rd party services.

Default configuration is set which should be valid for most systems. Use the `docker-compose.yaml` file to configure the services differently is necessary. Email me if you have issues or questions.

### Stopping the project

You can hit <ctrl>C in the terminal window running `make up`. Once that shutdown sequence is complete, it is important to run the `make down` command.

```
$ <ctrl>C
$ make down
```

Running `make down` will properly stop and terminate the Docker Compose session.

## About The Project

The service provides record keeping for someone running a multi-family garage sale. Authenticated users can maintain a list of projects for sale.


### Making Requests

#### Initial User

To make a request to the service you must have an authenticated user. Users can be created with the API but an initial admin user must first be created. While the service is running you can create the initial user with the command `make admin`

```
$ make admin
```

This will create a user with email `admin@example.com` and password `gophers`.

#### Authenticating

Before any authenticated requests can be sent you must acquire an auth token. Make a request using HTTP Basic auth with your email and password to get the token.

```
$ curl --user "admin@example.com:gophers" http://localhost:3000/v1/users/token
```

I suggest putting the resulting token in an environment variable like `$TOKEN`.

#### Authenticated Requests

To make authenticated requests put the token in the `Authorization` header with the `Bearer ` prefix.

```
$ curl -H "Authorization: Bearer ${TOKEN}" http://localhost:3000/v1/users
```


## Making db calls
Currently postgres is only supported for sqlxmigrate. MySQL should be easy to add after determing 
better method for abstracting the create table and other SQL statements from the main
testing logic. 

### bindvars
When making new packages that use sqlx, bind vars for mysql are `?` where as postgres is `$1`.
To database agnostic, sqlx supports using `?` for all queries and exposes the method `Rebind` to 
remap the placeholders to the correct database.

```go
sqlQueryStr = db.Rebind(sqlQueryStr)
```

For additional details refer to https://jmoiron.github.io/sqlx/#bindvars

### datadog

Datadog has a custom init script to support setting multiple expvar urls for monitoring. The docker-compose file then can set a single env variable.
```bash
DD_EXPVAR=service_name=web-app env=dev url=http://web-app:4000/debug/vars|service_name=web-api env=dev url=http://web-api:4001/debug/vars
```


## What's Next

We are in the process of writing more documentation about this code. Classes are being finalized as part of the Ultimate series.





## AWS Permissions

Base required permissions
```
secretsmanager:CreateSecret 
secretsmanager:GetSecretValue 
secretsmanager:ListSecretVersionIds 
secretsmanager:PutSecretValue 
secretsmanager:UpdateSecret 
```

If cloudfront enabled for static files
```
cloudFront:ListDistributions
```

Additional permissions required for unittests
```
secretsmanager:DeleteSecret
```




### TODO:
* update makefile

additianal info required here in readme

need to copy sample.env_docker_compose to .env_docker_compose and defined your aws configs for docker-compose

need to add mid tracer for all requests


/*
ZipKin: http://localhost:9411
AddLoad: hey -m GET -c 10 -n 10000 "http://localhost:3000/v1/users"
expvarmon -ports=":3001" -endpoint="/metrics" -vars="requests,goroutines,errors,mem:memstats.Alloc"
*/

/*
Need to figure out timeouts for http service.
You might want to reset your DB_HOST env var during test tear down.
Service should start even without a DB running yet.
symbols in profiles: https://github.com/golang/go/issues/23376 / https://github.com/google/pprof/pull/366
*/