Dev pydev guide (#149)

* feat: docs for python devs

* chore: typos

* fix: applied PR suggestion

* fix: applied suggestions

* fix: added ref to new doc

---------

Co-authored-by: thomaschiozzi-tndigit <[email protected]>

README-Python-Dev.md

@@ -0,0 +1,76 @@
+# Developing a Python dependency of this project
+
+This document contains a suggested approach on how to develop or modify a Python library that uses the current project Docker as a test or develop environment.
+For example, those instructions can be used to create a developer environment for further development of [eudi-wallet-it-python](https://github.com/italia/eudi-wallet-it-python).
+The instructions below are intended to be a suggestion or a guideline rather than a standard.
+
+## Step 0: Identify which Python dependency requires development
+
+We assume that the developer needs to develop a modified version of the library [eudi-wallet-it-python](https://github.com/italia/eudi-wallet-it-python) which is a dependency of the container `satosa-saml2spid`.
+A local copy of the library is required.
+We assume that the project eudi-wallet-it-python has been cloned in the folder `/home/username/my/development/folder/eudi-wallet-it-python/pyeudiw`. The path prefix `/home/username/my/development/folder/` is an example and should be replaced here with the location of your own development package.
+
+## Step 1: Set environment variable
+
+Set the environment variable `SATOSA_DEBUG=true`. This can be done either in the terminal with the command `export SATOSA_DEBUG=true`, or by updating the file [.env](Docker-compose/.env) by appending the entry `SATOSA_DEBUG=true`.
+
+## Step 2: Update the docker volume by binding the local development directory
+
+In the file [docker-compose.yml](Docker-example/docker-compose.yml), among the volumes of the container `satosa-saml2spid`, add the entry
+
+        volumes:
+            - /home/username/my/development/folder/eudi-wallet-it-python/pyeudiw:/.venv/lib/python3.12/site-packages/pyeudiw:rw
+
+This will replace the installed dependency package with your own local code.
+
+**NOTE:** at the time of writing, container volume is binded to the location `/.venv/lib/python3.12/site-packages`, but your location might be different as it always reference the Python version that is awailable in the container, which in this case is `Python3.12`. Check che actual python version of your container before completing with this step.
+
+## Step 3: Run the container
+
+Launch the script [run-docker-compose.sh](Docker-compose/run-docker-compose.sh). This will launch the docker composition that includes the container `satosa-saml2spid`.
+
+## Step 4 (Optional): Install further dependencies in the container
+
+If your version of the library contains further dependencies, or if you want to install development only dependencies such as, say [pdbpp](https://github.com/pdbpp/pdbpp), you can create a new image that contains the required dependency or execute a terminal (such as a `bash`) within the container and install it manually, therefore commit the changes to the docker container, as shown in the next section.
+Two different options are presented, based on your preferences or requirements.
+
+### Option 4.1: Add the dependency to an existing container
+
+The following steps instructs on how to install a new pip dependency to an existing container. We will assume that the container has name `satosa-saml2spid`.
+
+1. Enter in the container environment with `docker exec -it satosa-saml2spid bash`. Note that to perform the `docker exec` command, the container MUST be running.
+2. Execute the following commands to install you own dependencies; replace `new_package_name` with the new dependency
+
+        source /.venv/bin/activate
+        pip3 install new_package_name
+
+3. Exit from the container area with Docker escape control sequence, that is, `Ctrl+P` followed by `Ctrl+Q`.
+4. Freeze the changes with the command `docker container commit satosa-saml2spid`.
+5. Stop and then restart the container.
+
+At the end of the procedure, you will find the required dependency as part of your container.
+
+### Options 4.2: Create a new image Dockerfile
+
+The following steps instruct on how to create a new image with the new required python dependency. This new image will be the base of the updated container.
+
+1. Stop the container `satosa-saml2spid` with the command `docker stop satosa-saml2spid`.
+2. Create a new folder.
+3. Inside the new folder, create a Dockerfile with the following content, replacing `new_package_name` with the target package:
+
+        FROM ghcr.io/italia/satosa-saml2spid:latest
+        RUN source /.venv/bin/activate && pip3 install new_package_name
+
+4. Build the new image: `docker build . -t satosa-saml2spid`.
+5. Modify docker-compose.yml to replace the old image reference with `satosa-saml2spid`.
+6. Re-run `docker compose up`.
+
+**NOTE:** if the image is already built locally, you can simply update the existing Dockerfile instead of creating a new one from scratch.
+
+## Step 5 (Optional): Insert a breakpoint to check that your setting is working as intended
+
+1. Stop the container `docker stop satosa-saml2spid`.
+2. Add the line `breakpoint()` to a file of that package eudi-wallet-it-python that requires investigation.
+3. Start the container `docker start satosa-saml2spid`.
+
+If everything worked as intended, the program execution should stop at the given `breakpoint()`. To further investigate the state of the program at the time it was stopped, you can use the command `docker attach statosa-saml2spid` in a new terminal.

README.md

@@ -133,6 +133,8 @@ https://localhost/saml2/login/?idp=https://localhost/Saml2IDP/metadata&next=/sam
 If you're going to test Satosa-Saml2Spid with spid-sp-test, take a look to
 [.github/workflows/python-app.yml](.github/workflows/python-app.yml).
 
+If you are using this project as a testing tool or playground for [eudi-wallet-it-python](https://github.com/italia/eudi-wallet-it-python) or any other of its Python dependencies, take a look [here](README-Python-Dev.md)
+
 Additional information can be found [here](README-DEV.md).
 
 ### Warnings