From 694743d8390f25d8fefcb1ce19eaac2c90cbb08c Mon Sep 17 00:00:00 2001 From: James Robinson Date: Mon, 30 Sep 2024 16:17:59 +0100 Subject: [PATCH 1/4] :memo: Update build and test instructions --- README.md | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 148cdbf..1906459 100644 --- a/README.md +++ b/README.md @@ -21,15 +21,39 @@ Synchronise a Guacamole PostgreSQL database with an LDAP server, such as Microso - POSTGRESQL_USERNAME: Username of PostgreSQL user - REPEAT_INTERVAL: How often (in seconds) to wait before attempting to synchronise again (default: '300') -## Tests +## Development -To run the tests you will need to install +If you are interested in developing this package, you should install the following prerequisites: -- `bats-core` -- `yq` +- [`hatch`](https://hatch.pypa.io/latest/install/) -The tests can be run with: +### Running with Docker + +Build the Docker image with + +```console +$ docker build . -t guacamole-user-sync +``` + +Run the Docker image with + +```console +$ docker run -it \ + -e LDAP_HOST=$(your LDAP server host) \ + -e LDAP_GROUP_BASE_DN=$(your LDAP group DN) \ + -e LDAP_GROUP_FILTER=$(your LDAP group filter) \ + -e LDAP_USER_BASE_DN=$(your LDAP user DN) \ + -e LDAP_USER_FILTER=$(your LDAP user filter) \ + -e POSTGRESQL_HOST=$(your PostgreSQL server host) \ + -e POSTGRESQL_PASSWORD=$(your PostgreSQL connection password) \ + -e POSTGRESQL_USERNAME=$(your PostgreSQL connection username) \ + guacamole-user-sync +``` + +### Tests + +The tests can be run with ```console -$ bats tests +$ hatch run test:all ``` From 290d01e994be78fc2573e4d3ca9bf3155ee3003d Mon Sep 17 00:00:00 2001 From: James Robinson Date: Mon, 30 Sep 2024 16:29:05 +0100 Subject: [PATCH 2/4] :sparkles: Add badges --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 1906459..eb2d1da 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # guacamole-user-sync Synchronise a Guacamole PostgreSQL database with an LDAP server, such as Microsoft Active Directory +[![Latest image](https://ghcr-badge.egpl.dev/alan-turing-institute/guacamole-user-sync/latest_tag)](https://github.com/alan-turing-institute/guacamole-user-sync/pkgs/container/guacamole-user-sync) +[![Image size](https://ghcr-badge.egpl.dev/alan-turing-institute/guacamole-user-sync/size)](https://github.com/alan-turing-institute/guacamole-user-sync/pkgs/container/guacamole-user-sync) +[![Publish status](https://github.com/alan-turing-institute/guacamole-user-sync/actions/workflows/publish_docker.yaml/badge.svg)](https://github.com/alan-turing-institute/guacamole-user-sync/pkgs/) + ## Environment variables - DEBUG: Enable debug output (default: 'False') From 372bdd1ced8035eb257712f628bae20d2f523c11 Mon Sep 17 00:00:00 2001 From: James Robinson Date: Mon, 30 Sep 2024 16:38:43 +0100 Subject: [PATCH 3/4] :memo: Improve run instructions --- README.md | 53 +++++++++++++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index eb2d1da..0855c85 100644 --- a/README.md +++ b/README.md @@ -5,25 +5,42 @@ Synchronise a Guacamole PostgreSQL database with an LDAP server, such as Microso [![Image size](https://ghcr-badge.egpl.dev/alan-turing-institute/guacamole-user-sync/size)](https://github.com/alan-turing-institute/guacamole-user-sync/pkgs/container/guacamole-user-sync) [![Publish status](https://github.com/alan-turing-institute/guacamole-user-sync/actions/workflows/publish_docker.yaml/badge.svg)](https://github.com/alan-turing-institute/guacamole-user-sync/pkgs/) +## Running with Docker + +You can run this Docker image as follows + +```console +$ docker run -it \ + -e LDAP_HOST=$(your LDAP server host) \ + -e LDAP_GROUP_BASE_DN=$(your LDAP group DN) \ + -e LDAP_GROUP_FILTER=$(your LDAP group filter) \ + -e LDAP_USER_BASE_DN=$(your LDAP user DN) \ + -e LDAP_USER_FILTER=$(your LDAP user filter) \ + -e POSTGRESQL_HOST=$(your PostgreSQL server host) \ + -e POSTGRESQL_PASSWORD=$(your PostgreSQL connection password) \ + -e POSTGRESQL_USERNAME=$(your PostgreSQL connection username) \ + ghcr.io/alan-turing-institute/guacamole-user-sync:$(version you want to use) +``` + ## Environment variables -- DEBUG: Enable debug output (default: 'False') -- LDAP_BIND_DN: (Optional) distinguished name of LDAP bind user -- LDAP_BIND_PASSWORD: (Optional) password of LDAP bind user -- LDAP_GROUP_BASE_DN: Base DN for groups -- LDAP_GROUP_FILTER: LDAP filter to select groups -- LDAP_GROUP_NAME_ATTR: Attribute used to extract group names (default: 'cn') -- LDAP_HOST: LDAP host -- LDAP_PORT: LDAP port (default: '389') -- LDAP_USER_BASE_DN: Base DN for users -- LDAP_USER_FILTER: LDAP filter to select users -- LDAP_USER_NAME_ATTR: Attribute used to extract user names (default: 'userPrincipalName') -- POSTGRESQL_DB_NAME: Database name for PostgreSQL server (default: 'guacamole') -- POSTGRESQL_HOST: PostgreSQL server host -- POSTGRESQL_PASSWORD: Password of PostgreSQL user -- POSTGRESQL_PORT: PostgreSQL server port (default: '5432') -- POSTGRESQL_USERNAME: Username of PostgreSQL user -- REPEAT_INTERVAL: How often (in seconds) to wait before attempting to synchronise again (default: '300') +- `DEBUG`: Enable debug output (default: 'False') +- `LDAP_BIND_DN`: (Optional) distinguished name of LDAP bind user +- `LDAP_BIND_PASSWORD`: (Optional) password of LDAP bind user +- `LDAP_GROUP_BASE_DN`: Base DN for groups +- `LDAP_GROUP_FILTER`: LDAP filter to select groups +- `LDAP_GROUP_NAME_ATTR`: Attribute used to extract group names (default: 'cn') +- `LDAP_HOST`: LDAP host +- `LDAP_PORT`: LDAP port (default: '389') +- `LDAP_USER_BASE_DN`: Base DN for users +- `LDAP_USER_FILTER`: LDAP filter to select users +- `LDAP_USER_NAME_ATTR`: Attribute used to extract user names (default: 'userPrincipalName') +- `POSTGRESQL_DB_NAME`: Database name for PostgreSQL server (default: 'guacamole') +- `POSTGRESQL_HOST`: PostgreSQL server host +- `POSTGRESQL_PASSWORD`: Password of PostgreSQL user +- `POSTGRESQL_PORT`: PostgreSQL server port (default: '5432') +- `POSTGRESQL_USERNAME`: Username of PostgreSQL user +- `REPEAT_INTERVAL`: How often (in seconds) to wait before attempting to synchronise again (default: '300') ## Development @@ -39,7 +56,7 @@ Build the Docker image with $ docker build . -t guacamole-user-sync ``` -Run the Docker image with +Run the Docker image you have just built with ```console $ docker run -it \ From 3b3b1289d1f7ceaeff1f21e7a0b8b711a3ab5cbb Mon Sep 17 00:00:00 2001 From: James Robinson Date: Mon, 30 Sep 2024 16:40:56 +0100 Subject: [PATCH 4/4] :memo: Better contributing instructions --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0855c85..7e7adcd 100644 --- a/README.md +++ b/README.md @@ -42,11 +42,9 @@ $ docker run -it \ - `POSTGRESQL_USERNAME`: Username of PostgreSQL user - `REPEAT_INTERVAL`: How often (in seconds) to wait before attempting to synchronise again (default: '300') -## Development +## Contributing -If you are interested in developing this package, you should install the following prerequisites: - -- [`hatch`](https://hatch.pypa.io/latest/install/) +Pull requests are always welcome. ### Running with Docker @@ -73,7 +71,11 @@ $ docker run -it \ ### Tests -The tests can be run with +In order to run the tests, you should install the following prerequisites: + +- [`hatch`](https://hatch.pypa.io/latest/install/) + +The tests can then be run with ```console $ hatch run test:all