Skip to content

docs: How to run local auth stack #1384

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dan-fernandes wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs: How to run local auth stack #1384

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d6445a4
Add docs/tutorials/local-auth.md
dan-fernandes Feb 12, 2026
5ec0588
Merge branch 'main' into add-docs-for-self-hosting-auth
dan-fernandes Feb 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/tutorials/local-auth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor

@tpoliaw tpoliaw Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this work from the root of the repo? I think you either need to run from the system_tests directory or pass the file directly.

docker compose -f tests/system_tests/compose.yaml up -d

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
Copy link
Contributor

@tpoliaw tpoliaw Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you run source tests/system_tests/.env first, the devices will connect and it'll be a fair bit quicker.


To log in through the BlueAPI CLI:

1. Run `blueapi -c tests/system_tests/config.yaml login`
Copy link
Contributor

@tpoliaw tpoliaw Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think login requires the config file as the server is on the default host and port but worth adding a comment that it's needed if you want to run a plan with stomp config.

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
Copy link
Contributor

@tpoliaw tpoliaw Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
3. When promped by Keycloak, grant BlueAPI access to the listed privileges
3. When prompted by Keycloak, grant BlueAPI access to the listed privileges

4. Run `blueapi controller plans` to check that the log in has succeeded