github.com/jpetazzo/etcd@v0.2.1-0.20140113055439-97f1363afac5/README.md (about)

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