Updated installation procedure

Signed-off-by: jayonthenet <[email protected]>

README.md

@@ -1,52 +1,82 @@
 # Pocket IDP
 
 The material in this repo allows you to create an Internal Developer Platform (IDP) running with the Humanitec Platform Orchestrator in less than 5 minutes.
-The Pocket IDP is based on the ["Five-minute IDP"](https://developer.humanitec.com/introduction/getting-started/the-five-minute-idp/) getting started guide in the Humanitec developer docs. Please refer to that guide for additional usage instructions.
-
-For the pocket IDP you need to prepare a few more things on top of the 5min-IDP flow.
-
-1. Create a local CA and sign a certificate that you can provide
-
-    See [mkcert installation](https://github.com/FiloSottile/mkcert?tab=readme-ov-file#installation)
-    ```shell
-    brew install mkcert 
-    mkcert -install
-    mkcert 5min-idp 5min-idp-control-plane kubernetes.docker.internal localhost 127.0.0.1 ::1
-    ```
-
-2. Populate environment variables
-
-    See [direnv installation](https://direnv.net/#basic-installation)
-
-    ```shell
-    brew install direnv
-    HUMANITEC_ORG="" #set me
-	HUMANITEC_SERVICE_USER="" #set token 
-	TLS_CA_CERT="" #Export CA in PEM format and set here
-	TLS_CERT_STRING="" #Your cert in base64 encoded format
-	TLS_KEY_STRING="" #Your key in base64 encoded format
-    humctl login
-    direnv allow
-    ```
-
-3. Run the PocketIDP
-
-    ```shell
-    #For the prebuilt container
-    docker run --rm -it -h pocketidp --name 5min-idp \
-        -e HUMANITEC_ORG \
-        -e HUMANITEC_SERVICE_USER \
-        -e TLS_CA_CERT \
-        -e TLS_CERT_STRING \
-        -e TLS_KEY_STRING \
-        -v hum-5min-idp:/state \
-        -v $HOME/.humctl:/root/.humctl \
-        -v /var/run/docker.sock:/var/run/docker.sock \
-        --network bridge \
-        ghcr.io/internaldeveloperplatform/pocketidp:latest
-    
-    #For the non-prebuilt container
-    gh repo clone InternalDeveloperPlatform/PocketIDP
-    cd PocketIDP
-    make run-local
-    ```
+The Pocket IDP is based on the ["Five-minute IDP"](https://developer.humanitec.com/introduction/getting-started/the-five-minute-idp/) getting started guide in the Humanitec developer docs.
+
+However, it has expanded its capabilities to demonstrate end-to-end platform-based flows. Because of that, it can be used to experience how modern platform-building patterns behave in reality without any strings or cloud costs attached.
+
+If you choose to extend your experience beyond the capabilities of a local-machine-solution, for example, to collaborate with others on the same instance, you can simply upgrade to a cloud-based reference-architecture, which are available as OSS Terraform based packages here: [Humanitec Architecture (github.com)](https://github.com/humanitec-architecture/).
+
+## Pre-requisites
+
+- The [humctl](https://developer.humanitec.com/platform-orchestrator/cli/) CLI
+- Docker (or an equivalent)
+- A Humanitec Organization. If you do not have one yet, [sign up here](https://humanitec.com/free-trial) for a free trial.
+- A user account with the [Administrator](https://developer.humanitec.com/platform-orchestrator/security/rbac/#organization-level-roles) role in that Organization
+- mkcert → [mkcert installation](https://github.com/FiloSottile/mkcert?tab=readme-ov-file#installation)
+- direnv → [direnv installation](https://direnv.net/#basic-installation)
+
+## Installation
+
+1. Create a local CA and sign a certificate that you can provide to the PocketIDP
+
+   ```shell
+   mkcert -install
+   mkcert 5min-idp 5min-idp-control-plane kubernetes.docker.internal localhost 127.0.0.1 ::1
+   ```
+
+   Be sure to note the path and filenames of the generated certificates as you need them for step 3!
+
+2. Login with humctl to create the token that will be picked up by direnv in the next step
+
+   ```shell
+   humctl login
+   ```
+
+   Now follow [this guide](https://developer.humanitec.com/platform-orchestrator/security/service-users/) to create a more permanent service user token that will allow usage of your PocketIDP beyond 24h. You will need it as well in the next step.
+
+3. Populate environment variables
+
+   First, you want to create a `.envrc` file with the following contents - it will be run by direnv every time you change into this directory, so it might be a good idea to have your own directory for the PocketIDP.
+
+   ```shell
+   token=$(yq -r '.token' ~/.humctl)
+   export HUMANITEC_TOKEN=$token
+   export HUMANITEC_ORG="" #set me to your Humanitec org
+   export HUMANITEC_SERVICE_USER="" #set permanent token from step 2
+   export TLS_CA_CERT="" #Export CA in PEM format and set here
+   export TLS_CERT_STRING="" #Your cert in base64 encoded format
+   export TLS_KEY_STRING="" #Your key in base64 encoded format
+   ```
+
+   and allow direnv to work with this file by executing
+
+   ```shell
+   direnv allow
+   ```
+
+## Run the PocketIDP
+
+### For the prebuilt container
+
+```shell
+docker run --rm -it -h pocketidp --name 5min-idp \
+    -e HUMANITEC_ORG \
+    -e HUMANITEC_SERVICE_USER \
+    -e TLS_CA_CERT \
+    -e TLS_CERT_STRING \
+    -e TLS_KEY_STRING \
+    -v hum-5min-idp:/state \
+    -v $HOME/.humctl:/root/.humctl \
+    -v /var/run/docker.sock:/var/run/docker.sock \
+    --network bridge \
+    ghcr.io/internaldeveloperplatform/pocketidp:latest
+```
+
+### For the non-prebuilt container
+
+```shell
+gh repo clone InternalDeveloperPlatform/PocketIDP
+cd PocketIDP
+make run-local
+```