Skip to content

Commit

Permalink
Merge branch 'docs/readme/development' into next
Browse files Browse the repository at this point in the history
  • Loading branch information
@thibaultcha
thibaultcha committed Dec 24, 2015
2 parents 3da4dff + f95a34a commit 88f2930
Show file tree
Hide file tree
Showing 2 changed files with 113 additions and 49 deletions.
20 changes: 4 additions & 16 deletions Makefile
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
TESTING_CONF = kong_TEST.yml
DEVELOPMENT_CONF = kong_DEVELOPMENT.yml
DEV_ROCKS=busted luacov luacov-coveralls luacheck
DEV_ROCKS = busted luacov luacov-coveralls luacheck

.PHONY: install dev clean start restart seed drop lint test test-integration test-plugins test-all coverage
.PHONY: install dev clean doc lint test test-integration test-plugins test-all coverage

install:
@if [ `uname` = "Darwin" ]; then \
Expand Down Expand Up @@ -32,20 +32,8 @@ clean:
rm -f luacov.*
rm -rf nginx_tmp

start:
@bin/kong start -c $(DEVELOPMENT_CONF)

stop:
@bin/kong stop -c $(DEVELOPMENT_CONF)

restart:
@bin/kong restart -c $(DEVELOPMENT_CONF)

seed:
@bin/kong db -c $(DEVELOPMENT_CONF) seed

drop:
@bin/kong db -c $(DEVELOPMENT_CONF) drop
doc:
@ldoc -c config.ld kong

lint:
@find kong spec -name '*.lua' -not -name 'invalid-module.lua' -not -path 'kong/vendor/*' | xargs luacheck -q
Expand Down
142 changes: 109 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Microservice & API Management Layer
[![][kong-logo]][kong-url]

Kong runs in production at [Mashape](https://www.mashape.com) to secure, manage and extend over [15,000 APIs](http://stackshare.io/mashape/how-mashape-manages-over-15-000-apis-microservices), while handling billions of requests per month. Kong is backed by the battle-tested **NGINX** with a focus on scalability, high performance & reliability.
Kong runs in production at [Mashape][mashape-url] to secure, manage and extend over [15,000 APIs](http://stackshare.io/mashape/how-mashape-manages-over-15-000-apis-microservices), while handling billions of requests per month. Kong is backed by the battle-tested **NGINX** with a focus on scalability, high performance & reliability.

[Website](http://getkong.org) |
[Documentation](http://getkong.org/docs) |
[Installation](http://getkong.org/install) |
[Website][kong-url] |
[Documentation](https://getkong.org/docs) |
[Installation](https://getkong.org/install) |
[Mailing List][google-groups-url] |
[Gitter Chat][gitter-url] |
freenode: [#kong](http://webchat.freenode.net/?channels=kong)
Expand Down Expand Up @@ -56,7 +56,7 @@ If you're building for web, mobile or IoT (Internet of Things) you will likely e

## Benchmarks

We've load tested Kong and Cassandra on AWS; you can see our [benchmark report here](http://getkong.org/about/benchmark/).
We've load tested Kong and Cassandra on AWS; you can see our [benchmark report here](https://getkong.org/about/benchmark/).

## Distributions

Expand Down Expand Up @@ -112,7 +112,6 @@ Tools:
- [Kong with Instaclustr](https://www.instaclustr.com/products/kong/)
- [.NET Client for Kong](https://www.nuget.org/packages/Kong/0.0.4)


## Roadmap

You can find a detailed Roadmap of Kong on the [Wiki](https://github.com/Mashape/kong/wiki).
Expand All @@ -121,57 +120,134 @@ You can find a detailed Roadmap of Kong on the [Wiki](https://github.com/Mashape

If you are planning on developing on Kong, you'll need a development installation. The `next` branch holds the latest unreleased source code.

You can read more about writing your own plugins in the [Plugin Development Guide](https://getkong.org/docs/latest/plugin-development/), or browse an online version of Kong's source code documentation in the [Public Lua API Reference](https://getkong.org/docs/0.5.x/lua-reference/).
You can read more about writing your own plugins in the [Plugin Development Guide](https://getkong.org/docs/latest/plugin-development/), or browse an online version of Kong's source code documentation in the [Public Lua API Reference](https://getkong.org/docs/latest/lua-reference/).

#### Vagrant

You can use a Vagrant box running Kong and Cassandra that you can find at [Mashape/kong-vagrant](https://github.com/Mashape/kong-vagrant).

#### Source Install

First, you will need to already have Kong installed. Install Kong by following one of the methods described at [getkong.org/download](http://getkong.org/download). Then, make sure you have downloaded [Cassandra](http://cassandra.apache.org/download/) and that it is running. These steps will override your Kong installation with the latest source code:
First, you will need to already have Kong installed. Install Kong by following one of the methods described at [getkong.org/download](https://getkong.org/download). Then, make sure you have downloaded [Cassandra](http://cassandra.apache.org/download/) and that it is running. These steps will override your Kong installation with the latest source code:

```shell
# clone the repo and use the next branch
$ git clone https://github.com/Mashape/kong
$ cd kong/

# You might want to switch to the development branch. See CONTRIBUTING.md for more infos
$ git checkout next

# Build and install Kong globally using Luarocks, overriding the version previously installed
$ [sudo] make install
# Install latest Kong globally using Luarocks, overriding the version previously installed
$ make install
```

#### Running for development

It is best to run Kong with a development configuration file. Such a file can easily be created following those instructions:

```shell
# Install all development dependencies and create your environment configuration files
$ make dev

# Finally, run Kong with the just created development configuration
$ kong start -c kong_DEVELOPMENT.yml
```

The `lua_package_path` directive in the configuration specifies that the Lua code in your local folder will be used in favor of the system installation. The `lua_code_cache` directive being turned off, you can start Kong, edit your local files, and test your code without restarting Kong.
Since you use a configuration file dedicated to development, feel free to customize it as you wish. For example, the one generated by `make dev` includes the following changes: the [`lua_package_path`](https://github.com/openresty/lua-nginx-module#lua_package_path) directive specifies that the Lua modules in your current directory will be used in favor of the system installation. The [`lua_code_cache`](https://github.com/openresty/lua-nginx-module#lua_code_cache) directive being turned off, you can start Kong, edit your local files, and test your code without restarting Kong.

To stop Kong, you will need to specify the configuration file too:

```shell
$ kong stop -c kong_DEVELOPMENT.yml
# or
$ kong reload -c kong_DEVELOPMENT.yml
```

Learn more about the CLI and configuration options in the [documentation](https://getkong.org/docs/latest/cli/).

#### Tests

Kong relies on three test suites:

* Unit tests
* Integration tests, which require a running Cassandra cluster
* Plugins tests, which are a mix of unit and integration tests, which also require a Cassandra cluster

The first can simply be run after installing [busted](https://github.com/Olivine-Labs/busted) and running:

```
$ busted spec/unit
```

The integration tests require you to have a configuration file at `./kong_TEST.yml` and to make it point to a running Cassandra cluster (it will use a keyspace of its own). Such a file is also created by `make dev`, but you can create one of your own or customize it (you might want to change the logging settings, for example):

#### Makefile Operations
```
$ busted spec/integration
```

The `make dev` command can create a default `kong_TEST.yml` file.

The plugins tests also require a `./kong_TEST.yml` file and a running Cassandra cluster, and be be run with:

```
$ busted spec/plugins
```

When developing, use the `Makefile` for doing the following operations:
Finally, all suites can be run at once by simply running `busted`.

| Name | Description |
| -------------:| -------------------------------------------------------------------------|
| `install` | Install the Kong luarock globally |
| `dev` | Setup your development environment |
| `clean` | Clean your development environment |
| `start` | Start the `DEVELOPMENT` environment (`kong_DEVELOPMENT.yml`) |
| `restart` | Restart the `DEVELOPMENT` environment (`kong_DEVELOPMENT.yml`) |
| `seed` | Seed the `DEVELOPMENT` environment (`kong_DEVELOPMENT.yml`) |
| `drop` | Drop the `DEVELOPMENT` environment (`kong_DEVELOPMENT.yml`) |
| `lint` | Lint Lua files in `kong/` and `spec/` |
| `test` | Run the unit tests |
| `test-integration` | Run the integration tests (Kong + DAO) |
| `test-plugins` | Run unit + integration tests of all plugins |
| `test-all` | Run all unit + integration tests at once |
| `coverage` | Run all tests + coverage report |
#### Tools

Various tools are used for documentation and code quality. They can all be easily installed by running:

```
$ make dev
```

Code coverage is analyzed by [luacov](http://keplerproject.github.io/luacov/) from the busted **unit tests**:

```
$ busted --coverage
$ luacov kong
# or
$ make coverage
```

The code is statically analyzed and linted by [luacheck](https://github.com/mpeterv/luacheck). It is easier to use the Makefile to run it:

```
$ make lint
```

The documentation is written according to the [ldoc](https://github.com/stevedonovan/LDoc) format and can be generated with:

```
$ ldoc -c config.ld kong/
# or
$ make doc
```

We maintain this documentation on the [Public Lua API Reference](https://getkong.org/docs/latest/lua-reference/) so it is unlikely that you will have to generate it, but it is useful to keep that information in mind when documenting your modules if you wish to contribute.

#### Makefile

When developing, you can use the `Makefile` for doing the following operations:

| Name | Description |
| ------------------:| --------------------------------------------------------|
| `install` | Install the Kong luarock globally |
| `dev` | Setup your development environment |
| `clean` | Clean your development environment |
| `doc` | Generate the ldoc documentation |
| `lint` | Lint Lua files in `kong/` and `spec/` |
| `test` | Run the unit tests suite |
| `test-integration` | Run the integration tests suite |
| `test-plugins` | Run the plugins test suite |
| `test-all` | Run all unit + integration tests at once |
| `coverage` | Run all tests + coverage report |

## Enterprise Support

Support, Demo, Training, API Certifications and Consulting available at http://getkong.org/enterprise.
Support, Demo, Training, API Certifications and Consulting available at https://getkong.org/enterprise.

## License

Expand All @@ -191,14 +267,14 @@ See the License for the specific language governing permissions and
limitations under the License.
```

[kong-url]: http://getkong.org/
[kong-url]: https://getkong.org/
[mashape-url]: https://www.mashape.com

[kong-logo]: http://i.imgur.com/4jyQQAZ.png
[kong-benefits]: http://cl.ly/image/1B3J3b3h1H1c/Image%202015-07-07%20at%206.57.25%20PM.png

[mashape-url]: https://www.mashape.com

[gitter-url]: https://gitter.im/Mashape/kong
[gitter-badge]: https://img.shields.io/badge/Gitter-Join%20Chat-blue.svg

[google-groups-url]: https://groups.google.com/forum/#!forum/konglayer

0 comments on commit 88f2930

Please sign in to comment.