Initial commit

.github/docker-compose-test.yml

@@ -0,0 +1,5 @@
+services:
+  imhost:
+    build: ..
+    ports:
+      - "8080:80"

.github/workflows/docker-test.yml

@@ -0,0 +1,26 @@
+name: Docker Tests
+on:
+    workflow_dispatch:
+    push:
+      branches:
+        - main
+    pull_request:
+
+jobs:
+  docker-test:
+    name: Run tests on latest Go version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - run: |
+          docker pull golang:alpine
+          docker compose -f ./.github/docker-compose-test.yml up --build -d
+
+      - run: |
+          curl -sS http://localhost:8080/ | grep Hello\ from\ host
+
+      - run: |
+          docker compose -f ./.github/docker-compose-test.yml down --remove-orphans
+          docker system prune -af

.github/workflows/golang-ci.yml

@@ -0,0 +1,24 @@
+name: GolangCI
+on:
+    workflow_dispatch:
+    push:
+      branches:
+        - main
+    pull_request:
+
+jobs:
+  golangci-lint:
+    name: Run golangci-lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: 'stable'
+
+      # Linting and static analysis
+      - uses: golangci/golangci-lint-action@v4
+        with:
+          version: latest

.github/workflows/unit-test.yml

@@ -0,0 +1,22 @@
+name: Unit Tests
+on:
+    workflow_dispatch:
+    push:
+      branches:
+        - main
+    pull_request:
+
+jobs:
+  go-test:
+    name: Run tests on latest Go version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: 'stable'
+
+      # Unit tests
+      - run: go test ./...

.golangci.yml

@@ -0,0 +1,27 @@
+run:
+  tests: true
+  build-tags:
+    - golangci
+  allow-parallel-runners: true
+
+output:
+  sort-results: true
+
+linters:
+  enable-all: true
+  disable:
+  # Disable deprecated/abandoned linters
+  - structcheck
+  - scopelint
+  - ifshort
+  - interfacer
+  - maligned
+  - exhaustivestruct
+  - nosnakecase
+  - varcheck
+  - deadcode
+  - golint
+  # Allow global variables
+  - gochecknoglobals
+  # Disable due to use of external linters
+  - depguard

Dockerfile

@@ -0,0 +1,35 @@
+# -----------------------------------------------------------------------------
+#  Build Stage
+# -----------------------------------------------------------------------------
+FROM golang:alpine AS builder
+
+COPY . /go/src/app
+ENV CGO_ENABLED 0
+
+WORKDIR /go/src/app
+
+RUN go mod download && \
+    go mod verify && \
+    go test -v ./...
+
+RUN go build \
+    -ldflags="-s -w -extldflags \"-static\"" \
+    -o /go/bin/imhost \
+    /go/src/app/imhost/main.go
+
+# -----------------------------------------------------------------------------
+#  Main Stage
+# -----------------------------------------------------------------------------
+FROM scratch
+
+COPY --from=builder /go/bin/imhost /usr/bin/imhost
+EXPOSE 80/tcp
+WORKDIR /tmp
+ENTRYPOINT [ "/usr/bin/imhost" ]
+
+HEALTHCHECK \
+    --start-period=15s \
+    --interval=5m \
+    --timeout=15s \
+    --retries=3 \
+    CMD [ "/usr/bin/imhost", "--ping"]

LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

README.md

@@ -0,0 +1,76 @@
+# ImHost
+
+ImHost is a simple Docker image that simply returns the hostname of the container it is running in.
+
+Its aim is to be used for testing and debugging purposes in a Docker orchestration environment. Such as docker-compose, docker-swarm, kubernetes, etc.
+
+## Usage
+
+### Docker
+
+```shellsession
+$ # Build the image
+$ docker build -t imhost https://github.com/KEINOS/imhost.git
+**snip**
+
+$ # Run the container (expose the port 80 to 8080)
+$ docker run --rm -p 8080:80 imhost
+**snip**
+
+$ # Check the hostname (note the hostnames are different)
+$ curl -sS localhost:8080
+Hello from host: f9536b7afae0
+
+$ curl -sS localhost:8080
+Hello from host: 2b63d018a7ee
+```
+
+### docker-compose with scale and round-robin
+
+Here is an example of `docker-compose.yml` that uses `imhost` with `--scale` suppord and `nginx` as a load balancer.
+
+```shellsession
+$ # Run the containers and scale the imhost to 5 instances
+docker compose up --detach --scale imhost=5
+**snip**
+
+$ # Check the hostnames (note the hostnames are different)
+$ curl -sS localhost:8080
+Hello from host: 2c80ea38d91a
+
+$ curl -sS localhost:8080
+Hello from host: 5fec68e38b9b
+
+$ curl -sS localhost:8080
+Hello from host: 353184aa84c0
+```
+
+```yaml
+version: '3'
+
+services:
+  imhost:
+    build:
+      context: https://github.com/KEINOS/imhost.git
+    expose:
+      - "80"
+    restart: unless-stopped
+
+  loadbalancer:
+    image: nginx:latest
+    volumes:
+      - ./nginx/proxy.conf:/etc/nginx/nginx.conf:ro
+    ports:
+      - "8080:80"
+    depends_on:
+      - imhost
+    restart: unless-stopped
+```
+
+- For the full example, see the [example](./_example) directory.
+
+## Status
+
+[![Unit Tests](https://github.com/KEINOS/imhost/actions/workflows/unit-test.yml/badge.svg)](https://github.com/KEINOS/imhost/actions/workflows/unit-test.yml)
+[![GolangCI-Lint Test](https://github.com/KEINOS/imhost/actions/workflows/golang-ci.yml/badge.svg)](https://github.com/KEINOS/imhost/actions/workflows/golang-ci.yml)
+[![Docker Tests](https://github.com/KEINOS/imhost/actions/workflows/docker-test.yml/badge.svg)](https://github.com/KEINOS/imhost/actions/workflows/docker-test.yml)

_example/README.md

@@ -0,0 +1,31 @@
+# Usage
+
+```shell
+# Spawn 5 containers and counts the number of host names that
+# are different.
+./up.sh 5
+```
+
+```shellsessionc
+$ ./up.sh 5
+- docker compose up: starting 5 instances of imhost service.
+[+] Running 6/7
+ ⠼ Network example_default           Created                                                                                                                                                                              2.4s
+ ✔ Container example-imhost-1        Started                                                                                                                                                                              0.8s
+ ✔ Container example-imhost-5        Started                                                                                                                                                                              2.0s
+ ✔ Container example-imhost-3        Started                                                                                                                                                                              1.4s
+ ✔ Container example-imhost-2        Started                                                                                                                                                                              1.7s
+ ✔ Container example-imhost-4        Started                                                                                                                                                                              1.1s
+ ✔ Container example-loadbalancer-1  Started                                                                                                                                                                              2.1s
+- stress test: starting stress test with 5 instances.
+        Searching for 5 hosts.
+        Found 5 hosts .....
+        OK:found all hosts
+        List responses:
+          #01: "Hello from host: 9630feeaa63c"
+          #02: "Hello from host: bc03ae785b34"
+          #03: "Hello from host: f26a9bdb6e4d"
+          #04: "Hello from host: d87ac3a9d07f"
+          #05: "Hello from host: 2b63d018a7ee"
+- docker compose down: done.
+```

_example/docker-compose.yml

@@ -0,0 +1,25 @@
+version: '3'
+
+services:
+  imhost:
+    build:
+      context: https://github.com/KEINOS/imhost.git
+    expose:
+      - "80"
+    restart: unless-stopped
+
+  loadbalancer:
+    image: nginx:latest
+    volumes:
+      - ./nginx/proxy.conf:/etc/nginx/nginx.conf:ro
+    ports:
+      - "8080:80"
+    depends_on:
+      - imhost
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "service", "nginx", "status"]
+      start_period: 15s
+      interval: 5m
+      timeout: 15s
+      retries: 3

_example/nginx/proxy.conf

@@ -0,0 +1,16 @@
+user nginx;
+
+worker_processes auto;
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    server {
+        listen 80;
+        location / {
+            proxy_pass http://imhost:80/;
+        }
+    }
+}