instructions for setting up devenv and basic contribution guidelines

Dockerfile

@@ -1,6 +1,6 @@
 # Stage 1: Build step-ca with acme-proxy plugin
 
-FROM golang:1.26.2-trixie AS build
+FROM golang:1.26.5-trixie AS build
 
 WORKDIR /build
 

Makefile

@@ -55,3 +55,9 @@ build: clean check-deps
 	mkdir db
 	go build -ldflags="-s -w -X main.Version=$(VERSION) -X 'main.BuildTime=$(BUILD_TIME)'" -v -o $(APP_NAME) .
 	@echo "✔ OK"
+
+debug: clean check-deps
+	mkdir db
+	go build \
+	-ldflags="-X main.Version=$(VERSION) -X 'main.BuildTime=$(BUILD_TIME)'" \
+	-gcflags="all=-N -l" -o $(APP_NAME) .

contrib/contribute.md

@@ -0,0 +1,22 @@
+# Contribution Guidelines
+
+We welcome all contributions but we ask you to do the following _before_ submitting a pull request:
+
+- If it’s a **new feature request**, please open an issue with details about your proposed feature, what you want changed and why. What use cases would this feature solve and how will it benefit the community?
+
+- For any **bug fixes**, please check if there are already open or closed issues about the topic and verify that you are testing with the latest version of acme-proxy.
+
+- If you are **updating docs, improving tests**, please proceed directly to MR.
+
+1. Fork the repo
+2. In your fork, create a new branch for your work
+3. Add code/fix in this branch, write tests, update the docs as necessary
+4. Commit & push changes to your forked repo
+5. Submit a pull request targeting our main branch
+
+## Setup Development Environment
+
+1. Install `go >= 1.25`
+2. Install [pre-commit](https://pre-commit.com)
+3. Clone the repo using `git clone --recurse-submodules git@github.com:esnet/acme-proxy.git`
+4. Run `make dev`

develop/externalcas.md → contrib/develop/externalcas.md

@@ -1,6 +1,6 @@
 # ACME server as Registration Authority
 
-See [upstream docs](#upstream-docs) section for more background on what registration authority, CAS are and how those concepts fits into step-ca architecture.
+See [Breadcrumbs](#Breadcrumbs) for more background on what registration authority, CAS are and how those concepts fits into step-ca architecture.
 
 ## Certificate Authority Service (CAS)
 
@@ -18,7 +18,7 @@ type CertificateAuthorityService interface {
 }
 ```
 
-The go package also defines a special type called `ExternalCAS` for this exact purpose. Which is why our [ca.json](../ca.json) file defines an authority of `type: externalcas`.
+The go package also defines a special type called `ExternalCAS` for this exact purpose. Which is why our [ca.json](../../ca.json) file defines an authority of `type: externalcas`.
 
 ```go
 const (
@@ -37,12 +37,12 @@ const (
 )
 ```
 
-## Upstream docs
+## Breadcrumbs
 
-**Step CA github repo**
-<https://github.com/smallstep/certificates/tree/master>
+**step-ca github repo**
+<https://github.com/smallstep/certificates>
 
-**Step CA Registration Authority (RA)**
+**Step CA Registration Authority (RA) mode**
 <https://smallstep.com/docs/step-ca/registration-authority-ra-mode/>
 
 **RA related github discussions**

develop/maintenance.md → contrib/develop/maintenance.md

@@ -1,10 +1,12 @@
-# Guide to patching upstream related changes
+# Guide to patching upstream related bugs
 
-- While smallstep/certifiates is meant to serve as the upstream Go module for acme-proxy, we have to maintain some patches/fixes ourselves until they get merged upstream. Our patched version of step-ca is currently maintained in a forked repo [esnet/certificates](https://github.com/esnet/certificates).
+acme-proxy uses smallstep/certificates as an upstream dependency but just like any other software `smallstep/certifiates` can have bugs too. We have identified a couple of issues which imapct us and have even submitted merge requests but are waiting action from upstream maintainers.
+
+Until then we will have to maintain some patches/fixes ourselves until they get merged upstream. Our patched version of step-ca is currently maintained in a forked repo [esnet/certificates](https://github.com/esnet/certificates).
 
 - The branch naming scheme for our patches follow a pattern `patch/upstream-version`. For example: patches made against smallstep/certificates `v0.30.2` are in a branch called `patch/v0.30.2`.
 
-- Once the patches have been applied and tested, we tag the commit using a naming scheme `[upstream version]-patch.count`. So if the patches have been applied against upstream `v0.30.2` our go.mod in acme-proxy should contain
+- Once the patches have been applied and tested, we tag the commit using a naming scheme `[upstream version]-patch.count`. So if the patches have been applied against upstream `v0.30.2` our go.mod in acme-proxy should contain the following directive
 
 ```
 replace github.com/smallstep/certificates => github.com/esnet/certificates v0.30.2-patch.2

contrib/develop/test-infra.md

@@ -0,0 +1,28 @@
+# Test Infrstructure using Docker containers
+
+1. Build the container image from project root and start the server
+
+```sh
+git clone --recurse-submodules git@github.com:esnet/acme-proxy.git
+docker build -t acme-proxy:latest .
+```
+
+2. If you are running Docker on a Linux host then run the following commands. If on MacOS, jump to 3.
+
+```sh
+mkdir -p /opt/acme-proxy/db
+touch /opt/acme-proxy/ca.json
+chown -R 65532:65532 /opt/acme-proxy
+```
+
+3. Start the container with appropriate mounts
+
+```sh
+docker run -d \
+  --name acme-proxy-test \
+  -p 8443:443 \
+  -v "$(pwd)"/ca.json:/opt/acme-proxy/ca.json:ro \
+  -v "$(pwd)"/db:/opt/acme-proxy/db \
+  --restart unless-stopped \
+  acme-proxy:latest
+```

develop/scripts/uninstall.sh → contrib/scripts/uninstall.sh

@@ -1,4 +1,7 @@
 #!/bin/sh
+#
+# Uninstalls acme-proxy and related configuration files on a linux host for a clean start
+#
 set -e
 
 INSTALL_DIR="${INSTALL_DIR:-/opt/acme-proxy}"