Permalink
Browse files

Updated README and added example configuration

  • Loading branch information...
1 parent f296f0a commit d83279a2e2138452d4b41b50fdce5487f1e425c1 @kelvl kelvl committed Apr 28, 2013
Showing with 127 additions and 61 deletions.
  1. +6 −0 AUTHORS.md
  2. +22 −0 LICENSE
  3. +59 −61 README.md
  4. +40 −0 application.conf.example
View
@@ -0,0 +1,6 @@
+## Contributors
+
+We'd like to thank the following people who have contributed to this project.
+
+- Beau Gunderson <beau@beaugunderson.com>
+- Kelvin Law <kelvin@twilio.com>
View
22 LICENSE
@@ -0,0 +1,22 @@
+Copyright (c) 2012 Twilio, Inc.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
View
120 README.md
@@ -9,98 +9,96 @@ Shadowing deployments allows users to assert expected behaviors on the new codeb
Shadow comes with a UI that allows users to monitor the stream of requests live.
-All request and responses are also logged in as a JSON (Default: log/shadow-results.log) for easy parsing and analysis.
+## Requirements
-For more information, check out our blog post on Shadow in the coming week.
+1. Java 1.6+
+2. SBT 0.12.1+
-## Installing
-
-No escalated privledges needed unless you are using privileged ports. This will install the core libraries into your site-packages directory.
+## Building
- python setup.py install
+1. Clone the repository: `git clone https://github.com/twilio/shadow.git`
+2. Build the JAR: `sbt assembly`
-## Configuring
+This generates an assembled Jar with all dependencies in `/target/shadow-assembly-<VERSION>.jar`
-There are 2 bundled configuration files:
-debug_shadow.conf.py - for local development and debugging
+## Installing
-shadow.conf.py - for running a shadow service
+No escalated privledges needed unless you are using privileged ports. Just copy the Jar built in the previous step on to your existing server.
-```python
+## Configuring
-# Shadow specific configuration
+Make a copy of the example configuration `application.conf.example` and change the settings to fit your environment.
-ui = {
- # port and address for the UI
- 'port': 9000,
- 'address': '0.0.0.0',
-}
-proxy = {
+## Shadow specific configuration
- # address and port shadow runs on
- 'address': '0.0.0.0',
- 'port': 8081,
- # server running the old versions of the code
- 'old_servers': ['http://localhost:8081/'],
-
- # timeout values to use when making requests to old server
- 'old_servers_timeout': 15.0,
+```
+akka {
+ loglevel = INFO
+}
- # Additional parameters that we want to add
- # when making requests to the old server.
- # These will overwrite the existing params in the request
-
- 'old_servers_additional_get_params': [],
- 'old_servers_additional_post_params': [],
- 'old_servers_additional_headers': [],
+shadow {
+ version = "0.1-SNAPSHOT"
+
+ # host and port to listen to incoming requests
+ proxy-host = localhost
+ proxy-port = 8000
+
+ # host and port for the ui
+ ui-host = localhost
+ ui-port = 8081
+
+ # host and port of the service we are transitioning from
+ # shadow returns responses from this host
+ trueServer {
+ host = "httpbin.org"
+ port = 80
+ }
+
+ # host and port of the service we are transitioning to
+ shadowServer {
+ host = "httpbin.org"
+ port = 80
+ }
+}
- # same parameters can be used for the new server
- 'new_servers': ['http://localhost:8081/'],
- 'new_servers_timeout': 15.0,
+spray.can.server {
+ server-header = shadow-server/${shadow.version}
- 'new_servers_additional_get_params': [],
- 'new_servers_additional_post_params': [],
- 'new_servers_additional_headers': [],
+ # max request timeout
+ request-timeout = 15s
+ stats-support = true
}
+spray.can.client {
+ user-agent-header = shadow/${shadow.version}
+}
```
-There are also Gingko specific configuration parameters for managing service and daemonization.
-
-Check out Ginkgo's [docs](http://ginkgo.readthedocs.org/en/latest/index.html) for more information on running Ginkgo services
-
## Running
-Local development execution can be done with:
-
- ginkgo debug_shadow.conf.py
-
-Server execution should be done with:
-
- ginkgoctl shadow.conf.py start
+Running `java -jar -Dconfig.file=application.conf shadow-assembly-<VERSION>.jar` will start the server in the foreground.
-Be default, the UI can be accessed at [http://localhost:9000](http://localhost:9000)
+We recommend using a supervisor such as `jsvc` or `runit` to manage running shadow
-##Testing
+Be default, the UI can be accessed at [http://localhost:8081](http://localhost:8081)
-Tests are in the `tests` directory. Run them using nose
+## Testing
- nosetests tests/
+Tests are found under `src/main/test/scala/`
-##Build Status
-[![Build Status](https://secure.travis-ci.org/twilio/shadow.png)](http://travis-ci.org/twilio/shadow)
+To run them, use: `sbt test`
+## Build Status
+[![Build Status](https://secure.travis-ci.org/kelvl/shadow.png)](http://travis-ci.org/kelvl/shadow)
## Based upon
-* [Ginkgo](https://github.com/progrium/ginkgo)
-* [Gevent](http://www.gevent.org/)
-* [Flask](http://flask.pocoo.org/)
-* [Gevent-socketio](https://github.com/abourget/gevent-socketio)
-* [Socketio](http://socket.io/)
* [AngularJS](http://angularjs.org/)
* [jsdiff](https://github.com/kpdecker/jsdiff)
+* [Scala](http://www.scala.org)
+* [Spray](http://www.spray.io)
+* [Akka](http://www.akka.io)
View
@@ -0,0 +1,40 @@
+akka {
+ loglevel = INFO
+}
+
+shadow {
+ version = "0.1-SNAPSHOT"
+
+ # host and port to listen to incoming requests
+ proxy-host = localhost
+ proxy-port = 8000
+
+ # host and port for the ui
+ ui-host = localhost
+ ui-port = 8081
+
+ # host and port of the service we are transitioning from
+ # shadow returns responses from this host
+ trueServer {
+ host = "httpbin.org"
+ port = 80
+ }
+
+ # host and port of the service we are transitioning to
+ shadowServer {
+ host = "httpbin.org"
+ port = 80
+ }
+}
+
+spray.can.server {
+ server-header = shadow-server/${shadow.version}
+
+ # max request timeout
+ request-timeout = 15s
+ stats-support = true
+}
+
+spray.can.client {
+ user-agent-header = shadow/${shadow.version}
+}

0 comments on commit d83279a

Please sign in to comment.