chore(build): refactoring makefile for better usability and introducing a default help target (#2930)

.github/workflows/ci.yml

@@ -72,10 +72,10 @@ jobs:
     - name: Docker Build
       if: (!startsWith(github.head_ref, 'release'))
       run: |
-        make docker
+        make build-docker
 
     # For release testing
     - name: Docker Build All
       if: github.base_ref == 'master' && startsWith(github.head_ref, 'release')
       run: |
-        make docker-all
+        make build-docker-all

.github/workflows/nightly.yml

@@ -34,8 +34,8 @@ jobs:
 
     - name: Build images
       run: |
-        make docker-nightly-build
+        make nightly-build
 
     - name: Push images
       run: |
-        make docker-nightly-push
+        make nightly-push

.github/workflows/publish-release.yml

@@ -122,8 +122,8 @@ jobs:
 
     - name: Build images
       run: |
-        make docker-all
+        make build-docker-all
     
     - name: Push images
       run: |
-        make docker-push-all
+        make push-docker-all

Makefile

@@ -1,3 +1,29 @@
+#!/usr/bin/env bash
+
+#
+# Makefile with some common workflow for dev, build and test
+#
+
+##@ General
+
+# The help target prints out all targets with their descriptions organized
+# beneath their categories. The categories are represented by '##@' and the
+# target descriptions by '##'. The awk command is responsible for reading the
+# entire set of makefiles included in this invocation, looking for lines of the
+# file as xyz: ## something, and then pretty-format the target and help. Then,
+# if there's a line with ##@ something, that gets pretty-printed as a category.
+# More info on the usage of ANSI control characters for terminal formatting:
+# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
+# More info on the awk command:
+# http://linuxcommand.org/lc3_adv_awk.php
+
+# The following help command is Licensed under the Apache License, Version 2.0 (the "License")
+# Copyright 2023 The Kubernetes Authors.
+.PHONY: help
+help: ## Display this help
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+
 GO ?= go
 GOLANGCILINT ?= golangci-lint
 
@@ -22,24 +48,10 @@ ifeq ($(COVER),true)
 TESTCOVER ?= -coverprofile c.out
 endif
 
-.PHONY: all
-all: lint $(BINARY)
-
-.PHONY: clean
-clean:
-	-rm -rf release
-	-rm -f $(BINARY)
-
-.PHONY: distclean
-distclean: clean
-	rm -rf vendor
-
-.PHONY: lint
-lint: validate-go-version
-	GO111MODULE=on $(GOLANGCILINT) run
+##@ Build
 
 .PHONY: build
-build: validate-go-version clean $(BINARY)
+build: validate-go-version clean $(BINARY) ## Build and create oauth2-proxy binary from current source code
 
 $(BINARY):
 	CGO_ENABLED=0 $(GO) build -a -installsuffix cgo -ldflags="-X github.com/oauth2-proxy/oauth2-proxy/v7/pkg/version.VERSION=${VERSION}" -o $@ github.com/oauth2-proxy/oauth2-proxy/v7
@@ -60,60 +72,92 @@ DOCKER_BUILDX_ARGS_ALPINE            ?= --build-arg RUNTIME_IMAGE=${DOCKER_BUILD
 DOCKER_BUILDX_X_PLATFORM_ALPINE      := docker buildx build ${DOCKER_BUILDX_ARGS_ALPINE} --platform ${DOCKER_BUILD_PLATFORM_ALPINE}
 DOCKER_BUILDX_PUSH_X_PLATFORM_ALPINE := $(DOCKER_BUILDX_X_PLATFORM_ALPINE) --push
 
-.PHONY: docker
-docker:
+.PHONY: build-docker
+build-docker: build-distroless build-alpine ## Build multi architecture docker images in both flavours (distroless / alpine)
+
+.PHONY: build-distroless
+build-distroless: ## Build multi architecture distroless based docker image
 	$(DOCKER_BUILDX_X_PLATFORM) -t $(REGISTRY)/$(REPOSITORY):latest -t $(REGISTRY)/$(REPOSITORY):${VERSION} .
+
+.PHONY: build-alpine
+build-alpine: ## Build multi architecture alpine based docker image
 	$(DOCKER_BUILDX_X_PLATFORM_ALPINE) -t $(REGISTRY)/$(REPOSITORY):latest-alpine -t $(REGISTRY)/$(REPOSITORY):${VERSION}-alpine .
 
-.PHONY: docker-push
-docker-push:
-	$(DOCKER_BUILDX_PUSH_X_PLATFORM) -t $(REGISTRY)/$(REPOSITORY):latest -t $(REGISTRY)/$(REPOSITORY):${VERSION} .
-	$(DOCKER_BUILDX_PUSH_X_PLATFORM_ALPINE) -t $(REGISTRY)/$(REPOSITORY):latest-alpine -t $(REGISTRY)/$(REPOSITORY):${VERSION}-alpine .
-
-.PHONY: docker-all
-docker-all: docker
+.PHONY: build-docker-all
+build-docker-all: build-docker ## Build docker images for all supported architectures in both flavours (distroless / alpine)
 	$(DOCKER_BUILDX) --platform linux/amd64   -t $(REGISTRY)/$(REPOSITORY):latest-amd64   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-amd64 .
 	$(DOCKER_BUILDX) --platform linux/arm64   -t $(REGISTRY)/$(REPOSITORY):latest-arm64   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-arm64 .
 	$(DOCKER_BUILDX) --platform linux/ppc64le -t $(REGISTRY)/$(REPOSITORY):latest-ppc64le -t $(REGISTRY)/$(REPOSITORY):${VERSION}-ppc64le .
 	$(DOCKER_BUILDX) --platform linux/arm/v7  -t $(REGISTRY)/$(REPOSITORY):latest-armv7   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-armv7 .
 	$(DOCKER_BUILDX) --platform linux/s390x   -t $(REGISTRY)/$(REPOSITORY):latest-s390x -t $(REGISTRY)/$(REPOSITORY):${VERSION}-s390x .
 
-.PHONY: docker-push-all
-docker-push-all: docker-push
+
+##@ Publish
+
+.PHONY: push-docker
+push-docker: push-distroless push-alpine ## Push multi architecture docker images for both flavours (distroless / alpine)
+
+.PHONY: push-distroless
+push-distroless: ## Push multi architecture distroless based docker image
+	$(DOCKER_BUILDX_PUSH_X_PLATFORM) -t $(REGISTRY)/$(REPOSITORY):latest -t $(REGISTRY)/$(REPOSITORY):${VERSION} .
+
+.PHONY: push-alpine
+push-alpine: ## Push multi architecture alpine based docker image
+	$(DOCKER_BUILDX_PUSH_X_PLATFORM_ALPINE) -t $(REGISTRY)/$(REPOSITORY):latest-alpine -t $(REGISTRY)/$(REPOSITORY):${VERSION}-alpine .
+
+.PHONY: push-docker-all
+push-docker-all: push-docker ## Push docker images for all supported architectures for both flavours (distroless / alpine)
 	$(DOCKER_BUILDX_PUSH) --platform linux/amd64   -t $(REGISTRY)/$(REPOSITORY):latest-amd64   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-amd64 .
 	$(DOCKER_BUILDX_PUSH) --platform linux/arm64   -t $(REGISTRY)/$(REPOSITORY):latest-arm64   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-arm64 .
 	$(DOCKER_BUILDX_PUSH) --platform linux/ppc64le -t $(REGISTRY)/$(REPOSITORY):latest-ppc64le -t $(REGISTRY)/$(REPOSITORY):${VERSION}-ppc64le .
 	$(DOCKER_BUILDX_PUSH) --platform linux/arm/v7  -t $(REGISTRY)/$(REPOSITORY):latest-armv7   -t $(REGISTRY)/$(REPOSITORY):${VERSION}-armv7 .
 	$(DOCKER_BUILDX_PUSH) --platform linux/s390x   -t $(REGISTRY)/$(REPOSITORY):latest-s390x -t $(REGISTRY)/$(REPOSITORY):${VERSION}-s390x .
 
-.PHONY: docker-nightly-build
-docker-nightly-build:
+
+##@ Nightly scheduling
+
+.PHONY: nightly-build
+nightly-build: ## Nightly build command for docker images in both flavours (distroless / alpine)
 	$(DOCKER_BUILDX_X_PLATFORM) -t $(REGISTRY)/$(REPOSITORY)-nightly:latest -t $(REGISTRY)/$(REPOSITORY)-nightly:${DATE} .
 	$(DOCKER_BUILDX_X_PLATFORM_ALPINE) -t ${REGISTRY}/$(REPOSITORY)-nightly:latest-alpine -t $(REGISTRY)/$(REPOSITORY)-nightly:${DATE}-alpine .
 
-.PHONY: docker-nightly-push
-docker-nightly-push:
+.PHONY: nightly-push
+nightly-push: ## Nightly push command for docker images in both flavours (distroless / alpine)
 	$(DOCKER_BUILDX_PUSH_X_PLATFORM) -t $(REGISTRY)/$(REPOSITORY)-nightly:latest -t $(REGISTRY)/$(REPOSITORY)-nightly:${DATE} .
 	$(DOCKER_BUILDX_PUSH_X_PLATFORM_ALPINE) -t ${REGISTRY}/$(REPOSITORY)-nightly:latest-alpine -t $(REGISTRY)/$(REPOSITORY)-nightly:${DATE}-alpine .
 
+
+##@ Docs
+
 .PHONY: generate
-generate:
+generate: ## Generate alpha config docs from golang structs
 	go generate ./pkg/...
 
 .PHONY: verify-generate
-verify-generate: generate
+verify-generate: generate ## Verify command to check if alpha config docs are in line with golang struct changes
 	git diff --exit-code
 
+##@ Miscellaneous
+
 .PHONY: test
-test: lint
+test: lint ## Run all Go tests
 	GO111MODULE=on $(GO) test $(TESTCOVER) -v -race ./...
 
 .PHONY: release
-release: validate-go-version lint test
+release: validate-go-version lint test ## Create a full release for all architectures (binaries and checksums)
 	BINARY=${BINARY} VERSION=${VERSION} ./dist.sh
 
+.PHONY: clean
+clean: ## Cleanup release and build files
+	-rm -rf release
+	-rm -f $(BINARY)
+
+.PHONY: lint
+lint: validate-go-version ## Lint all files using golangci-lint
+	GO111MODULE=on $(GOLANGCILINT) run
+
 .PHONY: validate-go-version
-validate-go-version:
+validate-go-version: ## Validate Go environment requirements
 	@if [ $(GO_MAJOR_VERSION) -gt $(MINIMUM_SUPPORTED_GO_MAJOR_VERSION) ]; then \
 		exit 0 ;\
 	elif [ $(GO_MAJOR_VERSION) -lt $(MINIMUM_SUPPORTED_GO_MAJOR_VERSION) ]; then \

README.md

@@ -1,4 +1,4 @@
-[![Continuous Integration](https://github.com/oauth2-proxy/oauth2-proxy/actions/workflows/ci.yaml/badge.svg)](https://github.com/oauth2-proxy/oauth2-proxy/actions/workflows/ci.yaml)
+[![Continuous Integration](https://github.com/oauth2-proxy/oauth2-proxy/actions/workflows/ci.yml/badge.svg)](https://github.com/oauth2-proxy/oauth2-proxy/actions/workflows/ci.yml)
 [![Go Report Card](https://goreportcard.com/badge/github.com/oauth2-proxy/oauth2-proxy)](https://goreportcard.com/report/github.com/oauth2-proxy/oauth2-proxy)
 [![GoDoc](https://godoc.org/github.com/oauth2-proxy/oauth2-proxy?status.svg)](https://godoc.org/github.com/oauth2-proxy/oauth2-proxy)
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

RELEASE.md

@@ -41,8 +41,8 @@ Note this uses `v4.1.0` as an example release number.
 10. Publish release in Github
 11. Make and push docker images to Quay
   ```
-  make docker-all
-  make docker-push-all
+  make build-docker-all
+  make push-docker-all
   ```
   Note: Ensure the docker tags don't include `-dirty`. This means you have uncommitted changes.
 

docs/docs/community/contribution.md

@@ -68,11 +68,22 @@ For starting oauth2-proxy locally open the debugging tab and create the `launch.
 
 Before you can start your local version of oauth2-proxy, you will have to use the provided docker compose files to start a local upstream service and identity provider. We suggest using [httpbin](https://hub.docker.com/r/kennethreitz/httpbin) as your upstream for testing as it allows for request and response introspection of all things HTTP.
 
-Open a terminal and switch to the `contrib/local-environment` directory.
+Inside the `contrib/local-environment` directory you can use the `Makefile` for
+starting different example setups:
 
-- Dex as your IdP: `docker compose -f docker-compose.yaml up dex etcd httpbin`
-- Keycloak as your IdP: `docker compose -f docker-compose-keycloak.yaml up keycloak httpbin`
+- Dex as your IdP: `make up` or `make down`
+- Dex as your IdP using the alpha-config: `make alpha-config-up`
+- Keycloak as your IdP: `make keycloak-up`
+- Dex as your IdP & nginx reverse proxy: `make nginx-up`
+- and many more...
 
-The username for both is `admin@example.com` and password is `password`.
+Check out the `Makefile` to see what is available.
+
+The username and password for all setups is usually `admin@example.com` and `password`.
+
+The docker compose setups expose the services with a dynamic reverse DNS resolver: localtest.me
+
+- OAuth2-Proxy: http://oauth2-proxy.localtest.me:4180
+- Upstream: http://httpbin.localtest.me:8080
+- Dex: http://dex.localtest.me:4190
 
-Start oauth2-proxy from the debug tab and open http://oauth2-proxy.localtest.me:4180/ for testing.

docs/versioned_docs/version-7.8.x/community/contribution.md

@@ -68,11 +68,22 @@ For starting oauth2-proxy locally open the debugging tab and create the `launch.
 
 Before you can start your local version of oauth2-proxy, you will have to use the provided docker compose files to start a local upstream service and identity provider. We suggest using [httpbin](https://hub.docker.com/r/kennethreitz/httpbin) as your upstream for testing as it allows for request and response introspection of all things HTTP.
 
-Open a terminal and switch to the `contrib/local-environment` directory.
+Inside the `contrib/local-environment` directory you can use the `Makefile` for
+starting different example setups:
 
-- Dex as your IdP: `docker compose -f docker-compose.yaml up dex etcd httpbin`
-- Keycloak as your IdP: `docker compose -f docker-compose-keycloak.yaml up keycloak httpbin`
+- Dex as your IdP: `make up` or `make down`
+- Dex as your IdP using the alpha-config: `make alpha-config-up`
+- Keycloak as your IdP: `make keycloak-up`
+- Dex as your IdP & nginx reverse proxy: `make nginx-up`
+- and many more...
 
-The username for both is `admin@example.com` and password is `password`.
+Check out the `Makefile` to see what is available.
+
+The username and password for all setups is usually `admin@example.com` and `password`.
+
+The docker compose setups expose the services with a dynamic reverse DNS resolver: localtest.me
+
+- OAuth2-Proxy: http://oauth2-proxy.localtest.me:4180
+- Upstream: http://httpbin.localtest.me:8080
+- Dex: http://dex.localtest.me:4190
 
-Start oauth2-proxy from the debug tab and open http://oauth2-proxy.localtest.me:4180/ for testing.