docs: installation guide #314
Conversation
|
@tmberthold first you need to sign the ECA, and if you want your PR reviewed, it is advisable to request a review by someone from the team. |
paullatzelsperger
force-pushed
the
main
branch
2 times, most recently
from
dfe0701
to
71f4660
Compare
|
@stefan-ettl @stephanbcbauer as discussed the PR for the Installation Guide with the/my request to review it once or forward it @paullatzelsperger your review would also be welcome |
|
@tmberthold I'm happy to do it, but explicitly requesting reviews from committers is a good idea for several reasons:
I've added @stefan-ettl and @stephanbcbauer and myself as reviewers. I will merge as soon as either of them approves the PR. If you cannot request reviews, you likely need to be added as a contributor. |
paullatzelsperger
requested review from
stefan-ettl,
stephanbcbauer and
paullatzelsperger
That is exactly what is true, but thank you for the review request. |
|
Hello, I realize this PR is still under review so sorry if I'm jumping ahead at this stage. I am trying to run a tractus-edc connector setup locally and it's not very clear what instructions to follow. Thanks @tmberthold for taking the initiative to raise the PR. It would be great to clarify how this overlaps with the existing info that exists in various other README docs scattered throughout the repo. ex. Probably consolidating the docs into a common wiki may be a nice to have for someone just getting started using this project without assuming a lot of prior knowledge about EDC/IDS internals. Hopefully this makes it an easier path to adoption. Thank you! |
stephanbcbauer
added
the
documentation
Hey, Hey. We definitely need a step-by-step guide to setup/install the EDC... that's why this PR was created. And yes, we absolutely have to consolidate the different files and manuals. We are on it. But if you want, you could also try the new installation guide. Would be a nice test if it works ;) Thanks for jumping in |
|
@icysharp may be just a different view, but it's easier to read… here is the link to the connector kit https://eclipse-tractusx.github.io/docs/kits/tractusx-edc/docs/kit/operation-view/page00_operation_view The documentation is basically the same as we have in our repository, but it's structured and filtered… feedback is welcome ;) |
|
@stefan-ettl you mentioned a specific tester for this guide? Was he already able to test it? At least for me ... this would be a "qgate" before we merge this PR? |
Sure, so I gave it a try ignoring the docs besides the ones referenced in the PR doc. I got the PostgreSQL and Hashicorp Vault charts installed successfully. Further on I have some initial questions related to the connector configuration. I think these values could be elaborated in some more detail -
Again I'm approaching this assuming no prior understanding of the EDC/IDS internals so pardon my ignorance. If there are other docs that are essential reading before trying out the connector would be good to include links to them. I can give it another try once I have availability in a few days time. Thanks again for the efforts towards better documentation! |
|
thx @icysharp this is exactly the feedback we need to improve our documentation. @tmberthold can you take over? |
|
Kudos, SonarCloud Quality Gate passed!
|
|
Will be updated to the newest version I guess.. |
|
Thanks for the work so far, I am currently working through the guide. |
|
|
||
| Prerequisite | ||
| ------------ | ||
| If you do not have preexisting installations of PostgreSQL or HashiCorp Vault, you will need to configure them first. |
There was a problem hiding this comment.
A more detailed list of prerequsites like in this sample would be great.
You should be able to complete the installation if you have everything listed in the prerequisite, including all used tools and requirements.
| ``` | ||
| You can then roll out the chart using: | ||
| ```bash | ||
| helm upgrade --install $NAME bitnami/postgresql --set auth.enablePostgresUser=false --set auth.database=$DATABASE --set auth.username=$USERNAME --set auth.password=$PASSWORD |
There was a problem hiding this comment.
Please organise overly long commands with \.
That way, they are much more readable.
Example:
helm upgrade \
--install $NAME bitnami/postgresql \
--set auth.enablePostgresUser=false \
--set auth.database=$DATABASE \
--set auth.username=$USERNAME \
--set auth.password=$PASSWORD
| ================== | ||
| This guide describes how to install the [Tractus-X EDC](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector) via helm chart with Hashicorp Vault + PostgreSQL. | ||
|
|
||
| Prerequisite |
There was a problem hiding this comment.
I think it is enough to state that DAPS, Postgres and Hashicorp must be available and accessible beforehand, and access vectors (database name, passwords, tokens, etc.) must be known. This is an installation guide, not a sample, so we can safely assume users have already worked through the sample, and/or have a running environment.
For example, I would only state that "a valid DAPS certificate and client-id must exist" and link to wherever that process is defined.
At most, I would explain configuration that is specific to the connector, such as the use of a static vault token.
This will make the install guide much more succinct and quicker to read.
There was a problem hiding this comment.
Is DAPS a prereq at this point since it is going away? The prereq could be "an identity provider"
| FAQ | ||
| ------------ | ||
| ### How should the DAPS service URL be specified? | ||
| The URL of the DAPS depends on the dataspace you want to connect to. The best thing here is to contact a contact person and ask for the DAPS URL of the dataspace you want to join. The example URL will connect you to the Catena-X Int-Stage DAPS. |
There was a problem hiding this comment.
this is the install guide for one particular dataspace, i.e. Catena-X, so we should list the DAPS's URL
| The client ID results from the SKI and AKI of the connector certificate. Fur further information on certificates of Catena-X, please take a look at the [Catena-X Connector Registration FAQ](https://portal.int.demo.catena-x.net/documentation/?path=docs%2F02.+Technical+Integration%2F01.+Connector+Registration%2F07.+FAQ.md). | ||
|
|
||
| ### It seems like the connector specific properties are all optional? | ||
| Not changing these values does not prevent the connector from starting, but describe the operator of the connector. It therefore makes sense to adapt these values individually to the intended use. |
There was a problem hiding this comment.
i'm sorry, what does this mean? Also, if a value is optional, it should not limit the operation of a piece of software significantly, if it does, it is not optional.
| Not changing these values does not prevent the connector from starting, but describe the operator of the connector. It therefore makes sense to adapt these values individually to the intended use. | ||
|
|
||
| ### What exactly are the following values and where can they be obtained? | ||
| - `controlplane.endpoints.authKey`: An authkey plays an important role in security and access control, helping to prevent unauthorized access and ensure that only trusted actors can access certain services. Please set this value individually to a confidential key. This value will be used later to be allowed to call some ControlPlane endpoints. |
There was a problem hiding this comment.
better: "this value is used as access token for control plane endpoints". people are familiar with basic security concepts.
Is there any reason you are explaining this one in particular, and no others?
| 4. Install the Tractus-X EDC (please replace the angle brackets data with the information from step 1): | ||
| ```bash | ||
| helm repo add tractusx-edc https://eclipse-tractusx.github.io/charts/dev | ||
| helm install edc tractusx-edc/tractusx-connector --version 0.3.3 --set vault.hashicorp.enabled=true --set postgresql.enabled=true --set vault.hashicorp.url=<YOUR URL> --set vault.hashicorp.token=<YOUR TOKEN> --set daps.clientId=<YOUR ID> --set controlplane.endpoints.management.authKey=<YOUR AUTHKEY> --set postgresql.username=<YOUR USERNAME> --set postgresql.password=<YOUR PW> --set postgresql.jdbcUrl=<YOUR JDBC URL> --set backendService.httpProxyTokenReceiverUrl=<YOUR URL> --set daps.url=<YOUR URL> |
There was a problem hiding this comment.
better to collect the values in a dedicated *.yaml file to keep the command easier to type. Or, at the very least, please use shell line breaks
|
@tmberthold you are still working on this, correct? |
|
@stephanbcbauer After a longer break, we have a telco scheduled today for further proceed regarding this guide and the feedback we now got this week/last week. It is a question of time, but yes, we are still working on it. I ask for a little patience, otherwise I will let you know. |
| ================== | ||
| This guide describes how to install the [Tractus-X EDC](https://github.com/eclipse-tractusx/tractusx-edc/tree/main/charts/tractusx-connector) via helm chart with Hashicorp Vault + PostgreSQL. | ||
|
|
||
| Prerequisite |
There was a problem hiding this comment.
Is DAPS a prereq at this point since it is going away? The prereq could be "an identity provider"
| - `internationalDataSpaces.description`: the description of the IDS connector | ||
| - `internationalDataSpaces.title`: the title of the IDS connector | ||
| - `internationalDataSpaces.maintainer`: the maintainer of the IDS connector | ||
| - `internationalDataSpaces.curator`: the curator profile of the IDS connector |
There was a problem hiding this comment.
Are these "internationalDataspaces" configuration values still used because they have no corresponding item in the DSP specifications? These should probably be removed (and "InternationalDataSpaces" no longer used)
|
Closing in favor of new PR with fresh start for v0.5.0. |
Thank you @tmberthold |
WHAT
Attached is a first draft version of an installation guide. If you feel something is missing or could be done differently, we appreciate every feedback.
FURTHER NOTES
Closes #275