This repository has been archived on 2024-05-31. You can view files and clone it, but cannot push or open issues or pull requests.
idhub-docker/README.md

132 lines
8.1 KiB
Markdown
Raw Permalink Normal View History

# Docker deployment of IdHub and tools
## About the pilots and instances that this repository deploys
### Pilots
- **XO9B**:
- Instances:
- https://idhub1-xo9b.demo.pangea.org
- https://idhub2-xo9b.demo.pangea.org
2024-04-04 05:25:38 +00:00
- Motivation: Support an accreditation program for vulnerable people, exploring the value of using verifiable credentials to get services/benefits.
- Scenario: A vulnerable family obtains a benefit (internet connection fee discount) by presenting a verifiable credential to a connectivity provider entity.
Actors-> **XO9B**: IdHub1 (acting as a user wallet for families holding credentials issued by a social support organisation), **Connectivity provider entity**: Demo portal, IdHub2 (acting as verifier). The verifier portal incorporates verification capabalities and support to establish an OIDC4VP dialog with the user wallet for credential presentation (accreditation).
- **Setem**:
- Instances:
- https://idhub1-setem.demo.pangea.org
- https://idhub2-setem.demo.pangea.org
- Motivation: Since SETEM is a federation, members of one of the federated entities (Setem BCN) can accredit their membership to other federation members (Setem Madrid) presenting a verifiable credential to obtain a discount.
2024-01-24 14:00:04 +00:00
Actors-> **Setem BCN**: IdHub1 (acting as a user wallet for their members holding credentials issued by Setem BCN), **Setem Madrid**: Demo portal, IdHub 2 (acting as verifier). The verifier portal incorporates verification capabilities and support to establish an OIDC4VP dialog with the user wallet for credential presentation (accreditation).
- **Lafede**:
- Instance:
- https://idhub1-lafede.demo.pangea.org
2024-04-04 05:25:38 +00:00
- Motivation: Implementation of dual eIDAS1 and eIDAS2 compliant attestations as signed PDFS with public verifiable credentials exported as QR codes embedded in these documents. Member organisations and related persons of the Lafede federation request membership and training certificates.
Actors-> **Lafede**: idHub
2024-01-24 14:00:04 +00:00
- **Pangea**:
- Instances:
- https://idhub1.demo.pangea.org
- https://idhub2.demo.pangea.org
2024-01-24 14:00:04 +00:00
- Motivation: The case of Pangea as a web/internet service provider, with member organisations that receive services. These organisations have allocated several resources units (mail accounts, blogs, etc.). Only authorised users with a specific role should be able to access the Musician (Administration Control Panel of resources).
- Scenarios:
2024-01-24 14:00:04 +00:00
- Scenario 1-> 'Login with Organisation A (Idp)'. The staff members of organisation A, with the appropiate role, can authenticate themselves by providing their organisation credentials (username and password) to access a service in Pangea (Musician).
Actors-> **Pangea**: IdP (goauthentik), Musician, Orchestra. **Organisation A**: IdP, IdHub
2024-01-24 14:00:04 +00:00
Pangea delegates authentication to the IdP of organisation B using OpenID Connect. In this case, the Pangea's IdP (goauthentik) delegates the authentication to Organisation A's IdP, which get the user's role information from the Organisation A's IdHub.
2024-01-24 14:00:04 +00:00
- Scenario 2-> 'Present a verifiable credential'. The staff members of organisation A, with the appropiate credentials, present them to Pangea in order to access the Musician service.
Actors-> **Pangea**: IdP (goauthentik), IdHub (as verifier), Musician, Orchestra (with also nginx API rproxy). **Organisation A**: IdHub (as user wallet)
- **ereuse**:
- Instances:
- https://idhub1-ereuse.demo.pangea.org
- https://idhub2-ereuse.demo.pangea.org
- https://devicehub.demo.pangea.org
2024-04-04 05:25:38 +00:00
- Motivation: In the circular economy scenario of eReuse, devices change hands, and their hardware composition changes due to repair or upgrades. Hardware changes during processes known as repair, refurbishment, or remanufacturing. The circular economy requires access to trusted and verifiable second-hand computer product information (inventory, datasheet), which qualified actors manage. This is the case with recyclers and refurbishers or remanufacturers that modify devices.
- Scenarios: When a product registered in an inventory service is brought to an actor that changes the hardware (upgrade or dematerialisation), staff from that actor will want to report in that inventory the hardware change performed. Staff persons from a hardware company (Organisation R) can access the "Inventory service D" (DeviceHub instance where a given device is registered in its inventory). This can be achieved by accessing the product page (the URL for that item that constitutes a digital product passport or DPP) of that product item presenting the appropiate credentials.
- **generic**: https://idhub.demo.pangea.org
2024-04-04 05:25:38 +00:00
- Motivation: For demo purposes, for showing other people different than the intended pilot what we do. It is currently similar to Lafede pilot.
### Instances
- **autotest**:
- Instance: https://idhub-autotest.demo.pangea.org
2024-02-21 12:12:00 +00:00
- Motivation: regenerated on each commit in main, intended for automated and fast testing
2024-02-29 17:18:40 +00:00
- **autotest-pair**:
- Instances:
- https://idhub1-autotest.demo.pangea.org
- https://idhub2-autotest.demo.pangea.org
- Motivation: regenerated on each commit in main, intended for automated and fast testing. For testing that requires two instances
- **nightly**:
- Instance: https://idhub-nightly.demo.pangea.org
2024-02-21 12:12:00 +00:00
- Motivation: regenerated on each day at 4:00 AM
2024-03-18 20:16:18 +00:00
- **localhost-pair**:
- Instances:
- http://localhost
- http://idhub2
- Motivation: test locally an OIDC scenario
- **localhost-trio**:
- Instances:
- http://localhost
- http://idhub2
- http://idhub3
2024-03-18 20:18:23 +00:00
- Motivation: test locally a more complex OIDC scenario (similar to pilot xo9b)
2024-03-18 20:16:18 +00:00
### Details on localhost config
2024-04-04 05:25:38 +00:00
All features can be tested in localhost. It was tested on Debian GNU/Linux 12 (bookworm)
2024-03-18 20:16:18 +00:00
2024-04-04 05:25:38 +00:00
- On host machine install nginx and docker.
2024-03-18 20:16:18 +00:00
- nginx acts as a reverse proxy is used to get into docker containers (same approach applies to deployed pilots and instances)
2024-04-04 05:25:38 +00:00
- See [nginx-localhost.site](./nginx-localhost.site) for the nginx site config
- Add at the end of `/etc/hosts` a line with: `127.0.0.1 idhub2 idhub3` so you make the DNS resolution work locally.
## Installation
Considering debian stable distribution (Debian 12 bookworm).
- docker: [install using the convenience script](https://docs.docker.com/engine/install/debian/#install-using-the-convenience-script)
- make: some of the actions are declared in `Makefile`, you will need `sudo apt install make`.
- figlet: display large texts, better visibility when running all the pilots together `sudo apt install figlet`.
## Deployment
Execute `./build__all.sh` to run all the pilots, that includes building locally all the docker images and deploying its docker compose (each pilot has its `docker-compose__pilot-example.yml`).
Or run a specific pilot with `./build__pilot-example.sh`.
2024-04-04 05:25:38 +00:00
All the scripts are written in POSIX Shell. We hope they are easy enough and structured to be adapted to your needs.
## Development
2024-04-04 05:25:38 +00:00
You can use these Docker images for developing the software. This repo is targeted on integrating, deploying and testing the IdHub tools. You can do the same with the other tools, the trick used is to override the docker's directory with a local directory. Example found on all pilots instances.
```yaml
volumes:
- ./idhub1__pilot-example:/opt/idhub
```
If you are developing IdHub, all the instances generate a copy of the target repository such as `idhub1__pilot-example`, which you can modify there, and the changes will apply to the deployment.
In the `.env` there are some variables intended to be used for debugging purposes.
### Commands that you might like
2024-04-04 05:25:38 +00:00
If you want to enter a shell inside a new container:
```sh
docker run -it --entrypoint= ${target_docker_image} bash
```
2024-04-04 05:25:38 +00:00
If you want to enter a shell on already running container:
```sh
docker exec -it ${target_docker_image} bash
```
Where `target_docker_image` contains the ID of the container you want to run (see `docker ps` or `docker ps -a`)