From a785bc26538c4c7ff2c0769f95ef8ee102f744f7 Mon Sep 17 00:00:00 2001 From: Michael Krotscheck Date: Mon, 19 Feb 2018 20:05:51 -0800 Subject: [PATCH 1/3] New configuration section This section includes all of our commandline flags, as well as references to extended documentation (such as hibernate). --- content/about.md | 7 ++-- content/basics.md | 1 - content/configuration.md | 72 ++++++++++++++++++++++++++++++++++++++++ content/oauth2.md | 3 +- 4 files changed, 76 insertions(+), 7 deletions(-) create mode 100644 content/configuration.md diff --git a/content/about.md b/content/about.md index a3a1e1b..5919d2e 100644 --- a/content/about.md +++ b/content/about.md @@ -3,7 +3,6 @@ title: About the Project menu: main: weight: 200 - name: "About the Project" --- ## Contributing @@ -17,13 +16,13 @@ being duplicated, please reach out the the community in the [IRC Channel](http:/ The project adheres to several philosophies that impact our design decisions and architecture. -#### Secure by Default +### Secure by Default In order to encourage a safe and secure internet, the project will default to the most secure configuration. This is to address both overtaxed engineers and operators, as many do not have the time to read all the documentation, or test all the configurations. -#### Test Everything +### Test Everything We expect 100% test coverage. While we understand that this does not necessarily guarantee good tests, it does force a contributing engineer to @@ -31,7 +30,7 @@ think through edge cases in a way that might otherwise be skipped. It also puts us in a mindset to write testable code, and thus has a substantial impact on our project's internal plumbing. -#### Choose Boring Technology +### Choose Boring Technology We adhere to the doctrine of [Choose Boring Technology](http://mcfunley.com/choose-boring-technology). This is done mostly out of a need for project and engineer sanity sanity; if development, diff --git a/content/basics.md b/content/basics.md index 1185082..f2d333f 100644 --- a/content/basics.md +++ b/content/basics.md @@ -3,7 +3,6 @@ title: API Basics menu: main: weight: 20 - name: "API Basics" --- ### Required Headers diff --git a/content/configuration.md b/content/configuration.md new file mode 100644 index 0000000..842609e --- /dev/null +++ b/content/configuration.md @@ -0,0 +1,72 @@ +--- +title: Configuration +menu: + main: + weight: 15 +--- +Kangaroo attempts to provide an out-of-the-box "sane default" configuration for development purposes only, yet provides +all the necessary configuration hooks for true, highly-available deployments. Below is a comprehensive list of our +direct configuration options, as well as the current defaults. + +## Basic Configuration + +| Commandline Flag | Default | Description | +|--------------------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------| +| `--kangaroo.host` | `127.0.0.1` | The IP address to which this server will bind itself. | +| `--kangaroo.port` | `8080` | The port on which this server will listen. | +| `--kangaroo.working_dir` | `~/.kangaroo` | The filesystem path used for the server's working directory. | +| `--kangaroo.html_app_root` | | Filesystem path to the directory to use as our HTML5 Application root. If not set, the server will not attempt to host an application. | + +## SSL Certificates + +| Commandline Flag | Default | Description | +|--------------------------------|---------------|----------------------------------------------------------------------------------------------------------------------------------------| +| `--kangaroo.keystore_path` | | Path to an external keystore which contains your server certificates. | +| `--kangaroo.keystore_password` | `kangaroo` | The keystore's own password. | +| `--kangaroo.keystore_type` | `PKCS12` | The keystore's type. For a list of options, please refer to `java.security.Keystore` | +| `--kangaroo.cert_alias` | `kangaroo` | The alias of the server certificate to use from the keystore. | +| `--kangaroo.cert_key_password` | `kangaroo` | The password for server certificate's private key. | + +## Database + +Rather than provide custom options to configure our ORM (hibernate), kangaroo instead passes all system properties to +Hibernate directly, including Hibernate's Search. For specific configuration options, please refer to the +[hibernate documentation](http://hibernate.org/orm/documentation) or the [hibernate search documentation](http://hibernate.org/search/documentation/). +Specific, popular database configuration options are listed below. + +### H2 (Default) + +By default, Kangaroo creates an on-disk H2 database. This is mostly for testing and local development purposes, and we +do not recommend using this configuration at scale. The default options are listed below: + +| Commandline Flag | Default | Description | +|---------------------------------------|------------------------------------|------------------------------------------------------| +| `-Dhibernate.connection.url` | `jdbc:h2:file://~/.kangaroo/h2.db` | The JDBC connection string for the database. | +| `-Dhibernate.connection.username` | `oid` | Database user. | +| `-Dhibernate.connection.password` | `oid` | Database password. | +| `-Dhibernate.connection.driver_class` | `org.h2.Driver` | The Driver class to use for the database connection. | +| `-Dhibernate.connection.dialect` | `org.hibernate.dialect.H2Dialect` | The database SQL dialect implementation class. | + +### MariaDB / MySQL + +If you'd like to connect to a MySQL-compatible database instead, the below options should provide a good starting point. +Note that Kangaroo comes packaged only with the MariaDB driver, as the MySQL driver does not meet our licensing guidelines. +You will need to provide a database-specific driver via your system's JVM if this does not work for you. + +| Commandline Flag | Default | +|---------------------------------------|------------------------------------------------------------| +| `-Dhibernate.connection.url` | `jdbc:mariadb://127.0.0.1:3306/my_database?useUnicode=yes` | +| `-Dhibernate.connection.username` | `my_username` | +| `-Dhibernate.connection.password` | `my_password` | +| `-Dhibernate.connection.driver_class` | `org.mariadb.jdbc.Driver` | +| `-Dhibernate.connection.dialect` | `org.hibernate.dialect.MariaDBDialect` | + +### Lucene Index + +Kangaroo makes use of an on-disk lucene index for its search features. Truly highly-available configurations are currently +being considered for development. + +| Commandline Flag | Default | Description | +|-------------------------------------------------|------------------------------|-----------------------------------------------| +| `-Dhibernate.search.default.directory_provider` | `filesystem` | The lucene index provider to use. | +| `-Dhibernate.search.default.indexBase` | `~/.kangaroo/lucene_indexes` | Root directory for a lucene filesystem index. | \ No newline at end of file diff --git a/content/oauth2.md b/content/oauth2.md index eee739f..bc3c057 100644 --- a/content/oauth2.md +++ b/content/oauth2.md @@ -1,7 +1,6 @@ --- -title: OAuth2 +title: "API: OAuth2" menu: main: weight: 24 - name: "API: OAuth2" --- \ No newline at end of file From 7add9a0acd5bef3d590e0e2bcd9a6683bc438948 Mon Sep 17 00:00:00 2001 From: Michael Krotscheck Date: Mon, 19 Feb 2018 20:59:34 -0800 Subject: [PATCH 2/3] Added slack notification Use the shared jenkins library to send build status updates to slack. --- Jenkinsfile | 30 +----------------------------- 1 file changed, 1 insertion(+), 29 deletions(-) diff --git a/Jenkinsfile b/Jenkinsfile index 30891cc..7e53a70 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -75,35 +75,7 @@ pipeline { */ changed { script { - def buildStatus = currentBuild.currentResult - def url = env.BUILD_URL, message, color - - if (env.CHANGE_URL && buildStatus == 'SUCCESS') { - url = env.CHANGE_URL - } - - switch (buildStatus) { - case 'FAILURE': - message = "Build <${url}|${env.JOB_NAME}> failed." - color = '#AA0000' - break - case 'SUCCESS': - message = "Build <${url}|${env.JOB_NAME}> passed." - color = '#00AA00' - break - case 'UNSTABLE': - default: - message = "Build <${url}|${env.JOB_NAME}> unstable." - color = '#FFAA00' - } - - slackSend( - channel: '#build-notifications', - tokenCredentialId: 'kangaroo-server-slack-id', - teamDomain: 'kangaroo-server', - color: color, - message: message - ) + notifySlack(currentBuild.currentResult) } } From 58392ce4dcee9d04cc8a2941f386d7b54c32d382 Mon Sep 17 00:00:00 2001 From: Michael Krotscheck Date: Fri, 2 Mar 2018 08:05:51 -0800 Subject: [PATCH 3/3] Added badges This patch adds the code coverage, test, and vulnerability badges to the head of our documentation. --- content/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/index.md b/content/index.md index 835ca0a..ecafcea 100644 --- a/content/index.md +++ b/content/index.md @@ -6,6 +6,7 @@ menu: weight: 1 name: "Welcome" --- +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/net.krotscheck/kangaroo/badge.svg)](https://maven-badges.herokuapp.com/maven-central/net.krotscheck/kangaroo) [![Build Status](https://jenkins.krotscheck.net/buildStatus/icon?job=Kangaroo/kangaroo/develop)](https://jenkins.krotscheck.net/job/Kangaroo/job/kangaroo/job/develop) [![Jenkins tests](https://img.shields.io/jenkins/t/https/jenkins.krotscheck.net/job/Kangaroo/job/kangaroo/job/develop.svg)](https://jenkins.krotscheck.net/job/Kangaroo/job/kangaroo/job/develop/) [![Known Vulnerabilities](https://snyk.io/test/github/kangaroo-server/kangaroo/badge.svg?targetFile=/pom.xml)](https://snyk.io/test/github/kangaroo-server/kangaroo?targetFile=/pom.xml) Kangaroo is an open source, multi-tenant, OAuth2 Authorization server. It fully supports [RFC 6749](https://tools.ietf.org/html/rfc6749) (The original OAuth2 Specification), and aspires to