1 files changed, 179 insertions, 0 deletions
diff --git a/charms/trusty/cassandra/README.md b/charms/trusty/cassandra/README.md
new file mode 100644
index 0000000..00784cc
--- /dev/null
+++ b/charms/trusty/cassandra/README.md
@@ -0,0 +1,179 @@
+# Overview
+
+The Apache Cassandra database is the right choice when you need scalability
+and high availability without compromising performance. Linear scalability
+and proven fault-tolerance on commodity hardware or cloud infrastructure
+make it the perfect platform for mission-critical data. Cassandra's support
+for replicating across multiple datacenters is best-in-class, providing lower
+latency for your users and the peace of mind of knowing that you can survive
+regional outages.
+
+See [cassandra.apache.org](http://cassandra.apache.org) for more information.
+
+
+# Editions
+
+This charm supports Apache Cassandra 2.0, 2.1, 2.2 & 3.0, and
+Datastax Enterprise 4.7 & 4.8. The default is Apache Cassandra 2.2.
+
+To use Apache Cassandra 2.0, specify the Apache Cassandra 2.0 archive source
+in the `install_sources` config setting when deploying.
+
+To use Datastax Enterprise, set the `edition` config setting to `dse`
+and the Datastax Enterprise archive URL in `install_sources` (including your
+username and password).
+
+
+# Deployment
+
+Cassandra deployments are relatively simple in that they consist of a set of
+Cassandra nodes which seed from each other to create a ring of servers:
+    
+    juju deploy -n3 cs:trusty/cassandra
+
+The service units will deploy and will form a single ring.
+
+New nodes can be added to scale up:
+
+    juju add-unit cassandra
+
+
+/!\ Nodes must be manually decommissioned before dropping a unit.
+
+    juju run --unit cassandra/1 "nodetool decommission"
+    # Wait until Mode is DECOMMISSIONED
+    juju run --unit cassandra/1 "nodetool netstats"
+    juju remove-unit cassandra/1
+
+It is recommended to deploy at least 3 nodes and configure all your
+keyspaces to have a replication factor of three. Using fewer nodes or
+neglecting to set your keyspaces' replication settings means that your
+data is at risk and availability lower, as a failed unit may take the
+only copy of data with it.
+
+Production systems will normally want to set `max_heap_size` and
+`heap_newsize` to the empty string, to enable automatic memory size
+tuning. The defaults have been chosen to be suitable for development
+environments but will perform poorly with real workloads.
+
+
+## Planning
+
+- Do not attempt to store too much data per node. If you need more space,
+  add more nodes. Most workloads work best with a capacity under 1TB
+  per node.
+
+- You need to keep 50% of your disk space free for Cassandra maintenance
+  operations. If you expect your nodes to hold 500GB of data each, you
+  will need a 1TB partition. Using non-default compaction such as
+  LeveledCompactionStrategy can lower this waste.
+
+- Much more information can be found in the [Cassandra 2.2 documentation](http://docs.datastax.com/en/cassandra/2.2/cassandra/planning/planPlanningAbout.html)
+
+
+## Network Access
+
+The default Cassandra packages are installed from the apache.org
+archive. To avoid this download, place a copy of the packages in a local
+archive and specify its location in the `install_sources` configuration
+option. The signing key is automatically added.
+
+When using DataStax Enterprise, you need to specify the archive location
+containing the DataStax Enterprise .deb packages in the
+`install_sources` configuration item, and the signing key in the
+`install_keys` configuration item. Place the DataStax packages in a
+local archive to avoid downloading from datastax.com.
+
+
+## Oracle Java SE
+
+Cassandra recommends using Oracle Java SE 8. Unfortunately, this
+software is accessible only after accepting Oracle's click-through
+license making deployments using it much more cumbersome. You will need
+to download the Oracle Java SE 8 Server Runtime for Linux, and place the
+tarball at a URL accessible to your deployed units. The config item
+`private_jre_url` needs to be set to this URL.
+
+
+# Usage
+
+To relate the Cassandra charm to a service that understands how to talk to
+Cassandra using Thrift or the native Cassandra protocol::
+
+    juju deploy cs:service-that-needs-cassandra
+    juju add-relation service-that-needs-cassandra cassandra:database
+
+
+Alternatively, if you require a superuser connection, use the
+`database-admin` relation instead of `database`::
+
+    juju deploy cs:admin-service
+    juju add-relation admin-service cassandra:database-admin
+
+
+Client charms need to provide nothing. The Cassandra service publishes the
+following connection settings and cluster information on the client's relation:
+
+`username` and `password`:
+
+    Authentication credentials. The cluster is configured to use
+    the standard PasswordAuthenticator authentication provider, rather
+    than the insecure default. You can use different credentials
+    if you wish, using an account created through some other mechanism.
+
+`host`:
+
+    IP address to connect to.
+
+`native_transport_port`:
+
+    Port for drivers and tools using the newer native protocol.
+
+`rpc_port`:
+
+    Port for drivers and tools using the legacy Thrift protocol.
+
+`cluster_name`:
+
+    The cluster name. A client service may be related to several
+    Cassandra services, and this setting may be used to tell which
+    services belong to which cluster.
+
+`datacenter` and `rack`:
+
+    The datacenter and rack units in this service belong to. Required for
+    setting keyspace replication correctly.
+
+The cluster is configured to use the recommended 'snitch'
+(GossipingPropertyFileSnitch), so you will need to configure replication of
+your keyspaces using the NetworkTopologyStrategy replica placement strategy.
+For example, using the default datacenter named 'juju':
+
+    CREATE KEYSPACE IF NOT EXISTS mydata WITH REPLICATION =
+    { 'class': 'NetworkTopologyStrategy', 'juju': 3};
+
+
+Although authentication is configured using the standard
+PasswordAuthentication, by default no authorization is configured
+and the provided credentials will have access to all data on the cluster.
+For more granular permissions, you will need to set the authorizer
+in the service configuration to CassandraAuthorizer and manually grant
+permissions to the users.
+
+
+# Known Limitations and Issues
+
+This is the 'trusty' charm. Upgrade from the 'precise' charm is not supported.
+
+The `system_auth` keyspace replication factor is automatically increased
+but not decreased. If you have a service with three or more units and
+decommission enough nodes to drop below three, you will need to manually
+update the `system_auth` keyspace replication settings.
+
+
+# Contact Information
+
+## Cassandra
+
+- [Apache Cassandra homepage](http://cassandra.apache.org/)
+- [Cassandra Getting Started](http://wiki.apache.org/cassandra/GettingStarted)