Merge pull request #8 from create-go-app/dev

Update README

Author: Vic Shóstak

.dockerignore

@@ -2,14 +2,14 @@
 .dockerignore
 .editorconfig
 .gitignore
+.env.example
 Dockerfile
 Makefile
 LICENSE
-*.md
+**/*.md
+**/*_test.go
 
 # Folders
 .git/
 .github/
-.task/
-app/
-**/*_test.go
+build/

Makefile

@@ -32,7 +32,11 @@ migrate.force:
 docker.build:
 	docker build -t net_http-go-template .
 
-docker.run: docker.net_http docker.postgres
+docker.network:
+	docker network inspect dev-network >/dev/null 2>&1 || \
+	docker network create -d bridge dev-network
+
+docker.run: docker.network docker.net_http docker.postgres
 
 docker.stop:
 	docker stop dev-net_http dev-postgres

README.md

@@ -1,82 +1,115 @@
 # net/http backend template for [Create Go App CLI](https://github.com/create-go-app/cli)
 
-<img src="https://img.shields.io/badge/Go-1.11+-00ADD8?style=for-the-badge&logo=go" alt="go version" />&nbsp;<a href="https://gocover.io/github.com/create-go-app/net_http-go-template/pkg/apiserver" target="_blank"><img src="https://img.shields.io/badge/Go_Cover-49%25-success?style=for-the-badge&logo=none" alt="go cover" /></a>&nbsp;<a href="https://goreportcard.com/report/github.com/create-go-app/net_http-go-template" target="_blank"><img src="https://img.shields.io/badge/Go_report-A+-success?style=for-the-badge&logo=none" alt="go report" /></a>&nbsp;<img src="https://img.shields.io/badge/license-mit-red?style=for-the-badge&logo=none" alt="license" />
+<img src="https://img.shields.io/badge/Go-1.16+-00ADD8?style=for-the-badge&logo=go" alt="go version" />&nbsp;<a href="https://goreportcard.com/report/github.com/create-go-app/net_http-go-template" target="_blank"><img src="https://img.shields.io/badge/Go_report-A+-success?style=for-the-badge&logo=none" alt="go report" /></a>&nbsp;<img src="https://img.shields.io/badge/license-mit-red?style=for-the-badge&logo=none" alt="license" />
 
 Package `net` provides a portable interface for network I/O, including TCP/IP, UDP, domain name resolution, and Unix domain sockets. Although the package provides access to low-level networking primitives.
 
 Package [`net/http`](https://golang.org/pkg/net/http/) provides HTTP client and server implementations.
 
 ## ⚡️ Quick start
 
-1. Create a new project:
+1. Create a new project with Fiber:
 
 ```bash
 cgapp create
+
+# Choose a backend framework:
+# > net/http
+#   Fiber
 ```
 
-2. Run project by this command:
+2. Run Docker container with database (_by default, for PostgreSQL_):
 
 ```bash
-make run
+make docker.postgres
 ```
 
-## ✅ Used packages
+3. Apply migrations:
 
-- [gorilla/mux](https://github.com/gorilla/mux) `v1.7.4`
-- [go-yaml/yaml](https://github.com/go-yaml/yaml) `v2.3.0`
+```bash
+make migration.up user=<db_user> pass=<db_pass> host=<db_host> table=<db_table>
+```
 
-## 🗄 Template structure
+4. Rename `.env.example` to `.env` and fill it with your environment values.
+
+5. Run project by this command:
 
 ```bash
-.
-├── .dockerignore
-├── .editorconfig
-├── .gitignore
-├── Dockerfile
-├── Makefile
-├── go.mod
-├── go.sum
-├── main.go
-├── configs
-│   └── apiserver.yml
-├── static
-│   └── index.html
-└── pkg
-    └── apiserver
-        ├── config.go
-        ├── config_test.go
-        ├── error_checker.go
-        ├── error_checker_test.go
-        ├── new_server.go
-        ├── new_server_test.go
-        ├── routes.go
-        ├── utils.go
-        └── utils_test.go
-
-4 directories, 17 files
+make run
 ```
 
+6. Go to API Docs page (Swagger): [localhost:5000/swagger/index.html](http://localhost:5000/swagger/index.html).
+
+## 📦 Used packages
+
+| Name                                                                  | Version   | Type       |
+| --------------------------------------------------------------------- | --------- | ---------- |
+| [net/http](https://golang.org/pkg/net/http/)                          | `v1.16.0` | core       |
+| [auth0/go-jwt-middleware](https://github.com/auth0/go-jwt-middleware) | `v1.0.0`  | middleware |
+| [swaggo/http-swagger](https://github.com/swaggo/http-swagger)         | `v1.0.0`  | middleware |
+| [stretchr/testify](https://github.com/stretchr/testify)               | `v1.7.0`  | tests      |
+| [dgrijalva/jwt-go](https://github.com/dgrijalva/jwt-go)               | `v3.2.0`  | auth       |
+| [joho/godotenv](https://github.com/joho/godotenv)                     | `v1.3.0`  | config     |
+| [jmoiron/sqlx](https://github.com/jmoiron/sqlx)                       | `v1.3.1`  | database   |
+| [jackc/pgx](https://github.com/jackc/pgx)                             | `v4.10.1` | database   |
+| [swaggo/swag](https://github.com/swaggo/swag)                         | `v1.7.0`  | utils      |
+| [google/uuid](https://github.com/google/uuid)                         | `v1.2.0`  | utils      |
+| [go-playground/validator](https://github.com/go-playground/validator) | `v10.4.1` | utils      |
+
+## 🗄 Template structure
+
+### ./app
+
+**Folder with business logic only**. This directory doesn't care about _what database driver you're using_ or _which caching solution your choose_ or any third-party things.
+
+- `./app/controllers` folder for functional controllers (used in routes)
+- `./app/models` folder for describe business models and methods of your project
+- `./app/queries` folder for describe queries for models of your project
+- `./app/validators` folder for describe validators for models fields
+
+### ./docs
+
+**Folder with API Documentation**. This directory contains config files for auto-generated API Docs by Swagger.
+
+### ./pkg
+
+**Folder with project-specific functionality**. This directory contains all the project-specific code tailored only for your business use case, like _configs_, _middleware_, _routes_ or _utils_.
+
+- `./pkg/configs` folder for configuration functions
+- `./pkg/middleware` folder for add middleware (Fiber built-in and yours)
+- `./pkg/routes` folder for describe routes of your project
+- `./pkg/utils` folder with utility functions (server starter, error checker, etc)
+
+### ./platform
+
+**Folder with platform-level logic**. This directory contains all the platform-level logic that will build up the actual project, like _setting up the database_ or _cache server instance_ and _storing migrations_.
+
+- `./platform/database` folder with database setup functions (by default, PostgreSQL)
+- `./platform/migrations` folder with migration files (used with [golang-migrate/migrate](https://github.com/golang-migrate/migrate) tool)
+
 ## ⚙️ Configuration
 
-```yaml
-# ./configs/apiserver.yml
-
-# Server config
-server:
-  host: 0.0.0.0
-  port: 5000
-
-# Database config
-database:
-  host: 127.0.0.1
-  port: 5432
-  username: postgres
-  password: 1234
-
-# Static files config
-static:
-  prefix: /
-  path: ./static
+```ini
+# .env
+
+# Server settings:
+SERVER_URL="0.0.0.0:5000"
+SERVER_EMAIL="no-reply@example.com"
+SERVER_EMAIL_PASSWORD="secret"
+
+# JWT settings:
+JWT_SECRET_KEY="secret"
+JWT_REFRESH_KEY="refresh"
+
+# Database settings:
+DB_SERVER_URL="host=localhost port=5432 user=postgres password=password dbname=postgres sslmode=disable"
+DB_MAX_CONNECTIONS=100
+DB_MAX_IDLE_CONNECTIONS=10
+DB_MAX_LIFETIME_CONNECTIONS=2
+
+# SMTP severs settings:
+SMTP_SERVER="smtp.example.com"
+SMTP_PORT=25
 ```
 
 ## ⚠️ License

app/controllers/user_controller.go

@@ -71,8 +71,9 @@ func GetUsers(w http.ResponseWriter, r *http.Request) {
 // @Success 200 {object} models.User
 // @Router /api/public/user/{id} [get]
 func GetUser(w http.ResponseWriter, r *http.Request) {
-	// Define content type.
+	// Define content type and CORS.
 	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Access-Control-Allow-Origin", "*")
 
 	// Catch user ID from URL.
 	id, err := uuid.Parse(r.URL.Query().Get("id"))
@@ -130,8 +131,9 @@ func GetUser(w http.ResponseWriter, r *http.Request) {
 // @Success 200 {object} models.User
 // @Router /api/private/user [post]
 func CreateUser(w http.ResponseWriter, r *http.Request) {
-	// Define content type.
+	// Define content type and CORS.
 	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Access-Control-Allow-Origin", "*")
 
 	// Get now time.
 	now := time.Now().Unix()
@@ -235,8 +237,9 @@ func CreateUser(w http.ResponseWriter, r *http.Request) {
 // @Success 200 {object} models.User
 // @Router /api/private/user [patch]
 func UpdateUser(w http.ResponseWriter, r *http.Request) {
-	// Define content type.
+	// Define content type and CORS.
 	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Access-Control-Allow-Origin", "*")
 
 	// Get now time.
 	now := time.Now().Unix()
@@ -347,8 +350,9 @@ func UpdateUser(w http.ResponseWriter, r *http.Request) {
 // @Success 200 {string} string "ok"
 // @Router /api/private/user [delete]
 func DeleteUser(w http.ResponseWriter, r *http.Request) {
-	// Define content type.
+	// Define content type and CORS.
 	w.Header().Set("Content-Type", "application/json")
+	w.Header().Set("Access-Control-Allow-Origin", "*")
 
 	// Get now time.
 	now := time.Now().Unix()

main.go

@@ -31,7 +31,10 @@ func main() {
 	routes.PrivateRoutes(router)
 	routes.SwaggerRoutes(router)
 
-	// Register API routes.
+	// Register middleware.
+	router.Use(mux.CORSMethodMiddleware(router)) // enable CORS
+
+	// Initialize server.
 	server := configs.ServerConfig(router)
 
 	// Start API server.

pkg/routes/private_routes.go

@@ -20,11 +20,11 @@ func PrivateRoutes(router *mux.Router) {
 	deleteUser := jwtProtected.Handler(http.HandlerFunc(controllers.DeleteUser))
 
 	// Routes for POST method:
-	router.Handle("/api/private/user", createUser).Methods("POST") // create user by ID
+	router.Handle("/api/private/user", createUser).Methods(http.MethodPost) // create user by ID
 
 	// Routes for PATCH method:
-	router.Handle("/api/private/user", updateUser).Methods("PATCH") // update user by ID
+	router.Handle("/api/private/user", updateUser).Methods(http.MethodPatch) // update user by ID
 
 	// Routes for DELETE method:
-	router.Handle("/api/private/user", deleteUser).Methods("DELETE") // delete user by ID
+	router.Handle("/api/private/user", deleteUser).Methods(http.MethodDelete) // delete user by ID
 }

pkg/routes/public_routes.go

@@ -1,13 +1,15 @@
 package routes
 
 import (
+	"net/http"
+
 	"github.com/create-go-app/net_http-go-template/app/controllers"
 	"github.com/gorilla/mux"
 )
 
 // PublicRoutes func for describe group of public routes.
 func PublicRoutes(router *mux.Router) {
 	// Routes for GET method:
-	router.HandleFunc("/api/public/user/{id}", controllers.GetUser).Methods("GET") // get one user by ID
-	router.HandleFunc("/api/public/users", controllers.GetUsers).Methods("GET")    // Get list of all users
+	router.HandleFunc("/api/public/user/{id}", controllers.GetUser).Methods(http.MethodGet) // get one user by ID
+	router.HandleFunc("/api/public/users", controllers.GetUsers).Methods(http.MethodGet)    // Get list of all users
 }

pkg/routes/swagger_routes.go

@@ -1,6 +1,7 @@
 package routes
 
 import (
+	"net/http"
 	"os"
 
 	"github.com/gorilla/mux"
@@ -19,5 +20,5 @@ func SwaggerRoutes(router *mux.Router) {
 	)
 
 	// Routes for GET method:
-	router.PathPrefix("/swagger/").Handler(getSwagger).Methods("GET") // get one user by ID
+	router.PathPrefix("/swagger/").Handler(getSwagger).Methods(http.MethodGet) // get one user by ID
 }