From d6445a463a8b1983e1a5abdbfb26895d3709062c Mon Sep 17 00:00:00 2001 From: Daniel Fernandes Date: Thu, 12 Feb 2026 13:48:38 +0000 Subject: [PATCH 1/6] Add docs/tutorials/local-auth.md --- docs/tutorials/local-auth.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 docs/tutorials/local-auth.md diff --git a/docs/tutorials/local-auth.md b/docs/tutorials/local-auth.md new file mode 100644 index 0000000000..851968db16 --- /dev/null +++ b/docs/tutorials/local-auth.md @@ -0,0 +1,16 @@ +# Run Auth Locally + +BlueAPI can be secured using OIDC authenticaiton. For development it can be useful to run a containerised version of the OIDC stack, to serve a local instance of BlueAPI. + +To run the stack: + +1. In the root directory run `git submodule update --init --recursive` to initialise the example-services repo +2. Run `docker compose up -d` to launch an instance of NumTracker, RabbitMQ, Keycloak, Tiled, OPA and a number of IOCs, in detached mode +3. Run `blueapi -c tests/system_tests/config.yaml serve` to launch BlueAPI configured to use the launched stack. This may take a while, as BlueAPI will attempt to connect to a number of devices via Channel Access + +To log in through the BlueAPI CLI: + +1. Run `blueapi -c tests/system_tests/config.yaml login` +2. Follow the login prompt to Keycloak, then log in with the username `admin` and password `admin` +3. When promped by Keycloak, grant BlueAPI access to the listed privileges +4. Run `blueapi controller plans` to check that the log in has succeeded From 5206567395129e2e34d174d07c4dce74635d1ddd Mon Sep 17 00:00:00 2001 From: Daniel Fernandes Date: Thu, 19 Feb 2026 11:43:55 +0000 Subject: [PATCH 2/6] Use route to compose file in compose up --- docs/tutorials/local-auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/local-auth.md b/docs/tutorials/local-auth.md index 851968db16..d2b4ea8feb 100644 --- a/docs/tutorials/local-auth.md +++ b/docs/tutorials/local-auth.md @@ -5,7 +5,7 @@ BlueAPI can be secured using OIDC authenticaiton. For development it can be usef To run the stack: 1. In the root directory run `git submodule update --init --recursive` to initialise the example-services repo -2. Run `docker compose up -d` to launch an instance of NumTracker, RabbitMQ, Keycloak, Tiled, OPA and a number of IOCs, in detached mode +2. Run `docker compose -f tests/system_tests/compose.yaml up -d` to launch an instance of NumTracker, RabbitMQ, Keycloak, Tiled, OPA and a number of IOCs, in detached mode 3. Run `blueapi -c tests/system_tests/config.yaml serve` to launch BlueAPI configured to use the launched stack. This may take a while, as BlueAPI will attempt to connect to a number of devices via Channel Access To log in through the BlueAPI CLI: From 081dad3a008fb6a99b0804bc729d373681e41258 Mon Sep 17 00:00:00 2001 From: Daniel Fernandes Date: Thu, 19 Feb 2026 11:48:40 +0000 Subject: [PATCH 3/6] Add running env file to launching stack --- docs/tutorials/local-auth.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/local-auth.md b/docs/tutorials/local-auth.md index d2b4ea8feb..5569f635ac 100644 --- a/docs/tutorials/local-auth.md +++ b/docs/tutorials/local-auth.md @@ -6,7 +6,8 @@ To run the stack: 1. In the root directory run `git submodule update --init --recursive` to initialise the example-services repo 2. Run `docker compose -f tests/system_tests/compose.yaml up -d` to launch an instance of NumTracker, RabbitMQ, Keycloak, Tiled, OPA and a number of IOCs, in detached mode -3. Run `blueapi -c tests/system_tests/config.yaml serve` to launch BlueAPI configured to use the launched stack. This may take a while, as BlueAPI will attempt to connect to a number of devices via Channel Access +3. Run `source tests/system_tests/.env` which will set required EPICS environmental variables +4. Run `blueapi -c tests/system_tests/config.yaml serve` to launch BlueAPI configured to use the launched stack. This may take a while, as BlueAPI will attempt to connect to a number of devices via Channel Access To log in through the BlueAPI CLI: From 7c77375a20829b9aba112c1b4c1b7aee7f83e296 Mon Sep 17 00:00:00 2001 From: Daniel Fernandes Date: Thu, 19 Feb 2026 11:49:39 +0000 Subject: [PATCH 4/6] Typo --- docs/tutorials/local-auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/local-auth.md b/docs/tutorials/local-auth.md index 5569f635ac..f6f358e69d 100644 --- a/docs/tutorials/local-auth.md +++ b/docs/tutorials/local-auth.md @@ -12,6 +12,6 @@ To run the stack: To log in through the BlueAPI CLI: 1. Run `blueapi -c tests/system_tests/config.yaml login` -2. Follow the login prompt to Keycloak, then log in with the username `admin` and password `admin` +2. Follow the login prompted to Keycloak, then log in with the username `admin` and password `admin` 3. When promped by Keycloak, grant BlueAPI access to the listed privileges 4. Run `blueapi controller plans` to check that the log in has succeeded From 2919a54ca6e43424e13e879d9a84d835481cb335 Mon Sep 17 00:00:00 2001 From: Daniel Fernandes Date: Thu, 19 Feb 2026 11:53:02 +0000 Subject: [PATCH 5/6] Remove config param frm login --- docs/tutorials/local-auth.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/local-auth.md b/docs/tutorials/local-auth.md index f6f358e69d..9d759461c3 100644 --- a/docs/tutorials/local-auth.md +++ b/docs/tutorials/local-auth.md @@ -11,7 +11,7 @@ To run the stack: To log in through the BlueAPI CLI: -1. Run `blueapi -c tests/system_tests/config.yaml login` +1. Run `blueapi login` (if you want to run a plan with stomp config, add the `-c tests/system_tests/config.yaml` parameter) 2. Follow the login prompted to Keycloak, then log in with the username `admin` and password `admin` 3. When promped by Keycloak, grant BlueAPI access to the listed privileges 4. Run `blueapi controller plans` to check that the log in has succeeded From 6c9687a0643cccc255c7284431dbecec36d2aa26 Mon Sep 17 00:00:00 2001 From: Daniel Fernandes Date: Fri, 20 Feb 2026 14:03:59 +0000 Subject: [PATCH 6/6] Add note on addresses of blueapi and tiled --- docs/tutorials/local-auth.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tutorials/local-auth.md b/docs/tutorials/local-auth.md index 9d759461c3..3822320e7e 100644 --- a/docs/tutorials/local-auth.md +++ b/docs/tutorials/local-auth.md @@ -15,3 +15,5 @@ To log in through the BlueAPI CLI: 2. Follow the login prompted to Keycloak, then log in with the username `admin` and password `admin` 3. When promped by Keycloak, grant BlueAPI access to the listed privileges 4. Run `blueapi controller plans` to check that the log in has succeeded + +By default the BlueAPI instance will be available via the OAuth2 proxy at `localhost:4180`, and Tiled through its OAuth2 proxy at `localhost:4181`.