go-faces-http

Face detection HTTP microservice based on dlib. Built with Go and packaged as a statically-linked binary and Docker image.

Quick Start

make deps          # check and install prerequisites
make lint          # run Go and Dockerfile linters
make test          # run tests with coverage
make image-build   # build Docker image
make run           # build and run locally on :8011

Prerequisites

Tool	Version	Purpose
Go	1.26.2+	Language runtime and compiler
Docker	latest	Container image builds
Git	latest	Version control
GNU Make	3.81+	Build orchestration
gvm	latest	Go version management (auto-installed by make deps)
golangci-lint	2.11.4	Go linter (auto-installed by make deps)
hadolint	2.14.0	Dockerfile linter (auto-installed by make lint-dockerfile)
act	0.2.87	Run GitHub Actions locally (optional, auto-installed by make ci-run)

Install all required dependencies:

make deps

Available Make Targets

Run make help to see all available targets.

Build & Run

Target	Description
make build	Build Go binary (requires CGO and dlib)
make run	Build and run the application locally
make clean	Remove build artifacts
make update	Update dependency packages to latest versions
make format	Auto-format Go source files and tidy modules

Code Quality

Target	Description
make lint	Run golangci-lint (includes gocritic via .golangci.yml)
make test	Run tests with coverage and race detection
make lint-dockerfile	Lint the Dockerfile with hadolint

Docker

Target	Description
make image-build	Build Docker image (self-contained, installs deps in container)
make image-run	Run Docker container
make image-stop	Stop Docker container
make image-push	Push Docker image to registry
make image-push-ghcr	Tag and push Docker image to GHCR

CI

Target	Description
make ci	Run full local CI pipeline (requires CGO and dlib for test and build)
make ci-run	Run GitHub Actions workflow locally via act

Utilities

Target	Description
make help	List available tasks
make deps	Check and install required dependencies
make deps-check	Show required tool versions and installation status
make deps-hadolint	Install hadolint for Dockerfile linting
make deps-act	Install act for local CI
make deps-node	Install nvm and Node.js for Renovate
make release	Create and push a new tag
make release-artifacts	Extract binary from Docker image and create release archives
make renovate-bootstrap	Install nvm and npm for Renovate
make renovate-validate	Validate Renovate configuration

Installation

Portable statically-linked binary for Linux AMD64 is available on releases.

wget https://github.com/AndriyKalashnykov/go-faces-http/releases/download/latest/linux_amd64.tar.gz && tar xf linux_amd64.tar.gz && rm linux_amd64.tar.gz
./faces -h

It is also available as a docker image.

docker run --rm -p 8011:80 ghcr.io/andriykalashnykov/go-faces-http:latest

If you want to build the app from source, please follow the instructions on dependency setup.

Usage

./faces -h
Usage of ./faces:
  -listen string
        listen address (default "localhost:8011")

Start server.

./faces
2024/01/15 23:44:22 recognizer init 424.357089ms
2024/01/15 23:44:22 http://localhost:80/docs

Send request.

curl -X 'POST' \
  'http://localhost:8011/image' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'image=@person.jpg;type=image/jpeg'

{
  "elapsedSec": 2.373028184,
  "found": 4,
  "faces": [
    {
      "Rectangle": {
        "Min": { "X": 584, "Y": 1228 },
        "Max": { "X": 1029, "Y": 1673 }
      },
      "Descriptor": [
        -0.122200325,
        0.10511437,
        0.05358115,
        "............. cut here ..........."
      ]
    }
  ]
}

CI/CD

GitHub Actions runs on every push to main, tags v*, and pull requests.

Job	Triggers	Steps
static-check	push, PR, tags, workflow_call	Dockerfile lint
build	after static-check	Docker image build (Go compilation runs inside Docker)
release	tag push (v*)	Build image, push to GHCR, create GitHub release with binary
cleanup	weekly (Sunday) + manual	Delete workflow runs older than 7 days, keep minimum 5

Renovate keeps dependencies up to date with platform automerge enabled.

License

This repo contains models created by Davis King dlib-models, licensed in the public domain or under CC0 1.0 Universal. See LICENSE.

References

• Building a platform-specific executable with Docker Image and uploading to GitHub releases