From bfc114bc1de89c996d07961eaa39794053238480 Mon Sep 17 00:00:00 2001 From: John Dickinson Date: Wed, 12 Sep 2012 21:44:44 -0700 Subject: [PATCH] new more helpful README Change-Id: Ie5e88178e061955aea8759e5451a2d33ccc76511 --- README | 17 ------------ README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+), 17 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index cbeaf59e31..0000000000 --- a/README +++ /dev/null @@ -1,17 +0,0 @@ -Swift ------ - -A distributed object store that was originally developed as the basis for -Rackspace's Cloud Files. - -To build documentation run `python setup.py build_sphinx`, and then browse to -/doc/build/html/index.html. - -The best place to get started is the "SAIO - Swift All In One", which will walk -you through setting up a development cluster of Swift in a VM. - -For more information, visit us at http://launchpad.net/swift, or come hang out -on our IRC channel, #openstack on freenode. - --- -Swift Development Team diff --git a/README.md b/README.md new file mode 100644 index 0000000000..a839dd6fcc --- /dev/null +++ b/README.md @@ -0,0 +1,83 @@ +# Swift + +A distributed object storage system designed to scale from a single machine +to thousands of servers. Swift is optimized for multi-tenancy and high +concurrency. Swift is ideal for backups, web and mobile content, and any other +unstructured data that can grow without bound. + +Swift provides a simple, REST-based API fully documented at +http://doc.openstack.org/. + +Swift was originally developed as the basis for Rackspace's Cloud Files and +was open-sourced in 2010 as part of the OpenStack project. It has since grown +to include contributions from many companies and has spawned a thriving +ecosystem of 3rd party tools. Swift's contributors are listed in the AUTHORS +file. + +## Docs + +To build documentation install sphinx (`pip install sphinx`), run +`python setup.py build_sphinx`, and then browse to /doc/build/html/index.html. +These docs are auto-generated after every commit and available online at +http://docs.openstack.org/developer/swift/. + +## For Developers + +The best place to get started is the ["SAIO - Swift All In One"](http://docs.openstack.org/developer/swift/development_saio.html). +This document will walk you through setting up a development cluster of Swift +in a VM. The SAIO environment is ideal for running small-scale tests against +swift and trying out new features and bug fixes. + +You can run unit tests with `.unittests` and functional tests with +`.functests`. + +### Code Organization + + * bin/: Executable scripts that are the processes run by the deployer + * doc/: Documentation + * etc/: Sample config files + * swift/: Core code + * account/: account server + * common/: code shared by different modules + * middleware/: "standard", officially-supported middleware + * ring/: code implementing Swift's ring + * container/: container server + * obj/: object server + * proxy/: proxy server + * test/: Unit and functional tests + +### Data Flow + +Swift is a WSGI application and uses eventlet's WSGI server. After the +processes are running, the entry point for new requests is the `Application` +class in `swift/proxy/server.py`. From there, a controller is chosen, and the +request is processed. The proxy may choose to forward the request to a back- +end server. For example, the entry point for requests to the object server is +the `ObjectController` class in `swift/obj/server.py`. + + +## For Deployers + +Deployer docs are also available at +http://docs.openstack.org/developer/swift/. A good starting point is at +http://docs.openstack.org/developer/swift/deployment_guide.html + +You can run functional tests against a swift cluster with `.functests`. These +functional tests require `/etc/swift/test.conf` to run. A sample config file +can be found in this source tree in `test/sample.conf`. + +## For Client Apps + +For client applications, official Python language bindings are provided at +http://github.com/openstack/python-swiftclient. + +Complete API documentation at +http://docs.openstack.org/api/openstack-object-storage/1.0/content/ + +---- + +For more information come hang out in #openstack-swift on freenode. + +Thanks, + +The Swift Development Team