Skip to content

Latest commit

 

History

History
214 lines (125 loc) · 9.02 KB

README.md

File metadata and controls

214 lines (125 loc) · 9.02 KB
Raw

🍱 Gin Rest Prisma Boilerplate

Golang Logo Gin Logo

Golang, is a statically typed, compiled programming language designed at Google that aids in building simple, reliable, and efficient software. Gin is a full-featured web framework for Go that achieves outstanding performance.

GoDoc codebeat badge Build Status GitHub license FOSSA Status

📚 Description

This boilerplate leverages the Gin framework to quickly prototype backend applications. It comes with database, logging, security, and authentication features out of the box.

🍬 Features

  • Based on Gin.

  • Prisma ORM for Mongo. But can support MYSQL/PostgreSQL and Amazon Aurora.

  • Gin Sessions for Redis.

  • Gin Authz for role based access management. Internally, utilizing the powerful authentication library Casbin.

  • Viper for working with yaml configurations.

  • Gin Swagger for API specifications.

🛠️ Prerequisites

🐳 Docker

Please make sure to have Docker Desktop operational on the preferred operating system of choice to quickly get started. To get started, please see the following link.

Note: Despite the fact that Docker Desktop comes free for both Mac and Windows, it only supports the Pro edition of Windows 10. A common workaround is to get Docker Toolbox which will bypass the Windows 10 Pro restriction by executing Docker in a VM.

🧰 Node

The Prisma CLI is essential for streamlining workflows in managing and deploying Prisma services. The CLI can to be downloaded using npm; which requires NodeJS.

Then, the following command will download the Prisma command line interface:

// prisma cli
$ npm install -g prisma

🔨 Getting Started

If need be, replace the existing configuration variables in the config.yaml file with the preferred configuration values.

Changing the server.env : "test" to server.env : "dev" yields better logging that can come of use when developing.

🗳️ + 🐳 Developing Inside Docker

VSCode permits the development of source code to happen exclusively in a Docker container. For more information on how this works, please read the following documentation.

This boilerplate comes with a .devcontainer configuration enabling such a feature.

To get started:

  1. Clone this repository.
  2. Open VSCode and download the Remote-Containers extension.
  3. Press F1 and select the Remote-Containers: Open Folder in Container... command.
  4. Select the cloned copy of this folder, wait for the container to start.
  5. Run make prisma-endpoint-to-docker to guarantee prisma deploy works as intended.
  6. Run make prisma-deploy or prisma deploy.
  7. Run make dev (server reloading) or make run (no server reloading)
  8. Start developing!

⛲ Developing Locally Outside of Docker

Developing locally is still possible but requires some tweaks. The application dependencies such as Prisma, Mongo, and Redis will still require Docker to run. Mainly because Prisma can't be set up locally like Mongo and Redis. But the code itself will not be containerized.

  • Execute the following command to run the application dependencies in Docker without building the web application container:
# runs the application locally with only dependencies executing in docker
$ make develop-locally

# entrypoint for web application
$ make dev

#or (for development without server reloading)
$ make run

Why both Redis and Mongo❓

The design behind making the session management, Redis based, instead of Mongo based, came down to understanding that constant reads and writes to a database for cookie management were redundant and ineffective. The focus was to leave the persistent data in Mongo and less important session-based data in Redis.

🔒 Environment Configuration

As mentioned before, this application leverages the Viper module, which can read in configuration variables from the config.yaml file.

This is a breakdown of the variables:

server.env - the application environment it will be executing in, either in development, production, or testing. Options: dev, test, or prod.

server.port - the default port to expose the application to.

session.name - the name of the session for redis.

redis.idle_connections - the number of idle connections redis should support (default is 10).

redis.network_type - redis network type, default is "tcp" but "udp" is also supported.

redis.address - the URL to redis endpoint.

redis.secret_key - secret key to the redis store.

redis.password - redis password for authentication.

📦 Dep Package Manager

  • Dep is a package manager for Go. It aids in managing packages for any Go application.

Getting stated with Dep:

On Mac:

$ brew install dep
$ brew upgrade dep

Other Platforms:

# downloads dep package manager
$ curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh
  • Navigate to the project directory, initialize Dep by running dep init then remove the go.mod and go.sum files.
# ensuring dep dependencies are present
$ dep ensure

Note: On Windows, please use Git Bash or WSL where curl is included by default.

✨ Choosing Go Modules over Dep

One can choose Go Modules over Dep as its a native module version manager for Golang.

  1. Run go mod init
  2. Run go mod download to ensure dependencies are downloaded in the GOPATH.
  3. Run go mod tidy to incorporate version locking.
  4. Remove dep files with rm -rf vendor Gopkg.*

🧪 Testing

Depending on where the development is occurring; in docker or not, tests can be executed through the Docker shell or locally.

$ go test -v ./tests/*

🗃️ Makefile

This boilerplate comes with a lot of crucial Makefile methods to aid in development.

develop-locally: responsible for preparing the application to be developed locally, it composes redis, mongo and prisma to run locally.

build : builds the application for deployment.

clean: removes the generated binary from the build command.

test: runs e2e testing.

dev: Starts the application with fresh to enable auto reloading on saves. Can be paired with docs command to automate viewing api spec changes.

docs: generates swagger docs.

run: starts the server without fresh, meaning auto-reloading won't happen on file saves.

compose-deps: composes prisma, mongo, and redis only.

prisma-endpoint-to-local: changes the prisma.yml endpoint to localhost so that prisma deploy can work properly when developing locally.

prisma-endpoint-to-docker: changes the prisma.yml endpoint to the prisma container so that prisma deploy can work properly when developing in a container.

prisma-deploy: generates the prisma client files and deploys the prisma datamodel.

📝 License

GRPB is MIT licensed.

Author: Sal Anvarov.

FOSSA Status