Improve getting started documentation in Readme

[jrschumacher]

Feedback came in from the community regarding the documentation in the Readme.

I'm on a development effort that elected to switch to using OpenTDF for its ABAC needs several months ago. I've been using OpenTDF just long enough to start getting comfortable with it, though recently discovered the massive overhaul to the OpenTDF GitHub repo and it's overall implementation. Similar to the sentiment expressed by Carlos (see above), I was relying heavily on the examples (in particular the secure-remote-storage example) contained in now-deprecated version (and as someone drinking from several firehoses simultaneously, this...sigh...wasn't great timing...)
I suppose I have several questions:
(1) Is there anyway I could communicate with someone familiar with the older examples? The sunk cost and technical debt I'm running into is a beast. Would be very appreciative of any one willing to engage. 🙂
(2) I'm working in parallel trying to understand the new OpenTDF implementation. I've already setup the dependencies (thankfully, a much easier process than your previous quick start guide!), but I'm confused about what/why is going on with the steps in the "Run" section after docker-compose up.
There are instructions for creating an OpenTDF config file, though I see several examples exist. I presume I can leave for now? Or, are there modifications one needs to make out-of-the-gate?
Step 3 is giving me a headache:
"go run github.com/opentdf/platform/service provision keycloak" doesn't make sense to me. I don't know what the intention of this step is.
Firstly — and my preemptive apologies for having just enough knowledge of Golang to be super dangerous — does it make sense for a go run command to have a URL as an argument?
Secondly, I see where there is a file contained in platform/service/cmd called "provisionKeycloak.go". Is this actually the intended file that needs to be run here?
Is there anyway these steps could be better explained? I don't have a good idea what/why I'm doing what I'm doing, or how for that matter. IMHO, these instructions leave a lot to the imagination generally, but also seem to rely on quite a bit of expertise with the dependencies.
(3) Do you plan on adding more examples/documentation thereof anytime soon? I see the OpenTDF Platform Examples for Attribute Service and Authorization Service...but again, it seems like a lot of "exercises left to the reader".
(4) Although the implementation has obviously changed a lot, I presume the OpenTDF spec has not changed. Would someone be able to verify that this is the case?
Thanks in advance. I'm really excited about the possibilities of OpenTDF, but really struggling to get up and running. Any feedback is greatly appreciated

Acceptance Criteria

• interpret feedback and improve readme

[cakeholeDC]

Some additional questions related to getting started documentation:

I have followed steps 1-4 in the README under “Running the Platform Locally” here: https://github.com/opentdf/platform?tab=readme-ov-file#running-the-platform-locally

How do I validate that the platform is stood up properly?

Are there HTTP endpoints that should successfully return data with curl?

I expected that maybe http://localhost:8080/.well-known/opentdf-configuration could work, but it does not seem to be accessible.

$ curl -v http://localhost:8080/.well-known/opentdf-configuration
*   Trying [::1]:8080...
* connect to ::1 port 8080 failed: Connection refused
*   Trying 127.0.0.1:8080...
* connect to 127.0.0.1 port 8080 failed: Connection refused
* Failed to connect to localhost port 8080 after 0 ms: Couldn't connect to server
* Closing connection
curl: (7) Failed to connect to localhost port 8080 after 0 ms: Couldn't connect to server

Trying the same with port 8888 (keycloak) returns a 404.

$ curl -v http://localhost:8888/.well-known/opentdf-configuration
*   Trying [::1]:8888...
* Connected to localhost (::1) port 8888
> GET /.well-known/opentdf-configuration HTTP/1.1
> Host: localhost:8888
> User-Agent: curl/8.4.0
> Accept: */*
> 
< HTTP/1.1 404 Not Found
< content-type: text/html; charset=utf-8
< content-length: 53
< 
* Connection #0 to host localhost left intact
<html><body><h1>Resource not found</h1></body></html>