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) } } 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/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 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