Merge pull request #94 from Teamwork/docker

Docker build, switch to GHA

.editorconfig

@@ -12,5 +12,5 @@ trim_trailing_whitespace = true
 [*.{go,sh}]
 indent_style = tab
 
-[*.yaml]
+[*.{yaml,yml}]
 indent_size = 2

.github/workflows/go.yml

@@ -0,0 +1,88 @@
+name: Go
+on: [push]
+jobs:
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Lint
+        uses: golangci/golangci-lint-action@v3
+        with:
+          only-new-issues: true
+
+
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+
+    - uses: actions/setup-go@v5
+      with:
+        go-version: "1.20"
+
+    - uses: actions/checkout@v4
+      with:
+        path: gopath/src/github.com/teamwork/kommentaar
+
+    - name: Test & coverage
+      env:
+        GO111MODULE: "off"
+        GOPATH: ${{ github.workspace }}/gopath
+      run: |
+        cd $GOPATH/src/github.com/teamwork/kommentaar
+
+        go test -coverprofile=full_coverage -race ./...
+
+    - name: Upload coverage
+      env:
+        COVERALLS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        GOPATH: ${{ github.workspace }}/gopath
+      run: |
+        export PATH="$GOPATH/bin:$PATH"
+        go install github.com/mattn/goveralls@latest
+        cd $GOPATH/src/github.com/teamwork/kommentaar
+        goveralls -coverprofile=full_coverage -service=github
+
+
+
+  build:
+    name: Build and push image
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    if: startsWith(github.event.ref, 'refs/tags/v')
+    env:
+      REGISTRY: ghcr.io
+      IMAGE_NAME: ${{ github.repository }}
+    steps:
+
+    - uses: actions/checkout@v4
+    - uses: docker/setup-qemu-action@v3
+    - uses: docker/setup-buildx-action@v3
+
+    - name: Log in to Docker Hub
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Extract metadata (tags, labels) for Docker
+      id: meta
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+
+    - name: Build and push Docker image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        platforms: linux/amd64,linux/arm64
+        file: ./Dockerfile
+        push: true
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+

.gitignore

@@ -2,3 +2,5 @@
 /coverage.html
 .DS_Store
 .idea
+*.coverage
+*_coverage

Dockerfile

@@ -0,0 +1,10 @@
+FROM golang:1.20-alpine
+
+VOLUME /code
+VOLUME /config
+VOLUME /output
+
+COPY . /go/src/github.com/teamwork/kommentaar
+COPY config.example /config/kommentaar.conf
+
+CMD ["/go/src/github.com/teamwork/kommentaar/run.sh"]

README.md

@@ -1,6 +1,6 @@
 [![GoDoc](https://godoc.org/github.com/teamwork/kommentaar?status.svg)](https://godoc.org/github.com/teamwork/kommentaar)
-[![Build Status](https://travis-ci.com/Teamwork/kommentaar.svg?branch=master)](https://travis-ci.com/Teamwork/kommentaar)
-[![codecov](https://codecov.io/gh/Teamwork/kommentaar/branch/master/graph/badge.svg)](https://codecov.io/gh/Teamwork/kommentaar)
+![Build Status](https://github.com/teamwork/kommentaar/actions/workflows/go.yml/badge.svg?branch=master)
+[![Coverage Status](https://coveralls.io/repos/github/Teamwork/kommentaar/badge.svg?branch=master)](https://coveralls.io/github/Teamwork/kommentaar)
 
 Kommentaar generates documentation for Go APIs.
 
@@ -47,6 +47,27 @@ See `kommentaar -h` for the full list of options.
 You can also the [Go API](https://godoc.org/github.com/teamwork/kommentaar), for
 example to serve documentation in an HTTP endpoint.
 
+### Usage with Docker
+
+
+There is a kommentaar Docker image available at `ghcr.io/teamwork/kommentaar` which in some cases may simplify the setup process.
+It takes in the following parameters:
+
+- `MODULE_PATH` env var (required) - path to your module, e.g. `github.com/teamwork/amazingapp`
+- `EXEC_PATH` env var (optional) - path passed to kommentaar - can be relative or absolute, e.g. `./api/v3/...`, or `/go/src/github.com/teamwork/amazingapp/api/v3/...`. Default value is `/go/src/$MODULE_PATH/...`
+- `CONFIG_NAME` env var (optional) - name of kommentaar config file in the `/config` volume (see below). Default value is `kommentaar.conf`
+- `/code` volume (required) - folder containing your go code
+- `/config` volume (optional) - folder containing your kommentaar config file, by default the included `config.example` file is copied there as `kommentaar.conf`
+- `/output` volume (required) - folder where the generated `swagger.yaml` file will be placed.
+
+Usage examples:
+- `docker run --rm -it -e MODULE_PATH="github.com/teamwork/amazingapp" -v .:/code -v .:/config -v .:/output ghcr.io/teamwork/kommentaar`
+  - This assumes you are running the command in `amazingapp` folder
+  - This is roughly equivalent to `kommentaar -config ./kommentaar.conf github.com/teamwork/amazingapp... > ./swagger.yaml`
+- `docker run --rm -it -e MODULE_PATH="github.com/teamwork/amazingapp" -e EXEC_PATH="./api/v3/controller/..." -e CONFIG_NAME=".kommentaar.v3" -v $HOME/dev/amazingapp:/code -v $HOME/dev/amazingapp/config:/config -v %HOME/dev/amazingapp/api/v3:/output ghcr.io/teamwork/kommentaar`
+  - This will run the equivalent of `kommentaar -config $HOME/dev/amazingapp/config/.kommentaar.v3 $GOPATH/src/github.com/teamwork/amazingapp/api/v3/controller/... > $HOME/dev/amazingapp/api/v3/swagger.yaml`
+
+
 Syntax
 ------