From 367183d7b8d82be2fba2722c79e469cafdec1418 Mon Sep 17 00:00:00 2001 From: Jan Larwig Date: Sun, 27 Apr 2025 20:09:52 +0200 Subject: [PATCH] chore(build): refactoring makefile for better usability and introducing a default help target (#2930) --- .github/workflows/ci.yml | 4 +- .github/workflows/nightly.yml | 4 +- .github/workflows/publish-release.yml | 4 +- Makefile | 116 ++++++++++++------ README.md | 2 +- RELEASE.md | 4 +- docs/docs/community/contribution.md | 21 +++- .../version-7.8.x/community/contribution.md | 21 +++- 8 files changed, 121 insertions(+), 55 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f9e4a377..0d98d90b 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 9693ba3e..b2a69d95 100644 --- a/.github/workflows/nightly.yml +++ b/.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 diff --git a/.github/workflows/publish-release.yml b/.github/workflows/publish-release.yml index 2bdca60f..5e23d8ad 100644 --- a/.github/workflows/publish-release.yml +++ b/.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 diff --git a/Makefile b/Makefile index 280ac6c6..870f1d2d 100644 --- a/Makefile +++ b/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\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 \ diff --git a/README.md b/README.md index 33849682..dfcdc7aa 100644 --- a/README.md +++ b/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) diff --git a/RELEASE.md b/RELEASE.md index 92a25ebc..0e629457 100644 --- a/RELEASE.md +++ b/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. diff --git a/docs/docs/community/contribution.md b/docs/docs/community/contribution.md index a6e8674c..2cd330ac 100644 --- a/docs/docs/community/contribution.md +++ b/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. diff --git a/docs/versioned_docs/version-7.8.x/community/contribution.md b/docs/versioned_docs/version-7.8.x/community/contribution.md index a6e8674c..2cd330ac 100644 --- a/docs/versioned_docs/version-7.8.x/community/contribution.md +++ b/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.