Updated hacking on KC guide
This commit is contained in:
Stian Thorgersen
parent
b8d05c452c
commit
656a5c4baa
6 changed files with 174 additions and 22 deletions
10
README.md
10
README.md
|
|
@ -7,10 +7,16 @@ Keycloak is an SSO Service for web apps and REST services. For more information
|
|||
Building
|
||||
--------
|
||||
|
||||
Ensure you have JDK 7 (or newer) and Maven 3.2.1 (or newer) installed
|
||||
Ensure you have JDK 7 (or newer), Maven 3.2.1 (or newer) and Git installed
|
||||
|
||||
java -version
|
||||
mvn -version
|
||||
git --version
|
||||
|
||||
First clone the Keycloak repository:
|
||||
|
||||
git clone https://github.com/keycloak/keycloak.git
|
||||
cd keycloak
|
||||
|
||||
To build Keycloak run:
|
||||
|
||||
|
|
@ -45,7 +51,7 @@ To stop the server press `Ctrl + C`.
|
|||
Contributing
|
||||
------------
|
||||
|
||||
* [Hacking On Keycloak](https://github.com/keycloak/keycloak/blob/master/misc/HackingOnKeycloak.md)
|
||||
* [Hacking on Keycloak](misc/HackingOnKeycloak.md)
|
||||
|
||||
|
||||
License
|
||||
|
|
|
|||
|
|
@ -1,11 +1,20 @@
|
|||
Test with various databases
|
||||
===========================
|
||||
|
||||
MongoDB
|
||||
-------
|
||||
|
||||
The Keycloak testsuite uses an embedded MongoDB when running tests so you don't have to have one running locally.
|
||||
|
||||
Run tests:
|
||||
|
||||
mvn install -Pmongo
|
||||
|
||||
|
||||
MySQL
|
||||
-----
|
||||
|
||||
Use the official [MySQL docker image](https://registry.hub.docker.com/_/mysql/).
|
||||
The simplest way to test with MySQL is to use the official [MySQL docker image](https://registry.hub.docker.com/_/mysql/).
|
||||
|
||||
Start MySQL:
|
||||
|
||||
|
|
@ -13,7 +22,7 @@ Start MySQL:
|
|||
|
||||
Run tests:
|
||||
|
||||
mvn clean install -Dkeycloak.connectionsJpa.url=jdbc:mysql://`docker inspect --format '{{ .NetworkSettings.IPAddress }}' mysql`/keycloak -Dkeycloak.connectionsJpa.driver=com.mysql.jdbc.Driver -Dkeycloak.connectionsJpa.user=keycloak -Dkeycloak.connectionsJpa.password=keycloak
|
||||
mvn install -Dkeycloak.connectionsJpa.url=jdbc:mysql://`docker inspect --format '{{ .NetworkSettings.IPAddress }}' mysql`/keycloak -Dkeycloak.connectionsJpa.driver=com.mysql.jdbc.Driver -Dkeycloak.connectionsJpa.user=keycloak -Dkeycloak.connectionsJpa.password=keycloak
|
||||
|
||||
Stop MySQl:
|
||||
|
||||
|
|
@ -23,7 +32,7 @@ Stop MySQl:
|
|||
PostgreSQL
|
||||
----------
|
||||
|
||||
Use the official [PostgreSQL docker image](https://registry.hub.docker.com/_/postgres/).
|
||||
The simplest way to test with PostgreSQL is to use the official [PostgreSQL docker image](https://registry.hub.docker.com/_/postgres/).
|
||||
|
||||
Start PostgreSQL:
|
||||
|
||||
|
|
@ -31,7 +40,7 @@ Start PostgreSQL:
|
|||
|
||||
Run tests:
|
||||
|
||||
mvn clean install -Dkeycloak.connectionsJpa.url=jdbc:postgresql://`docker inspect --format '{{ .NetworkSettings.IPAddress }}' postgres`:5432/keycloak -Dkeycloak.connectionsJpa.driver=org.postgresql.Driver -Dkeycloak.connectionsJpa.user=keycloak -Dkeycloak.connectionsJpa.password=keycloak
|
||||
mvn install -Dkeycloak.connectionsJpa.url=jdbc:postgresql://`docker inspect --format '{{ .NetworkSettings.IPAddress }}' postgres`:5432/keycloak -Dkeycloak.connectionsJpa.driver=org.postgresql.Driver -Dkeycloak.connectionsJpa.user=keycloak -Dkeycloak.connectionsJpa.password=keycloak
|
||||
|
||||
Stop PostgreSQL:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,9 +1,70 @@
|
|||
So you are a developer who wants to start hacking on Keycloak? Here is the short list of things you need to know:
|
||||
Hacking on Keycloak
|
||||
===================
|
||||
|
||||
1. You'll get a good feel for the Keycloak server and adapters if you try out the demo apps. Instructions for setting that up are at [https://github.com/keycloak/keycloak/tree/master/examples/demo-template](https://github.com/keycloak/keycloak/tree/master/examples/demo-template).
|
||||
2. The build has three Maven roots. There is the obvious one at the root of the project, which builds all the core stuff. The second one is in /distribution. That assembles the appliance, the adapters, and a few other things. The third is in /docbook. That one creates the documentation.
|
||||
3. We track everything in [Jira](https://issues.jboss.org/browse/KEYCLOAK). Make sure you create an issue for any changes you propose.
|
||||
4. We work with GitHub in much the same way as the WildFly project. You can look at [Hacking on Wildfly](https://developer.jboss.org/wiki/HackingOnWildFly) to get some tips on that.
|
||||
5. If you have other questions, ask on the [Developer Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-dev). We don't use IRC much, so that's the best place to ask.
|
||||
6. For a more productive development, please consider using org.keycloak.testutils.KeycloakServer. This class is a Java Application that starts a KC server without requiring you to deploy a WAR file in a specific container.
|
||||
|
||||
GitHub Repository
|
||||
-----------------
|
||||
|
||||
### Create a GitHub account if you don't already have one
|
||||
|
||||
[Join GitHub](https://github.com/join)
|
||||
|
||||
### Fork Keycloak repository into your account
|
||||
|
||||
[https://github.com/keycloak/keycloak](https://github.com/keycloak/keycloak)
|
||||
|
||||
### Clone your newly forked copy onto your local workspace
|
||||
|
||||
git clone https://github.com/<your username>/keycloak.git
|
||||
cd keycloak
|
||||
|
||||
### Add a remote ref to upstream for pulling future updates
|
||||
|
||||
git remote add upstream https://github.com/keycloak/keycloak.git
|
||||
|
||||
### Pull later updates from upstream
|
||||
|
||||
git fetch upstream
|
||||
git rebase upstream/master
|
||||
|
||||
|
||||
Discuss changes
|
||||
---------------
|
||||
|
||||
Before starting work on a new feature or anything besides a minor bug fix join the [Keycloak Dev mailing list](https://lists.jboss.org/mailman/listinfo/keycloak-dev)
|
||||
and send a mail about your proposed changes. This is vital as otherwise you may waste days implementing a feature that is later rejected.
|
||||
|
||||
Once you have received feedback from the mailing list if there's not one already create a (JIRA issue)[https://issues.jboss.org/browse/KEYCLOAK].
|
||||
|
||||
|
||||
Implement changes
|
||||
-----------------
|
||||
|
||||
We don't currently enforce a code style in Keycloak, but a good reference is the code style used by WildFly. This can be
|
||||
retrieved from (https://github.com/wildfly/wildfly-core/tree/master/ide-configs)[https://github.com/wildfly/wildfly-core/tree/master/ide-configs].
|
||||
|
||||
If your changes requires updates to the database read [Updating Database Schema](UpdatingDatabaseSchema.md).
|
||||
|
||||
To try your changes out manually you can quickly start Keycloak from within your IDEA or Maven, to find out how to do this
|
||||
read [Testsuite](Testsuite.md). It's also important that you add tests to the testsuite for your changes.
|
||||
|
||||
|
||||
Get your changes merged into upstream
|
||||
-------------------------------------
|
||||
|
||||
Here's a quick check list for a good pull request (PR):
|
||||
|
||||
* Discussed and agreed on Keycloak Dev mailing list
|
||||
* One commit per PR
|
||||
* One feature/change per PR
|
||||
* No changes to code not directly related to your change (e.g. no formatting changes or refactoring to existing code, if you want to refactor/improve existing code that's a separate discussion to mailing list and JIRA issue)
|
||||
* A JIRA associated with your PR (include the JIRA issue number in commit comment)
|
||||
* All tests in testsuite pass
|
||||
* Do a rebase on upstream master
|
||||
|
||||
Once you're happy with your changes go to GitHub and create a PR.
|
||||
|
||||
|
||||
Release Keycloak
|
||||
----------------
|
||||
|
||||
* [Release Process](ReleaseProcess.md)
|
||||
80
misc/ReleaseProcess.md
Normal file
80
misc/ReleaseProcess.md
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
## Test
|
||||
|
||||
* Make sure tests pass on Travis
|
||||
* Make sure tests pass on Jenkins
|
||||
* Go through the (manual testing)[https://docs.google.com/spreadsheets/d/17C_WEHNE03r5DxN71OXGJaytjA6_WjZKCXRcsnmNQD4]
|
||||
|
||||
## Create release
|
||||
|
||||
* Get from github
|
||||
```
|
||||
$ git@github.com:keycloak/keycloak.git
|
||||
```
|
||||
|
||||
* Build everything to make sure its kosher.
|
||||
```
|
||||
$ cd keycloak
|
||||
$ mvn install
|
||||
```
|
||||
|
||||
* Build javadoc and jaxrs-doc
|
||||
```
|
||||
$ mvn javadoc:javadoc
|
||||
# This is for jaxrs-docs
|
||||
$ cd services
|
||||
$ mvn package
|
||||
# back to root keycloak dir
|
||||
$ cd ..
|
||||
```
|
||||
|
||||
* Upload to Nexus (from project root)
|
||||
```
|
||||
$ mvn -Pdistribution deploy
|
||||
```
|
||||
|
||||
* Login to Nexus and release the maven repository uploads in the staging area.
|
||||
|
||||
* Upload src and distro zips to sf.net/projects/keycloak. This includes appliance, war-dist, each adapter, and proxy distros. You need to create an adapters folder on sf.net and each uploaded adapter there.
|
||||
|
||||
* Upload documentation to docs.jboss.org
|
||||
```
|
||||
$ sftp keycloak@filemgmt.jboss.org
|
||||
> cd docs_htdocs/keycloak/docs
|
||||
> mkdir 1.0.0.Final (or whatever version)
|
||||
> quit
|
||||
|
||||
$ unzip distribution/examples-docs-zip/target/keycloak-examples-docs-dist.zip
|
||||
$ cd docs
|
||||
$ rsync -rv --protocol=28 * keycloak@filemgmt.jboss.org:/docs_htdocs/keycloak/docs/1.0.0.Final
|
||||
```
|
||||
|
||||
* tag release
|
||||
```
|
||||
$ git tag -a -m "1.0.0.Final" 1.0.0.Final
|
||||
$ git push --tags
|
||||
```
|
||||
|
||||
## Update Bower
|
||||
```
|
||||
$ git clone https://github.com/keycloak/keycloak-js-bower
|
||||
$ cp <keycloak.js from dist> dist/keycloak-js-bower
|
||||
$ cp <keycloak.min.js from dist> dist/keycloak-js-bower
|
||||
```
|
||||
Edit bower.json and set version (include -beta -rc, but not -final). Create tag.
|
||||
|
||||
## Update OpenShift Cartridge
|
||||
|
||||
See https://github.com/keycloak/openshift-keycloak-cartridge for details
|
||||
|
||||
## Update Docker image
|
||||
|
||||
Instructions TBD
|
||||
|
||||
## Maven central
|
||||
|
||||
Releases are automatically synced to Maven central, but this can take up to one day
|
||||
|
||||
## Announce
|
||||
|
||||
* Update Magnolia site to link keycloak docs and announcements.
|
||||
* Write a blog and email about release including links to download, migration guide, docs, and blurb about what's new
|
||||
|
|
@ -8,14 +8,10 @@ The testsuite uses Sellenium. By default it uses the HtmlUnit WebDriver, but can
|
|||
|
||||
To run the tests with Firefox add `-Dbrowser=firefox` or for Chrome add `-Dbrowser=chrome`
|
||||
|
||||
Mongo
|
||||
-----
|
||||
Database
|
||||
--------
|
||||
|
||||
The testsuite is executed with JPA model implementation with data saved in H2 database by default. To run testsuite with Mongo model, just add property `-Dkeycloak.realm.provider=mongo` when executing it.
|
||||
This single property will cause that mongo will be used for realm-model, user-model and audit.
|
||||
|
||||
Note that this will automatically run embedded Mongo database on localhost/27018 and it will stop it after whole testsuite is finished.
|
||||
So you don't need to have Mongo installed on your laptop to run mongo execution tests.
|
||||
By default the testsuite uses an embedded H2 database to test with other databases see (Database Testing)[DatabaseTesting.md].
|
||||
|
||||
Test utils
|
||||
==========
|
||||
|
|
@ -76,4 +76,4 @@ It should be added last to the `DefaultMongoUpdaterProvider#updates` array.
|
|||
Testing database migration
|
||||
--------------------------
|
||||
|
||||
Get the database from an old version of Keycloak that includes the demo applications. Start the server with this and test it.
|
||||
Get the database from an old version of Keycloak that includes the demo applications. Start the server with this and test it.
|
||||
Loading…
Reference in a new issue