Requirements

• go 1.11 or higher.
• Make sure that you activate Go Modules

Installation, please read this before running anything.

$ make

• Through this we install some binaries and all the go libraries that the project needs.

Go Modules

• If you need more information about them please go here
• To install new dependencies just use go get

Creating an API through gin-gonic

$ make run

• This will run an HTTP server in port 8080, if you want to change this port you have to specify it through the environment variable (AUTH_SERVER_PORT) in the .env file.
• For testing all existing endpoints you can try them out in swagger UI.

How to generate API documentation

• Initialize the documentation (this will generate a docs folder in the root folder)

$ make api-docs

or

$ swag init -g ./api/main.go

• Then we make run and go to http://localhost:8080/documentation/index.html

How to make build of a main.go file and run it on Linux.

$ make build

or

$ go build -o ./tmp/auth-server ./api/main.go

• The command above will create a file called auth-server in folder tmp, that file is an executable with the main in ./api/main.go
• To run your executable you have to:
  • Make it executable: chmod +x ./tmp/auth-server
  • Run it: ./tmp/auth-server
• You can build whatever you want (it doesn't have to be a web-server), for example there is another main with which you can follow the same steps ./cmd/cli/main.go

Building for MacOS

$ make build-for-mac

• Same steps as above, an executable will be created in ./tpm/

Building for Windows

$ make build-for-windows

• Same steps as above, an executable will be created in ./tpm/

How to run format

• We use go vet and go fmt for simple linter and formatting, running make format will do.
• This commands are run also when we run the project, you can check the Makefile to know exactly in which commands is used.

How to run the linter

• For the linter we are using golangci-lint
• To run it you can either use:

$ make lint

or

$ golangci-lint run

Logging framework

• We are using Logrus as a logging framework
• This is how we initialize the logger here, specifically InitializeLogger
• We have to run InitializeLogger before using the Log function, here's an example
• Finally examples of using the logger
• Visit their website for advance information on how to use it.

How to handle environment variables

• For environment variables we use the same .env mechanism that we all know, for more information here's the library
• You can either use the mechanism to read the environment variables from the .env file that's explain in the library above OR use this one in this other library
• Here's how we load the .env file
• For an example you can check here, we are using the second library method which let us use tags in structs. Then we load the struct with the values like this
• For testing this you can create a .env file with a different port than the default, you will see how the web server is initialize in the port you specified in the .env, you can just change the name of .env-template to .env and that will do the trick.

How to run the tests

$ make test

or

$ go test -cover -v ./...

• This will run all the test files in the project.
• Test should be in the same folder of the file they are testing and the file name of the test must have the suffix _test, if you see the example in test folder you will get it right away.
• Gomega is being used for improving assertion mechanism.

How to see test coverage

• will show information about the coverage:

$ make test

• if you want to only see the test coverage information (without the tests logs):

$ make coverage

• if you want to see the coverage in detail in a browser:

$ make coverage-html

• For knowing how are we generating test coverage please check this

Storage

• This project uses an SQLite database as default storage, for now this will be the only storage capability of the project. Possibly in the future we will have different ways of providing external storage to the system.

• We are also using an ORM library.

TL;DR How to run/build

• Build: $ make build or $ go build -o <destination_of_executable_relative_to_root> <path_of_main_file_relative_to_root>
• Run:
  • Without executable: $ make run or $ go run <path_of_main_file_relative_to_root>
  • With executable:
    • Make the file executable: $ chmod +x <path_to_executable_relative_to_root>
    • Run it: $ <path_to_executable_relative_to_root>

Docker

Getting Started

At the time of configuration we used Docker version 19.03.1 and Docker Compose version 1.24.1

Prerequisites

In order to run this container you'll need docker and docker-compose installed. You will also need to configure the .env in the root of the project, please read the environment section.

Usage

To run the container you should run:

$ make docker-run

If you need to build the image:

$ make docker-build

Behind the scenes we are using docker-compose, but you could build and run the same configuration using docker:

$ docker build -f build/package/Dockerfile -t authentication_api .

$ docker run -d --env-file=.env -p 9000:9000 --name authentication_api authentication_api

Notes

If you want more information about all the folders being used in this project please refer to the original template. Thanks for the authors of this one!