Dear Wiki user, You have subscribed to a wiki page or wiki category on "Cassandra Wiki" for change notification.
The "GettingStarted" page has been changed by TylerHobbs: http://wiki.apache.org/cassandra/GettingStarted?action=diff&rev1=68&rev2=69 Comment: Greatly simplify the GettingStarted guide for the common case == Cassandra documentation from DataStax == - !DataStax's latest [[http://www.datastax.com/docs/1.1/index|Cassandra documentation]] covers topics from installation to troubleshooting. Documentation for older releases is also available. + !DataStax's latest [[http://www.datastax.com/docs/1.1/index|Cassandra documentation]] covers topics from installation to troubleshooting, including a [[http://www.datastax.com/docs/quick_start/quickstart|Quick Start Guide]]. Documentation for older releases is also available. == Introduction == This document aims to provide a few easy to follow steps to take the first-time user from installation, to running single node Cassandra, and overview to configure multinode cluster. Cassandra is meant to run on a cluster of nodes, but will run equally well on a single machine. This is a handy way of getting familiar with the software while avoiding the complexities of a larger system. - == Step 0: Prerequisites and connection to the community == + == Step 0: Prerequisites and Connection to the Community == - Cassandra requires the most stable version of Java 1.6 you can deploy. For Sun's jvm, this means at least u19; u21 is better. Cassandra also runs on the IBM jvm, and should run on jrockit as well. + Cassandra requires the most stable version of Java 1.6 you can deploy, preferably the Oracle/Sun JVM. Cassandra also runs on the IBM JVM, and should run on jrockit as well. + + Note for OS X users: + Some people running OS X have trouble getting Java 6 to work. If you've kept up with Apple's updates, Java 6 should already be installed (it comes in Mac OS X 10.5 Update 1). Unfortunately, Apple does not default to using it. What you have to do is change your `JAVA_HOME` environment setting to `/System/Library/Frameworks/JavaVM.framework/Versions/1.6/Home` and add `/System/Library/Frameworks/JavaVM.framework/Versions/1.6/Home/bin` to the beginning of your `PATH`. The best way to ensure you always have up to date information on the project, releases, stability, bugs, and features is to subscribe to the users mailing list ([[mailto:[email protected]|subscription required]]) and participate in the #cassandra channel on [[http://webchat.freenode.net/?channels=#cassandra|IRC]]. <<Anchor(picking_a_version)>> <<Anchor(download_a_kit)>> - == Step 1: Download Cassandra Kit == + == Step 1: Download Cassandra == * Download links for the latest stable release can always be found on the [[http://cassandra.apache.org/download|website]]. * Users of Debian or Debian-based derivatives can install the latest stable release in package form, see DebianPackaging for details. @@ -23, +26 @@ * If you are interested in building Cassandra from source, please refer to [[HowToBuild|How to Build]] page. For more details about misc builds, please refer to [[VersionsAndBuilds|Cassandra versions and builds]] page. - - If you plan to run "snapshot" command on Cassandra, it will be better to install jna.jar also. Please refer to [[Operations#Backing_up_data|Backup Data]] section. <<Anchor(running_a_single_node)>> - == Step 2: Edit configuration files == + == Step 2: Basic Configuration == - Cassandra configuration files can be found in `conf` directory under the top directory of binary and source distributions. + The Cassandra configuration files can be found in the `conf` directory of binary and source distributions. - If you have installed cassandra from RPM packages, configuration files will be placed into `/etc/cassandra/conf`. + If you have installed Cassandra from a deb or rpm package, the configuration files will located in `/etc/cassandra`. - === Step 2.1: Edit cassandra.yaml === - The distribution's sample configuration `conf/cassandra.yaml` contains reasonable defaults for single node operation, but you will need to make sure that the paths exist for '''data_file_directories''', '''commitlog_directory''', and '''saved_caches_directory'''. + === Step 2.1: Directories Used by Cassandra === + If you've installed Cassandra with a deb or rpm package, the directories that Cassandra will use should already be created an have the correct permissions. Otherwise, you will want to check the following config settings. + In `conf/cassandra.yaml` you will find the following configuration options: `data_file_directories` (`/var/lib/cassandra/data`), `commitlog_directory` (`/var/lib/cassandra/commitlog`), and `saved_caches_directory` (`/var/lib/cassandra/saved_caches`). Make sure these directories exist and can be written to. - Verify '''storage_port''' and '''rpc_port''' are not conflict with other service on your computer. - By default, Cassandra uses 7000 for storage_port, and 9160 for rpc_port. The `storage_port` must be identical between Cassandra nodes in a cluster. Cassandra client applications will use `rpc_port` to connect to Cassandra. - - It will be a good idea to change '''cluster_name''' to avoid unnecessary conflict with existing clusters. + By default, Cassandra will log write its logs in `/var/log/cassandra/`. Make sure this directory exists and is writeable, or change this line in `conf/log4j-server.properies`: - '''initial_token'''. You can leave it blank, but I recommend you to set it to 0 if you are configuring your first node. - - === Step 2.2: Edit log4j-server.properties === - `conf/log4j.properties` contains a path for the log file. Edit the line if you need. {{{ - # Edit the next line to point to your logs directory log4j.appender.R.File=/var/log/cassandra/system.log }}} + === Step 2.2: Configure Memory Usage (Optional) === + By default, Cassandra will allocate memory based on physical memory your system has, using somewhere between 1/4 and 1/2 of the available RAM. + + If you want to specify Cassandra heap size explicitly, edit `conf/cassandra-env.sh`, find the following lines, uncomment them, and change their values: - === Step 2.3: Edit cassandra-env.sh === - Cassandra has JMX (Java Management Extensions) interface, and the JMX_PORT is defined in `conf/cassandra-env.sh`. - Edit following line if you need. - {{{ - # Specifies the default port over which Cassandra will be available for - # JMX connections. - JMX_PORT="7199" - }}} - - By default, Cassandra will allocate memory based on physical memory your system has. - For example it will allocate 1GB heap on 2GB system, and 2GB heap on 8GB system. - If you want to specify Cassandra heap size, remove leading pound sign(#) on the following lines and specify memory size for them. {{{ #MAX_HEAP_SIZE="4G" #HEAP_NEWSIZE="800M" }}} + As a rule of thumb, you should set `HEAP_NEWSIZE` to be 1/4 of `MAX_HEAP_SIZE`. If you face OutOfMemory exceptions or massive GCs with this configuration, increase both of these values. - If you are not familiar with Java GC, 1/4 of MAX_HEAP_SIZE may be a good start point for HEAP_NEWSIZE. - - Cassandra will need more than few GB heap for production use, but you can run it with smaller footprint for test drive. If you want to assign 128MB as max, edit the lines as following. - {{{ - MAX_HEAP_SIZE="128M" - HEAP_NEWSIZE="32M" - }}} - If you face OutOfMemory exceptions or massive GCs with this configuration, increase these values. - '''Don't start your production service with such tiny heap configuration!''' - Note for Mac Uses: - Some people running OS X have trouble getting Java 6 to work. If you've kept up with Apple's updates, Java 6 should already be installed (it comes in Mac OS X 10.5 Update 1). Unfortunately, Apple does not default to using it. What you have to do is change your `JAVA_HOME` environment setting to `/System/Library/Frameworks/JavaVM.framework/Versions/1.6/Home` and add `/System/Library/Frameworks/JavaVM.framework/Versions/1.6/Home/bin` to the beginning of your `PATH`. - == Step 3: Start up Cassandra == + == Step 3: Start Cassandra == - And now for the moment of truth, start up Cassandra by invoking `bin/cassandra -f` from the command line<<FootNote(To learn more about controlling the behavior of startup scripts, see RunningCassandra.)>>. The service should start in the foreground and log gratuitously to standard-out. Assuming you don't see messages with scary words like "error", or "fatal", or anything that looks like a Java stack trace, then chances are you've succeeded. + And now for the moment of truth, start up Cassandra by invoking `bin/cassandra -f` from the command line<<FootNote(To learn more about controlling the behavior of startup scripts, see RunningCassandra.)>>. The service should start in the foreground and log gratuitously to the console. Assuming you don't see messages with scary words like "error", or "fatal", or anything that looks like a Java stack trace, then everything should be working. Press "Control-C" to stop Cassandra. - If you start up Cassandra without "-f" option, it will run in background, so you need to kill the process to stop. + If you start up Cassandra without "-f" option, it will run in background. You can stop the process by killing it, using `pkill -f CassandraDaemon`, for example. == Step 4: Using cassandra-cli == - `bin/cassandra-cli` is a interactive command line interface for Cassandra. You can define schema, store and fetch data with the tool. + `bin/cassandra-cli` is a interactive command line interface for Cassandra. You can alter the schema and interact with data using the cli. Run following command to connect to your Cassandra instance. {{{ + bin/cassandra-cli - bin/cassandra-cli -h host -p rpc_port - - example: - % bin/cassandra-cli -h 127.0.0.1 -p 9160 }}} Then you will see following cassandra-cli prompt. @@ -109, +82 @@ [default@unknown] }}} - You can access to the online help with 'help;' command. You need semicolon(;) at end to complete a command in cli. + You can access to the online help with 'help;' command. Commands are terminated with a semicolon (';') in the cli. {{{ [default@unknown] help; @@ -125, +98 @@ [default@unknown] }}} - Don't forget to add semicolon(;) at end of the command. + Don't forget to add a semicolon (';') at end of the command. - Second, authenticate you to use DEMO keyspace. + Second, authenticate you to use the DEMO keyspace. {{{ [default@unknown] use DEMO; Authenticated to keyspace: DEMO [default@DEMO] }}} - Third, create a column family ''Users'', just for test. + Third, create a `Users` column family: {{{ - [default@DEMO] create column family Users; + [default@DEMO] create column family Users - 18a3e2d0-5bd9-11e1-0000-915a024292eb - Waiting for schema agreement... - ... schemas agree across the cluster + ... with key_validation_class = 'UTF8Type' + ... and comparator = 'UTF8Type' + ... and default_validation_class = 'UTF8Type'; [default@DEMO] }}} - Now you can store data into ''Users'' column family. + Now you can store data into `Users` column family: {{{ - [default@DEMO] set Users[utf8('1234')][utf8('name')] = utf8('scott'); + [default@DEMO] set Users[1234][name] = scott; Value inserted. Elapsed time: 10 msec(s). - [default@DEMO] set Users[utf8('1234')][utf8('password')] = utf8('tiger'); + [default@DEMO] set Users[1234][password] = tiger; Value inserted. Elapsed time: 10 msec(s). [default@DEMO] }}} - You have inserted a row to Users column family. The row key is '1234', and we set the 2 columns in the row: column named 'name', and 'password'. + You have inserted a row into the `Users` column family. The row key is '1234', and we set values for two columns in the row: 'name', and 'password'. - 'utf8()' means to treat the data as UTF8 string. Refer to 'help set;' for more details. + - Now let's try to fetch data you inserted. + Now let's fetch the data you inserted: - {{{ - [default@DEMO] get Users[utf8('1234')]; + [default@DEMO] get Users[1234]; - => (column=6e616d65, value=73636f7474, timestamp=1330051295937000) - => (column=70617373776f7264, value=7469676572, timestamp=1330051308368000) + => (column=name, value=scott, timestamp=1350769161684000) + => (column=password, value=tiger, timestamp=1350769245191000) Returned 2 results. - Elapsed time: 9 msec(s). + Elapsed time: 67 msec(s). [default@DEMO] }}} - You may notice that the column name and value are not displayed as string. - Use 'assume' command to let Cassandra to know the data type of the key, column name and value. - {{{ - [default@DEMO] assume Users keys as utf8; - Assumption for column family 'Users' added successfully. - [default@DEMO] assume Users comparator as utf8; - Assumption for column family 'Users' added successfully. - [default@DEMO] assume Users validator as utf8; - Assumption for column family 'Users' added successfully. - [default@DEMO] get Users['1234']; - => (column=name, value=scott, timestamp=1330051295937000) - => (column=password, value=tiger, timestamp=1330051308368000) - - Returned 2 results. - Elapsed time: 9 msec(s). - [default@DEMO] - }}} - - Please note that we didn't use "utf8()" for the row key this time. - You can define the data type as meta data of the column family. Check 'help update column family;' and 'help create column family;' for more details. + You can easily specify types other than UTF-8 when creating or updating a column family. See '`help update column family;`' and '`help create column family;`' for more details. - - Note: You can't update comparator (validation class for "column name") after creating column family. Please refer to [[https://issues.apache.org/jira/browse/CASSANDRA-2809?focusedCommentId=13053420&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13053420|CASSANDRA-2809]]. To be certain though, take some time to try out the examples in CassandraCli before moving on Also, if you run into problems, Don't Panic, calmly proceed to [[#if_something_goes_wrong|If Something Goes Wrong]].
