Skip to content

Documentation changes for release 1.3.0 #3

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
krotscheck wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Documentation changes for release 1.3.0 #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a785bc2
New configuration section
krotscheck Feb 20, 2018
7add9a0
Added slack notification
krotscheck Feb 20, 2018
58392ce
Added badges
krotscheck Mar 2, 2018
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
30 changes: 1 addition & 29 deletions Jenkinsfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}

Expand Down
7 changes: 3 additions & 4 deletions content/about.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ title: About the Project
menu:
main:
weight: 200
name: "About the Project"
---

## Contributing
Expand All @@ -17,21 +16,21 @@ 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
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,
Expand Down
1 change: 0 additions & 1 deletion content/basics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ title: API Basics
menu:
main:
weight: 20
name: "API Basics"
---

### Required Headers
Expand Down
72 changes: 72 additions & 0 deletions content/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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. |
1 change: 1 addition & 0 deletions content/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 1 addition & 2 deletions content/oauth2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,6 @@
---
title: OAuth2
title: "API: OAuth2"
menu:
main:
weight: 24
name: "API: OAuth2"
---