diff --git a/Dockerfile b/Dockerfile index 7ce9405..e7213a0 100644 --- a/Dockerfile +++ b/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 diff --git a/Makefile b/Makefile index 4720e94..ff3a55a 100644 --- a/Makefile +++ b/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) . diff --git a/contrib/contribute.md b/contrib/contribute.md new file mode 100644 index 0000000..6341eef --- /dev/null +++ b/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` diff --git a/develop/externalcas.md b/contrib/develop/externalcas.md similarity index 83% rename from develop/externalcas.md rename to contrib/develop/externalcas.md index abc9f12..6167120 100644 --- a/develop/externalcas.md +++ b/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** - +**step-ca github repo** + -**Step CA Registration Authority (RA)** +**Step CA Registration Authority (RA) mode** **RA related github discussions** diff --git a/develop/maintenance.md b/contrib/develop/maintenance.md similarity index 66% rename from develop/maintenance.md rename to contrib/develop/maintenance.md index 47f9440..55d21ad 100644 --- a/develop/maintenance.md +++ b/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 diff --git a/contrib/develop/test-infra.md b/contrib/develop/test-infra.md new file mode 100644 index 0000000..347e16f --- /dev/null +++ b/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 +``` diff --git a/develop/scripts/uninstall.sh b/contrib/scripts/uninstall.sh similarity index 92% rename from develop/scripts/uninstall.sh rename to contrib/scripts/uninstall.sh index f63c1c2..1e957bd 100644 --- a/develop/scripts/uninstall.sh +++ b/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}" diff --git a/develop/contribute.md b/develop/contribute.md deleted file mode 100644 index 74bd35f..0000000 --- a/develop/contribute.md +++ /dev/null @@ -1,13 +0,0 @@ -# Setup development environment - -1. Install `go >= 1.25` -2. Install `pre-commit` -3. Clone the repo -4. Run `make dev` - -## Contribute - -1. Fork the repo -2. In your fork, create a new branch for your work -3. Add changes in your branch, Commit & push changes to your forked repo -4. Submit a pull request