Skip to content

Commit 5f1b43f

Browse files
guidograzioliguidograzioli
committed
update docs
1 parent c6bb815 commit 5f1b43f

File tree

8 files changed

+91
-85
lines changed

8 files changed

+91
-85
lines changed

Diff for: ‎.github/workflows/traffic.yml

+7-7
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,22 @@
11
name: Collect traffic stats
22
on:
3-
schedule:
3+
schedule:
44
- cron: "51 23 * * 0"
5-
workflow_dispatch:
6-
5+
workflow_dispatch:
6+
77
jobs:
88
traffic:
99
runs-on: ubuntu-latest
1010
steps:
1111
- uses: actions/checkout@v2
1212
with:
1313
ref: "gh-pages"
14-
15-
- name: GitHub traffic
14+
15+
- name: GitHub traffic
1616
uses: sangonzal/[email protected]
1717
env:
18-
TRAFFIC_ACTION_TOKEN: ${{ secrets.TRIGGERING_PAT }}
19-
18+
TRAFFIC_ACTION_TOKEN: ${{ secrets.TRIGGERING_PAT }}
19+
2020
- name: Commit changes
2121
uses: EndBug/add-and-commit@v4
2222
with:

Diff for: ‎CHANGELOG.rst

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
=============================================
2-
middleware\_automation.keycloak Release Notes
3-
=============================================
1+
=============
2+
Release Notes
3+
=============
44

55
.. contents:: Topics
66

Diff for: ‎CONTRIBUTING.md

+34
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,37 @@
1+
## Developing
2+
3+
### Build and install locally
4+
5+
Clone the repository, checkout the tag you want to build, or pick the main branch for the development version; then:
6+
7+
ansible-galaxy collection build .
8+
ansible-galaxy collection install middleware_automation-keycloak-*.tar.gz
9+
10+
11+
### Development environment
12+
13+
Make sure your development machine has avilable:
14+
15+
* python 3.11+
16+
* virtualenv
17+
* docker (or podman)
18+
19+
In order to run setup the development environment and run the molecule tests locally, after cloning the repository:
20+
21+
```
22+
# create new virtualenv using python 3
23+
virtualenv $PATH_TO_DEV_VIRTUALENV
24+
# activate the virtual env
25+
source $PATH_TO_DEV_VIRTUALENV/bin/activate
26+
# install ansible and tools onto the virtualenv
27+
pip install yamllint 'molecule>=6.0' 'molecule-plugins[docker]' 'ansible-core>=2.15' ansible-lint
28+
# install collection dependencies
29+
ansible-galaxy collection install -r requirements.yml
30+
# install python dependencies
31+
pip install -r requirements.txt molecule/requirements.txt
32+
# execute the tests (replace --all with -s subdirectory to run a single test)
33+
molecule test --all
34+
```
135

236
## Contributor's Guidelines
337

Diff for: ‎README.md

+7-7
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
<!--start build_status -->
44
[![Build Status](https://github.com/ansible-middleware/keycloak/workflows/CI/badge.svg?branch=main)](https://github.com/ansible-middleware/keycloak/actions/workflows/ci.yml)
55

6-
> **_NOTE:_ If you are Red Hat customer, install `redhat.sso` (for Red Hat Single Sign-On) or `redhat.rhbk` (for Red Hat Build of Keycloak) from [Automation Hub](https://console.redhat.com/ansible/ansible-dashboard) as the certified version of this collection.**
6+
> **_NOTE:_ If you are Red Hat customer, install `redhat.rhbk` (for Red Hat Build of Keycloak) or `redhat.sso` (for Red Hat Single Sign-On) from [Automation Hub](https://console.redhat.com/ansible/ansible-dashboard) as the certified version of this collection.**
77
88
<!--end build_status -->
99
<!--start description -->
@@ -49,9 +49,10 @@ A requirement file is provided to install:
4949
<!--start roles_paths -->
5050
### Included roles
5151
52-
* [`keycloak`](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md): role for installing the service (keycloak <= 19.0).
53-
* [`keycloak_realm`](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_realm/README.md): role for configuring a realm, user federation(s), clients and users, in an installed service.
54-
* [`keycloak_quarkus`](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak_quarkus/README.md): role for installing the quarkus variant of keycloak (>= 17.0.0).
52+
* `keycloak_quarkus`: role for installing keycloak (>= 19.0.0, quarkus based).
53+
* `keycloak_realm`: role for configuring a realm, user federation(s), clients and users, in an installed service.
54+
* `keycloak`: role for installing legacy keycloak (<= 19.0, wildfly based).
55+
5556
<!--end roles_paths -->
5657

5758
## Usage
@@ -61,7 +62,7 @@ A requirement file is provided to install:
6162
<!--start rhbk_playbook -->
6263
* [`playbooks/keycloak.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak.yml) installs keycloak legacy based on the defined variables (using most defaults).
6364
* [`playbooks/keycloak_quarkus.yml`](https://github.com/ansible-middleware/keycloak/blob/main/playbooks/keycloak_quarkus.yml) installs keycloak >= 17 based on the defined variables (using most defaults).
64-
65+
6566
Both playbooks include the `keycloak` role, with different settings, as described in the following sections.
6667

6768
For full service configuration details, refer to the [keycloak role README](https://github.com/ansible-middleware/keycloak/blob/main/roles/keycloak/README.md).
@@ -92,7 +93,7 @@ Execute the following command from the source root directory
9293

9394
```
9495
ansible-playbook -i <ansible_hosts> -e @rhn-creds.yml playbooks/keycloak.yml -e keycloak_admin_password=<changeme>
95-
```
96+
```
9697
9798
- `keycloak_admin_password` Password for the administration console user account.
9899
- `ansible_hosts` is the inventory, below is an example inventory for deploying to localhost
@@ -143,4 +144,3 @@ Apache License v2.0 or later
143144
<!--start license -->
144145
See [LICENSE](LICENSE) to view the full text.
145146
<!--end license -->
146-

Diff for: ‎docs/_gh_include/footer.inc

+2-2
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
</div>
88
<hr/>
99
<div role="contentinfo">
10-
<p>&#169; Copyright 2022, Red Hat, Inc.</p>
10+
<p>&#169; Copyright 2024, Red Hat, Inc.</p>
1111
</div>
1212
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
1313
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
@@ -18,4 +18,4 @@
1818
</section>
1919
</div>
2020
</body>
21-
</html>
21+
</html>

Diff for: ‎docs/index.rst

+5-11
Original file line numberDiff line numberDiff line change
@@ -10,31 +10,25 @@ Welcome to Keycloak Collection documentation
1010
README
1111
plugins/index
1212
roles/index
13+
Changelog <CHANGELOG>
1314

1415
.. toctree::
1516
:maxdepth: 2
1617
:caption: Developer documentation
1718

18-
testing
19-
developing
20-
releasing
21-
22-
.. toctree::
23-
:maxdepth: 2
24-
:caption: General
25-
26-
Changelog <CHANGELOG>
19+
Developing <developing>
20+
Testing <testing>
21+
Releasing <releasing>
2722

2823
.. toctree::
2924
:maxdepth: 2
3025
:caption: Middleware collections
3126

32-
Infinispan / Red Hat Data Grid <https://ansible-middleware.github.io/infinispan/main/>
3327
Keycloak / Red Hat Single Sign-On <https://ansible-middleware.github.io/keycloak/main/>
28+
Infinispan / Red Hat Data Grid <https://ansible-middleware.github.io/infinispan/main/>
3429
Wildfly / Red Hat JBoss EAP <https://ansible-middleware.github.io/wildfly/main/>
3530
Tomcat / Red Hat JWS <https://ansible-middleware.github.io/jws/main/>
3631
ActiveMQ / Red Hat AMQ Broker <https://ansible-middleware.github.io/amq/main/>
3732
Kafka / Red Hat AMQ Streams <https://ansible-middleware.github.io/amq_streams/main/>
3833
Ansible Middleware utilities <https://ansible-middleware.github.io/common/main/>
39-
Red Hat CSP Download <https://ansible-middleware.github.io/redhat-csp-download/main/>
4034
JCliff <https://ansible-middleware.github.io/ansible_collections_jcliff/main/>

Diff for: ‎docs/testing.md

+2-27
Original file line numberDiff line numberDiff line change
@@ -4,40 +4,15 @@
44

55
The collection is tested with a [molecule](https://github.com/ansible-community/molecule) setup covering the included roles and verifying correct installation and idempotency.
66
In order to run the molecule tests locally with python 3.9 available, after cloning the repository:
7-
8-
```
9-
pip install yamllint 'molecule[docker]~=3.5.2' ansible-core flake8 ansible-lint voluptuous
10-
molecule test --all
11-
```
12-
13-
14-
## Integration testing
15-
16-
Demo repositories which depend on the collection, and aggregate functionality with other middleware_automation collections, are automatically rebuilt
17-
at every collection release to ensure non-breaking changes and consistent behaviour.
18-
19-
The repository are:
20-
21-
- [Flange demo](https://github.com/ansible-middleware/flange-demo)
22-
A deployment of Wildfly cluster integrated with keycloak and infinispan.
23-
- [CrossDC keycloak demo](https://github.com/ansible-middleware/cross-dc-rhsso-demo)
24-
A clustered multi-regional installation of keycloak with infinispan remote caches.
7+
The test scenarios are available on the source code repository each on his own subdirectory under [molecule/](https://github.com/ansible-middleware/keycloak/molecule).
258

269

2710
## Test playbooks
2811

2912
Sample playbooks are provided in the `playbooks/` directory; to run the playbooks locally (requires a rhel system with python 3.9+, ansible, and systemd) the steps are as follows:
3013

3114
```
32-
# setup environment
33-
pip install ansible-core
34-
# clone the repository
35-
git clone https://github.com/ansible-middleware/keycloak
36-
cd keycloak
37-
# install collection dependencies
38-
ansible-galaxy collection install -r requirements.yml
39-
# install collection python deps
40-
pip install -r requirements.txt
15+
# setup environment as in developing
4116
# create inventory for localhost
4217
cat << EOF > inventory
4318
[keycloak]

Diff for: ‎molecule/debian/converge.yml

+31-28
Original file line numberDiff line numberDiff line change
@@ -7,36 +7,39 @@
77
keycloak_realm: TestRealm
88
keycloak_quarkus_log: file
99
keycloak_quarkus_frontend_url: 'http://localhost:8080/'
10-
keycloak_quarkus_start_dev: True
10+
keycloak_quarkus_start_dev: true
1111
keycloak_quarkus_proxy_mode: none
12-
keycloak_client_default_roles:
13-
- TestRoleAdmin
14-
- TestRoleUser
15-
keycloak_client_users:
16-
- username: TestUser
17-
password: password
18-
client_roles:
19-
- client: TestClient
20-
role: TestRoleUser
21-
- username: TestAdmin
22-
password: password
23-
client_roles:
24-
- client: TestClient
25-
role: TestRoleUser
26-
- client: TestClient
27-
role: TestRoleAdmin
28-
keycloak_clients:
29-
- name: TestClient
30-
roles: "{{ keycloak_client_default_roles }}"
31-
public_client: "{{ keycloak_client_public }}"
32-
web_origins: "{{ keycloak_client_web_origins }}"
33-
users: "{{ keycloak_client_users }}"
34-
client_id: TestClient
35-
attributes:
36-
post.logout.redirect.uris: '/public/logout'
3712
roles:
3813
- role: keycloak_quarkus
3914
- role: keycloak_realm
40-
keycloak_realm: TestRealm
41-
keycloak_admin_password: "remembertochangeme"
4215
keycloak_context: ''
16+
keycloak_client_default_roles:
17+
- TestRoleAdmin
18+
- TestRoleUser
19+
keycloak_client_users:
20+
- username: TestUser
21+
password: password
22+
client_roles:
23+
- client: TestClient
24+
role: TestRoleUser
25+
realm: "{{ keycloak_realm }}"
26+
- username: TestAdmin
27+
password: password
28+
client_roles:
29+
- client: TestClient
30+
role: TestRoleUser
31+
realm: "{{ keycloak_realm }}"
32+
- client: TestClient
33+
role: TestRoleAdmin
34+
realm: "{{ keycloak_realm }}"
35+
keycloak_realm: TestRealm
36+
keycloak_clients:
37+
- name: TestClient
38+
roles: "{{ keycloak_client_default_roles }}"
39+
realm: "{{ keycloak_realm }}"
40+
public_client: "{{ keycloak_client_public }}"
41+
web_origins: "{{ keycloak_client_web_origins }}"
42+
users: "{{ keycloak_client_users }}"
43+
client_id: TestClient
44+
attributes:
45+
post.logout.redirect.uris: '/public/logout'

0 commit comments

Comments
 (0)