Add build instructions (#163)

* add build instructions

---------

Co-authored-by: Ethan Heilman <ethan.r.heilman@gmail.com>

Author: markafarrell

.gitignore

@@ -34,3 +34,7 @@ dist/
 
 # Created by integration tests
 test/integration/testfile.txt
+
+# Go build cache
+.cache
+.mod-cache

CONTRIBUTING.md

@@ -1,18 +1,20 @@
-# Contributing to OpenPubkey
+# Contributing to OPKSSH
 
 Welcome to OpenPubkey SSH! We are so excited you are here. Thank you for your interest in contributing your time and expertise to the project. The following document details contribution guidelines.
 
-# Getting Started
+OPKSSH is part of [the OpenPubkey project.](https://github.com/openpubkey/openpubkey/blob/main/CONTRIBUTING.md)
+
+## Getting Started
 
 Whether you're addressing an open issue (or filing a new one), fixing a typo in our documentation, adding to core capabilities of the project, or introducing a new use case, anyone from the community is welcome here at OpenPubkey.
 
-## Include Licensing at the Top of Each File
+### Include Licensing at the Top of Each File
 
 At the top of each file in your commit, please ensure the following is captured in a comment:
 
 ` SPDX-License-Identifier: Apache-2.0 `
 
-## Sign Off on Your Commits
+### Sign Off on Your Commits
 
 Contributors are required to sign off on their commits. A sign off certifies that you wrote the associated change or have permission to submit it as an open-source patch. All submissions are bound by the [Developer's Certificate of Origin 1.1](https://developercertificate.org/) and [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
 
@@ -50,7 +52,8 @@ Then, you can create a signed off commit using the flag `-s` or `--signoff`:
 `$ git commit -s -m "This is my signed off commit."`.
 
 To verify that your commit was signed off, check your latest log output:
-```
+
+```bash
 $ git log -1
 commit <commit id>
 Author: Jane Doe <jane.doe@example.com>
@@ -61,7 +64,7 @@ Date:   Thurs Nov 9 06:14:13 2023 -0400
     Signed-off-by: Jane Doe <jane.doe@example.com>
 ```
 
-## Pull Request (PR) Process
+### Pull Request (PR) Process
 
 OpenPubkey is managed from the `main` branch. To ensure your contribution is reviewed, all pull requests must be made against the `main` branch.
 
@@ -75,17 +78,31 @@ Our automated PR checks verify that:
  2. The code has been formatted correctly, according to `go fmt`.
  3. There are no obvious errors, according to `go vet`.
 
-## Testing OpenPubkey Locally
+## Building and Testing
+
+To build with docker run `./hack/build.sh`
 
-To build OpenPubkey, ensure you have Go version `>= 1.23` installed. To verify which version you have installed, try `go version`.
+To build natively run
 
-To run the [Google example](https://github.com/openpubkey/openpubkey/tree/main/examples/google):
- 1. Navigate to the `examples/google/` directory.
- 2. Execute `go build`
- 3. Execute `./google login` to generate a valid PK token using Google as your OIDC provider.
- 4. Execute `./google sign` to use the PK token generated in (3) to sign a verifiable message.
+```bash
+CGO_ENABLED=false go build -v -o opkssh
 
-## Integration Tests
+chmod u+x opkssh
+```
+
+### Unit Tests
+
+```bash
+go test -v ./...
+```
+
+or
+
+```bash
+./hack/unit-tests.sh
+```
+
+### Integration Tests
 
 To run the integration tests, you need
 [Docker installed](https://docs.docker.com/engine/install/)
@@ -100,8 +117,14 @@ Then run the integration tests with:
 export OS_TYPE="ubuntu"
 go test -tags=integration ./test/integration -timeout=15m -count=1 -v
 ```
+  
+or
 
-## Building and Packaging `opkssh` Locally
+```bash
+./hack/integration-tests.sh
+```
+
+## Packaging `opkssh` Locally
 
 `opkssh` leverages on [GoReleaser](https://goreleaser.com/) to simplify the process of building binaries for all supported systems and architectures, as well as creating distribution packages.
 
@@ -132,21 +155,21 @@ Releasing `opkssh` is a straightforward process. If you have the appropriate rol
 
 Once the draft release is created, review and update it if necessary. If everything looks good, publish the release to make it available to the community.
 
-# Contributing Roles
+## Contributing Roles
 
 Contributors include anyone in the technical community who contributes code, documentation, or other technical artifacts to the OpenPubkey project.
-
 Committers are Contributors who have earned the ability to modify (“commit”) source code, documentation or other technical artifacts in a project’s repository. Note that Committers are still required to submit pull requests.
 
 A Contributor may become a Committer by a majority approval of the existing Committers. A Committer may be removed by a majority approval of the other existing Committers.
 
-# Current Committers
+### Current Committers
 
 The Committers of OpenPubkey are:
+
 1. Ethan Heilman (@EthanHeilman)
 2. Jonny Stoten (@jonnystoten)
 3. Lucie Mugnier (@lgmugnier)
 
-# Copyright
+## Copyright
 
 By contributing to this repository, you agree to license your work under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). Any work contributed where you are not the original author must display a license header with the original author(s) and source.

README.md

@@ -453,6 +453,39 @@ opkssh add root alice@example.com https://authentik.local/application/o/opkssh/
 
 Do not use Confidential/Secret mode **only** client ID is needed.
 
+## Developing
+
+For a complete developers guide see [CONTRIBUTING.md](CONTRIBUTING.md)
+
+### Building
+
+Run:
+
+```bash
+CGO_ENABLED=false go build -v -o opkssh
+chmod u+x opkssh
+```
+
+to build with docker run:
+
+```bash
+./hack/build.sh
+```
+
+### Testing
+
+For unit tests run
+
+```bash
+go test ./...
+```
+
+For integration tests run:
+
+```bash
+./hack/integration-tests.sh
+```
+
 ## More information
 
 We document how to manually install opkssh on a server [here](scripts/installing.md).

hack/build.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+set -eou pipefail
+
+pushd $SCRIPT_DIR/../
+
+GO_VERSION=${GO_VERSION:-"1.24.2"}
+
+mkdir -p .cache
+mkdir -p .mod-cache
+
+docker run --rm \
+    -v "$PWD":/data/ \
+    -w /data \
+    --user=$(id -g):$(id -g) \
+    -v ${PWD}/.cache:/.cache \
+    -v ${PWD}/.mod-cache:/go/pkg/mod \
+    golang:${GO_VERSION}-alpine \
+    go build -v -o opkssh
+
+chmod u+x opkssh
+
+popd

hack/integration-tests.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -eou pipefail
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+pushd $SCRIPT_DIR/../
+
+OS_TYPE=ubuntu go test -tags=integration ./test/integration -timeout=15m -count=1 -parallel=2 -v
+
+popd

hack/unit-tests.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -eou pipefail
+
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+
+pushd $SCRIPT_DIR/../
+
+go test -v ./...
+
+popd