github.com/ghodss/etcd@v0.3.1-0.20140417172404-cc329bfa55cb/README.md (about)

     1  # etcd
     2  
     3  README version 0.3.0
     4  
     5  A highly-available key value store for shared configuration and service discovery.
     6  etcd is inspired by [Apache ZooKeeper][zookeeper] and [doozer][doozer], with a focus on being:
     7  
     8  * *Simple*: curl'able user facing API (HTTP+JSON)
     9  * *Secure*: optional SSL client cert authentication
    10  * *Fast*: benchmarked 1000s of writes/s per instance
    11  * *Reliable*: properly distributed using Raft
    12  
    13  etcd is written in Go and uses the [Raft][raft] consensus algorithm to manage a highly-available replicated log.
    14  
    15  See [etcdctl][etcdctl] for a simple command line client.
    16  Or feel free to just use curl, as in the examples below.
    17  
    18  [zookeeper]: http://zookeeper.apache.org/
    19  [doozer]: https://github.com/ha/doozerd
    20  [raft]: http://raftconsensus.github.io/
    21  [etcdctl]: http://github.com/coreos/etcdctl/
    22  
    23  If you're considering etcd for production use, please see: [production-ready.md](./Documentation/production-ready.md)
    24  
    25  ## Getting Started
    26  
    27  ### Getting etcd
    28  
    29  The latest release and setup instructions are available at [GitHub][github-release].
    30  
    31  [github-release]: https://github.com/coreos/etcd/releases/
    32  
    33  
    34  ### Building
    35  
    36  You can build etcd from source:
    37  
    38  ```sh
    39  git clone https://github.com/coreos/etcd
    40  cd etcd
    41  ./build
    42  ```
    43  
    44  This will generate a binary called `./bin/etcd`.
    45  
    46  _NOTE_: you need go 1.2+. Please check your installation with
    47  
    48  ```
    49  go version
    50  ```
    51  
    52  See the [development tools documentation][development-tools] for alternative build methods like using Vagrant.
    53  
    54  [development-tools]: https://github.com/coreos/etcd/blob/master/Documentation/development-tools.md
    55  
    56  ### Running
    57  
    58  First start a single-machine cluster of etcd:
    59  
    60  ```sh
    61  ./bin/etcd
    62  ```
    63  
    64  This will bring up etcd listening on port 4001 for client communication and on port 7001 for server-to-server communication.
    65  
    66  Next, let's set a single key, and then retrieve it:
    67  
    68  ```
    69  curl -L http://127.0.0.1:4001/v2/keys/mykey -XPUT -d value="this is awesome"
    70  curl -L http://127.0.0.1:4001/v2/keys/mykey
    71  ```
    72  
    73  You have successfully started an etcd on a single machine and written a key to the store. Now it's time to dig into the full etcd API and other guides.
    74  
    75  ### Next Steps
    76  
    77  - Explore the full [API][api].
    78  - Set up a [multi-machine cluster][clustering].
    79  - Learn the [config format, env variables and flags][configuration].
    80  - Find [language bindings and tools][libraries-and-tools].
    81  - Learn about the dashboard, lock and leader election [modules][modules].
    82  - Use TLS to [secure an etcd cluster][security].
    83  - [Tune etcd][tuning].
    84  
    85  [api]: https://github.com/coreos/etcd/blob/master/Documentation/api.md
    86  [clustering]: https://github.com/coreos/etcd/blob/master/Documentation/clustering.md
    87  [configuration]: https://github.com/coreos/etcd/blob/master/Documentation/configuration.md
    88  [libraries-and-tools]: https://github.com/coreos/etcd/blob/master/Documentation/libraries-and-tools.md
    89  [modules]: https://github.com/coreos/etcd/blob/master/Documentation/modules.md
    90  [security]: https://github.com/coreos/etcd/blob/master/Documentation/security.md
    91  [tuning]: https://github.com/coreos/etcd/blob/master/Documentation/tuning.md
    92  
    93  ## Contact
    94  
    95  - Mailing list: [etcd-dev](https://groups.google.com/forum/?hl=en#!forum/etcd-dev)
    96  - IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) oon freenode.org
    97  - Planning/Roadmap: [milestones](https://github.com/coreos/etcd/issues/milestones)
    98  - Bugs: [issues](https://github.com/coreos/etcd/issues)
    99  
   100  ## Contributing
   101  
   102  See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
   103  
   104  ## Project Details
   105  
   106  ### Versioning
   107  
   108  #### Service Versioning
   109  
   110  etcd uses [semantic versioning](http://semver.org)
   111  New minor versions may add additional features to the API.
   112  
   113  You can get the version of etcd by issuing a request to /version:
   114  
   115  ```sh
   116  curl -L http://127.0.0.1:4001/version
   117  ```
   118  
   119  #### API Versioning
   120  
   121  Clients are encouraged to use the `v2` API. The `v1` API will not change.
   122  
   123  The `v2` API responses should not change after the 0.2.0 release but new features will be added over time.
   124  
   125  During the pre-v1.0.0 series of releases we may break the API as we fix bugs and get feedback.
   126  
   127  ### License
   128  
   129  etcd is under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.