docs: Improve development environment docs

CONTRIBUTING.md

@@ -10,12 +10,12 @@ Your commits must meet the following criteria
 
 - It is signed. To learn how, check [this guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
 - It includes a `--sign-off` stanza. By doing this you state that you can certify [Developer Certificate of Origin](https://developercertificate.org).
-- Its message tries to follow the Conventional Commits [guidelines](https://www.conventionalcommits.org/en/v1.0.0/>).
+- Its message tries to follow the Conventional Commits [guidelines](https://www.conventionalcommits.org/en/v1.0.0).
 
 A commit then would look like
 
 ```
-git commit -S -s -m "<your commit message that follows https://www.conventionalcommits.org/en/v1.0.0/>"
+git commit -S -s -m "<your commit message that follows https://www.conventionalcommits.org/en/v1.0.0"
 ```
 
 ## Code Reviews

app/cli/Makefile

@@ -1,38 +1,15 @@
 VERSION=$(shell git describe --tags --always)
 
-.PHONY: init
-# init env
-init:
-	go install github.com/spf13/cobra-cli@latest
-
-# If the first argument is "run"...
-ifeq (run,$(firstword $(MAKECMDGOALS)))
-  # use the rest as arguments for "run"
-  RUN_ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
-  # ...and turn them into do-nothing targets
-  $(eval $(RUN_ARGS):;@:)
-endif
-
 .PHONY: api
 # generate api proto
 api:
 	cd ./api && buf generate
 
-.PHONY: run
-# run
-run:
-	go run main.go --insecure --control-plane localhost:9000 --artifact-cas localhost:9001 $(RUN_ARGS)
-
 .PHONY: build
 # build
 build:
 	mkdir -p bin/ && go build -ldflags "-X github.com/chainloop-dev/chainloop/app/cli/cmd.Version=$(VERSION)" -o ./bin/chainloop ./main.go
 
-.PHONY: all
-# generate all
-all:
-	make build;
-
 .PHONY: test
 # test
 test:

app/controlplane/Makefile

@@ -16,7 +16,7 @@ build:
 	mkdir -p bin/ && go build -ldflags\
 	  "-X github.com/chainloop-dev/chainloop/app/controlplane/internal/server.Version=$(VERSION)\
 	  -X main.Version=$(VERSION)"\
-	   -o ./bin/control-plane ./cmd/...
+	  -o ./bin/control-plane ./cmd/...
 
 .PHONY: run
 # run

devel/README.md

@@ -1,46 +1,69 @@
 ## Local development
 
-### Pre-requisites
+For development, Chainloop components (Control Plane, Artifact CAS and CLI) come pre-configured to talk to a set of auxiliary services (Dex, PostgresSQL and Vault) that can be run using [Docker Compose](https://docs.docker.com/compose/), so you can start contributing in no time! :)
 
-To run Chainloop core components locally you need
+![development environment](../docs/img/dev-env-overview.png)
+
+### 1 - Prerequisites
+
+To get up and running you'll need
 
 - Golang 1.20+ toolchain
-- `make`
+- [Docker Compose](https://docs.docker.com/compose/)
+- `make` (optional)
+
+### 2 - Run pre-required/auxiliary services
 
-In addition to those, you'll need:
+Chainloop requires some configuration to be in place such as
 
-- PostgreSQL 14
-- Access to a credentials manager. Currently Hashicorp Vault and AWS secret manager are supported.
+- PostgreSQL 14 connection from the Control plane
+- Access to a secrets manager. Currently Hashicorp Vault and AWS secret manager are supported.
 - Open ID connect (OIDC) single sign-on credentials.
 
-Luckily, these can be easily run by leveraging the provided docker compose that can be found in the `devel` directory.
+Luckily, you can leverage the provided docker compose file that can be found in the `devel` directory to do all the setup for you.
 
 ```
 cd devel
 docker compose up
 ```
 
-### Chainloop Components
+### 3 - Run Chainloop server-side components
 
-Once you have the pre-required service up and running, you should be able to run the different Chainloop components, in our case we have three.
+Once you have the pre-required services up and running, you should be able to run the different Chainloop server-side components, in our case we have:
 
 - The Control Plane (`app/controlplane`)
 - The Artifact Content Addressable Storage (CAS) Proxy (`app/artifact-cas`)
-- The Command line interface (CLI) that is used for both a) operate on the control plane and b) run the attestation process on your CI/CD (`app/cli`)
 
-These three components are built in Golang and have a `Makefile` and a `make run` target for convenience.
+These components are built using [Go](https://go.dev/), have a `Makefile` and a `make run` target for convenience.
+
+- run controlplane `make -C app/controlplane run`
+- run CAS `make -C app/cas run`
+
+### 4 - Using the CLI pointing to the local environment
+
+The Command line interface (CLI) is used for both a) operate on the control plane and b) run the attestation process on your CI/CD.
 
-i.e `make -C app/controlplane run`
+You can run it by executing `go run app/cli/main.go`
 
-### Logging in the control-plane
+3.1 - Configure the CLI to point to the local control plane and CAS services.
 
-Once you have the Controlplane and the Artifact API running, you can get started by authenticating using the CLI
+```
+go run app/cli/main.go config save --insecure --control-plane localhost:9000 --artifact-cas localhost:9001
+```
+
+3.2 - Logging in the control-plane
+
+You should now be ready to authenticate the CLI
+
+> NOTE: In development a `--insecure` flag must be provided to talk to the local APIs
 
 ```
-make -C app/cli -- auth login
+go run --insecure app/cli/main.go auth login
 ```
 
 You will get redirected to the pre-configured local OIDC provider (DEX) where there are two configured users
 
 - `sarah@chainloop.local`/`password`
 - `john@chainloop.local`/`password`
+
+Once logged in, you are ready to follow our [Getting Started guide](https://docs.chainloop.dev/getting-started/setup)