diff --git a/README-Python-Dev.md b/README-Python-Dev.md new file mode 100644 index 00000000..3e5f8ec8 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 14b30dfd..b800893f 100644 --- a/README.md +++ b/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