1This README is just a fast *quick start* document. You can find more detailed documentation at http://redis.io. 2 3What is Redis? 4-------------- 5 6Redis is often referred as a *data structures* server. What this means is that Redis provides access to mutable data structures via a set of commands, which are sent using a *server-client* model with TCP sockets and a simple protocol. So different processes can query and modify the same data structures in a shared way. 7 8Data structures implemented into Redis have a few special properties: 9 10* Redis cares to store them on disk, even if they are always served and modified into the server memory. This means that Redis is fast, but that is also non-volatile. 11* Implementation of data structures stress on memory efficiency, so data structures inside Redis will likely use less memory compared to the same data structure modeled using an high level programming language. 12* Redis offers a number of features that are natural to find in a database, like replication, tunable levels of durability, cluster, high availability. 13 14Another good example is to think of Redis as a more complex version of memcached, where the operations are not just SETs and GETs, but operations to work with complex data types like Lists, Sets, ordered data structures, and so forth. 15 16If you want to know more, this is a list of selected starting points: 17 18* Introduction to Redis data types. http://redis.io/topics/data-types-intro 19* Try Redis directly inside your browser. http://try.redis.io 20* The full list of Redis commands. http://redis.io/commands 21* There is much more inside the Redis official documentation. http://redis.io/documentation 22 23Building Redis 24-------------- 25 26Redis can be compiled and used on Linux, OSX, OpenBSD, NetBSD, FreeBSD. 27We support big endian and little endian architectures, and both 32 bit 28and 64 bit systems. 29 30It may compile on Solaris derived systems (for instance SmartOS) but our 31support for this platform is *best effort* and Redis is not guaranteed to 32work as well as in Linux, OSX, and \*BSD there. 33 34It is as simple as: 35 36 % make 37 38You can run a 32 bit Redis binary using: 39 40 % make 32bit 41 42After building Redis is a good idea to test it, using: 43 44 % make test 45 46Fixing build problems with dependencies or cached build options 47--------- 48 49Redis has some dependencies which are included into the `deps` directory. 50`make` does not rebuild dependencies automatically, even if something in the 51source code of dependencies is changed. 52 53When you update the source code with `git pull` or when code inside the 54dependencies tree is modified in any other way, make sure to use the following 55command in order to really clean everything and rebuild from scratch: 56 57 make distclean 58 59This will clean: jemalloc, lua, hiredis, linenoise. 60 61Also if you force certain build options like 32bit target, no C compiler 62optimizations (for debugging purposes), and other similar build time options, 63those options are cached indefinitely until you issue a `make distclean` 64command. 65 66Fixing problems building 32 bit binaries 67--------- 68 69If after building Redis with a 32 bit target you need to rebuild it 70with a 64 bit target, or the other way around, you need to perform a 71`make distclean` in the root directory of the Redis distribution. 72 73In case of build errors when trying to build a 32 bit binary of Redis, try 74the following steps: 75 76* Install the packages libc6-dev-i386 (also try g++-multilib). 77* Try using the following command line instead of `make 32bit`: 78 `make CFLAGS="-m32 -march=native" LDFLAGS="-m32"` 79 80Allocator 81--------- 82 83Selecting a non-default memory allocator when building Redis is done by setting 84the `MALLOC` environment variable. Redis is compiled and linked against libc 85malloc by default, with the exception of jemalloc being the default on Linux 86systems. This default was picked because jemalloc has proven to have fewer 87fragmentation problems than libc malloc. 88 89To force compiling against libc malloc, use: 90 91 % make MALLOC=libc 92 93To compile against jemalloc on Mac OS X systems, use: 94 95 % make MALLOC=jemalloc 96 97Verbose build 98------------- 99 100Redis will build with a user friendly colorized output by default. 101If you want to see a more verbose output use the following: 102 103 % make V=1 104 105Running Redis 106------------- 107 108To run Redis with the default configuration just type: 109 110 % cd src 111 % ./redis-server 112 113If you want to provide your redis.conf, you have to run it using an additional 114parameter (the path of the configuration file): 115 116 % cd src 117 % ./redis-server /path/to/redis.conf 118 119It is possible to alter the Redis configuration passing parameters directly 120as options using the command line. Examples: 121 122 % ./redis-server --port 9999 --slaveof 127.0.0.1 6379 123 % ./redis-server /etc/redis/6379.conf --loglevel debug 124 125All the options in redis.conf are also supported as options using the command 126line, with exactly the same name. 127 128Playing with Redis 129------------------ 130 131You can use redis-cli to play with Redis. Start a redis-server instance, 132then in another terminal try the following: 133 134 % cd src 135 % ./redis-cli 136 redis> ping 137 PONG 138 redis> set foo bar 139 OK 140 redis> get foo 141 "bar" 142 redis> incr mycounter 143 (integer) 1 144 redis> incr mycounter 145 (integer) 2 146 redis> 147 148You can find the list of all the available commands at http://redis.io/commands. 149 150Installing Redis 151----------------- 152 153In order to install Redis binaries into /usr/local/bin just use: 154 155 % make install 156 157You can use `make PREFIX=/some/other/directory install` if you wish to use a 158different destination. 159 160Make install will just install binaries in your system, but will not configure 161init scripts and configuration files in the appropriate place. This is not 162needed if you want just to play a bit with Redis, but if you are installing 163it the proper way for a production system, we have a script doing this 164for Ubuntu and Debian systems: 165 166 % cd utils 167 % ./install_server.sh 168 169The script will ask you a few questions and will setup everything you need 170to run Redis properly as a background daemon that will start again on 171system reboots. 172 173You'll be able to stop and start Redis using the script named 174`/etc/init.d/redis_<portnumber>`, for instance `/etc/init.d/redis_6379`. 175 176Code contributions 177--- 178 179Note: by contributing code to the Redis project in any form, including sending 180a pull request via Github, a code fragment or patch via private email or 181public discussion groups, you agree to release your code under the terms 182of the BSD license that you can find in the [COPYING][1] file included in the Redis 183source distribution. 184 185Please see the [CONTRIBUTING][2] file in this source distribution for more 186information. 187 188Enjoy! 189 190[1]: https://github.com/antirez/redis/blob/unstable/COPYING 191[2]: https://github.com/antirez/redis/blob/unstable/CONTRIBUTING 192