Merge pull request #28 from hueristiq/dev

Development v0.8.0

.dockerignore

@@ -0,0 +1,8 @@
+.github
+bin
+.gitignore
+.golangci.yaml
+.goreleaser.yaml
+CONTRIBUTING.md
+LICENSE
+README.md

.github/workflows/build-test.yml

@@ -27,7 +27,7 @@ jobs:
                 name: Set up Go
                 uses: actions/setup-go@v5
                 with:
-                    go-version:  '>=1.21'
+                    go-version:  '>=1.23'
             -
                 name: Checkout the repository
                 uses: actions/checkout@v4

.github/workflows/dockerhub-push.yaml

@@ -0,0 +1,46 @@
+name: 🐋 DockerHub Push
+
+on:
+    workflow_run:
+        workflows: ["🎉 Release"]
+        types:
+            - completed
+    workflow_dispatch:
+
+jobs:
+    push:
+        runs-on: ubuntu-latest-16-cores
+        steps:
+            -
+                name: Checkout
+                uses: actions/checkout@v4
+
+            -
+                name: Get Github tag
+                id: meta
+                run: |
+                    curl --silent "https://api.github.com/repos/hueristiq/xsubfind3r/releases/latest" | jq -r .tag_name | xargs -I {} echo TAG={} >> $GITHUB_OUTPUT
+
+            -
+                name: Set up QEMU
+                uses: docker/setup-qemu-action@v3
+
+            -
+                name: Set up Docker Buildx
+                uses: docker/setup-buildx-action@v3
+
+            -
+                name: Login to DockerHub
+                uses: docker/login-action@v3 
+                with:
+                    username: ${{ secrets.DOCKERHUB_USERNAME }}
+                    password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+            -
+                name: Build and push
+                uses: docker/build-push-action@v6
+                with:
+                    context: .
+                    platforms: linux/amd64,linux/arm64,linux/arm
+                    push: true
+                    tags: hueristiq/xsubfind3r:latest,hueristiq/xsubfind3r:${{ steps.meta.outputs.TAG }}

.github/workflows/lint-test.yml

@@ -27,7 +27,7 @@ jobs:
                 name: Set up Go
                 uses: actions/setup-go@v5
                 with:
-                    go-version:  '>=1.21'
+                    go-version:  '>=1.23'
                     cache: false
             -
                 name: Checkout the repository
@@ -36,7 +36,7 @@ jobs:
                     fetch-depth: 0
             -
                 name: Run golangci-lint
-                uses: golangci/golangci-lint-action@v3
+                uses: golangci/golangci-lint-action@v6
                 with:
                     version: v1.54.2
                     args: --timeout 5m

.github/workflows/release.yml

@@ -16,15 +16,15 @@ jobs:
                 name: Set up Go
                 uses: actions/setup-go@v5
                 with:
-                    go-version:  '>=1.21'
+                    go-version:  '>=1.23'
             -
                 name: Checkout the repository
                 uses: actions/checkout@v4
                 with:
                     fetch-depth: 0
             -
                 name: Run GoReleaser
-                uses: goreleaser/goreleaser-action@v5
+                uses: goreleaser/goreleaser-action@v6
                 with:
                     distribution: goreleaser
                     version: latest

Dockerfile

@@ -0,0 +1,59 @@
+# Use the official Golang image version 1.23 with the Alpine distribution as the base image for the build stage.
+# This multi-stage build starts with the "build-stage" stage where the Go application will be compiled.
+FROM golang:1.23.1-alpine3.20 AS build-stage
+
+# Perform system updates and install necessary packages.
+# - `apk --no-cache update`: Updates the Alpine package repository without caching index files.
+# - `apk --no-cache upgrade`: Upgrades all installed packages to the latest available versions.
+# - `apk --no-cache add`: Installs additional required packages:
+#   - `ca-certificates`: For managing CA certificates for secure communication.
+#   - `curl`: For making HTTP requests (can be used to download files or for health checks).
+#   - `gcc` and `g++`: The GNU Compiler Collection used for compiling C and C++ code, essential for building Go applications.
+#   - `git`: Required for downloading Go modules that reference external repositories.
+#   - `make`: Utility for automating build processes and running the `Makefile`.
+RUN <<EOF
+    apk --no-cache update
+    apk --no-cache upgrade
+    apk --no-cache add ca-certificates curl gcc g++ git make
+EOF
+
+# Set the working directory inside the container to `/xsubfind3r`.
+# All subsequent commands (COPY, RUN, etc.) will operate relative to this directory.
+WORKDIR /xsubfind3r
+
+# Copy the Go module files (`go.mod` and `go.sum`) from the host to the container.
+# This allows Docker to cache the dependency downloads, avoiding repeated downloads unless these files change.
+COPY go.mod go.sum ./
+
+# Download the Go dependencies specified in `go.mod` and `go.sum`.
+# This ensures that the environment has all the required libraries before building the application.
+RUN go mod download
+
+# Copy the entire source code from the host machine to the working directory inside the container.
+# This includes all files from the current directory where the Dockerfile is located into the `/xsubfind3r` directory.
+COPY . .
+
+# Run the `make go-build` command to build the Go application.
+# Assumes a `Makefile` exists in the project root that handles the build process (likely using `go build`).
+RUN make go-build
+
+# Start the second stage of the multi-stage build using the `alpine:3.20.3` image.
+# This stage is designed to produce a much smaller, production-ready image containing only the necessary runtime components.
+FROM alpine:3.20.3
+
+# Perform system updates and install essential runtime packages:
+# - `bind-tools`: Provides DNS lookup utilities like `dig` and `host`.
+# - `ca-certificates`: Includes CA certificates to allow HTTPS connections.
+RUN <<EOF
+    apk --no-cache update
+    apk --no-cache upgrade
+    apk --no-cache add bind-tools ca-certificates
+EOF
+
+# Copy the compiled binary `xsubfind3r` from the `build-stage` stage.
+# The binary is located at `/xsubfind3r/bin/xsubfind3r` in the build environment and is copied to `/usr/local/bin/` in the final image.
+COPY --from=build-stage /xsubfind3r/bin/xsubfind3r /usr/local/bin/
+
+# Set the default command to execute the `xsubfind3r` binary when the container starts.
+# This means that when you run the container, it will automatically start the `xsubfind3r` tool.
+ENTRYPOINT ["xsubfind3r"]

Makefile

@@ -1,50 +1,150 @@
-SHELL = /bin/bash
+# Set the default shell to `/bin/sh` for executing commands in the Makefile.
+SHELL = /bin/sh
 
+# Define the project name for easy reference.
+PROJECT = "xsubfind3r"
+
+# The default target that gets executed when the `make` command is run without arguments.
+# In this case, it will trigger the `go-build` target.
 all: go-build
 
 # --- Go(Golang) ------------------------------------------------------------------------------------
-GOCMD=go
-GOMOD=$(GOCMD) mod
-GOGET=$(GOCMD) get
-GOFMT=$(GOCMD) fmt
-GOTEST=$(GOCMD) test
-GOBUILD=$(GOCMD) build
-GOINSTALL=$(GOCMD) install
-GOFLAGS := -v 
-LDFLAGS := -s -w
 
+# Define common Go commands with variables for reusability and easier updates.
+GOCMD=go # The main Go command.
+GOMOD=$(GOCMD) mod # Go mod command for managing modules.
+GOGET=$(GOCMD) get # Go get command for retrieving packages.
+GOFMT=$(GOCMD) fmt # Go fmt command for formatting Go code.
+GOTEST=$(GOCMD) test # Go test command for running tests.
+GOBUILD=$(GOCMD) build # Go build command for building binaries.
+GOINSTALL=$(GOCMD) install # Go install command for installing packages.
+
+# Define Go build flags for verbosity and linking.
+GOFLAGS := -v # Verbose flag for Go commands to print detailed output.
+LDFLAGS := -s -w # Linker flags to strip debug information (-s) and reduce binary size (-w).
+
+# Set static linking flags for systems that are not macOS (darwin).
+# Static linking allows the binary to include all required libraries in the executable.
 ifneq ($(shell go env GOOS),darwin)
-LDFLAGS := -extldflags "-static"
+	LDFLAGS := -extldflags "-static"
 endif
 
+# Define Golangci-lint command for linting Go code.
 GOLANGCILINTCMD=golangci-lint
 GOLANGCILINTRUN=$(GOLANGCILINTCMD) run
 
+# --- Go Module Management
+
+# Tidy Go modules
+# This target cleans up `go.mod` and `go.sum` files by removing any unused dependencies.
+# Use this command to ensure that the module files are in a clean state.
 .PHONY: go-mod-tidy
 go-mod-tidy:
 	$(GOMOD) tidy
 
+# Update Go modules
+# This target updates the Go module dependencies to their latest versions.
+# It fetches and updates all modules, and any indirect dependencies.
 .PHONY: go-mod-update
 go-mod-update:
-	$(GOGET) -f -t -u ./...
-	$(GOGET) -f -u ./...
+	$(GOGET) -f -t -u ./... # Update test dependencies.
+	$(GOGET) -f -u ./... # Update other dependencies.
 
+# --- Go Code Quality and Testing
+
+# Format Go code
+# This target formats all Go source files according to Go's standard formatting rules using `go fmt`.
 .PHONY: go-fmt
 go-fmt:
 	$(GOFMT) ./...
 
+# Lint Go code
+# This target lints the Go source code to ensure it adheres to best practices.
+# It uses `golangci-lint` to run various static analysis checks on the code.
+# It first runs the `go-fmt` target to ensure the code is properly formatted.
 .PHONY: go-lint
 go-lint: go-fmt
 	$(GOLANGCILINTRUN) $(GOLANGCILINT) ./...
 
+# Run Go tests
+# This target runs all Go tests in the current module.
+# The `GOFLAGS` flag ensures that tests are run with verbose output, providing more detailed information.
 .PHONY: go-test
 go-test:
 	$(GOTEST) $(GOFLAGS) ./...
 
+# --- Go Build and Install
+
+# Build Go program
+# This target compiles the Go source code and generates a binary in the `bin/` directory.
+# The output binary is named after the project (`xsubfind3r`), and the source entry point is the main file in `cmd/$(PROJECT)/main.go`.
+# The `LDFLAGS` flag is passed to optimize the binary size by stripping debug information.
 .PHONY: go-build
 go-build:
-	$(GOBUILD) $(GOFLAGS) -ldflags '$(LDFLAGS)' -o bin/xsubfind3r cmd/xsubfind3r/main.go
+	$(GOBUILD) $(GOFLAGS) -ldflags '$(LDFLAGS)' -o bin/$(PROJECT) cmd/$(PROJECT)/main.go
 
+# Install Go program
+# This target installs the Go program by compiling and placing it in the system's Go bin directory.
+# Use this to make the application globally available on the system.
 .PHONY: go-install
 go-install:
-	$(GOINSTALL) $(GOFLAGS) ./...
+	$(GOINSTALL) $(GOFLAGS) ./...
+
+# --- Docker ------------------------------------------------------------------------------------
+
+# Define common Docker commands with variables for reusability.
+DOCKERCMD = docker # The main Docker command.
+DOCKERBUILD = $(DOCKERCMD) build # Docker build command for building images.
+
+# Define the path to the Dockerfile.
+# The Dockerfile is located in the root directory by default.
+DOCKERFILE := ./Dockerfile
+
+# Define the Docker image name and tag.
+# The image name is based on the project name, and the tag is extracted from the version in the configuration file.
+IMAGE_NAME = hueristiq/$(PROJECT)
+IMAGE_TAG = $(shell cat internal/configuration/configuration.go | grep "VERSION =" | sed 's/.*VERSION = "\([0-9.]*\)".*/\1/')
+IMAGE = $(IMAGE_NAME):$(IMAGE_TAG)
+
+# Build Docker image
+# This target builds the Docker image using the Dockerfile.
+# It tags the image with both the specific version and `latest` for convenience.
+.PHONY: docker-build
+docker-build:
+	@$(DOCKERBUILD) \
+		-f $(DOCKERFILE) \
+		-t $(IMAGE) \
+		-t $(IMAGE_NAME):latest \
+		.
+
+# --- Help -----------------------------------------------------------------------------------------
+
+# Display help information
+# This target prints out a detailed list of all available Makefile commands for ease of use.
+# It's a helpful reference for developers using the Makefile.
+.PHONY: help
+help:
+	@echo ""
+	@echo "*****************************************************************************"
+	@echo ""
+	@echo "PROJECT : $(PROJECT)"
+	@echo ""
+	@echo "*****************************************************************************"
+	@echo ""
+	@echo "Available commands:"
+	@echo ""
+	@echo " Go Commands:"
+	@echo "  go-mod-tidy .............. Tidy Go modules."
+	@echo "  go-mod-update ............ Update Go modules."
+	@echo "  go-fmt ................... Format Go code."
+	@echo "  go-lint .................. Lint Go code."
+	@echo "  go-test .................. Run Go tests."
+	@echo "  go-build ................. Build Go program."
+	@echo "  go-install ............... Install Go program."
+	@echo ""
+	@echo " Docker Commands:"
+	@echo "  docker-build ............. Build Docker image."
+	@echo ""
+	@echo " Help Commands:"
+	@echo "  help ..................... Display this help information"
+	@echo ""