Bitnami/containers
2
0
Fork 0
mirror of https://github.com/bitnami/containers.git synced 2026-04-03 15:57:46 +08:00
Code Issues Packages Projects Releases Wiki Activity

Improve README

Browse Source
This commit is contained in:
Adnan Abdulhussein
2015-06-17 23:47:58 -07:00
parent 5ad129e381
commit d8841ac3c3
1 changed files with 376 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

433
bitnami/redis/README.md
View File

@@ -1,80 +1,399 @@
# Bitnami Redis Docker Container
# What is Redis?
## Introduction to Bitnami containers
Bitnami provides easy-to-use, consistently configured, and always up-to-date container images. [Click here](https://bitnami.com) for more information on our packaging approach.
> Redis is an advanced key-value cache and store. It is often referred to as a data structure server
> since keys can contain strings, hashes, lists, sets, sorted sets, bitmaps and hyperloglogs.
## What is Redis?
Redis is an open source, BSD licensed, advanced key-value cache and
store. It is often referred to as a data structure server since keys can
contain strings, hashes, lists, sets, sorted sets, bitmaps and
hyperloglogs.
[redis.io](http://redis.io/)
## Usage
You can instantiate a Bitnami Redis container by doing:
# TLDR
```
HOST_REDIS_CONF_DIR=`pwd`/redis/conf
HOST_REDIS_DATA_DIR=`pwd`/redis/data
CONTAINER_REDIS_SERVER_NAME=redis
docker run -it \
-v $HOST_REDIS_CONF_DIR:/conf \
-v $HOST_REDIS_DATA_DIR:/data \
--name $CONTAINER_REDIS_SERVER_NAME
bitnami/redis
```bash
docker run --name redis bitnami/redis
```
## Data
Redis data lives in $HOST_REDIS_DATA_DIR on the host. /data inside the
container.
## Configuration
### redis.cnf
Redis configuration files live in $HOST_REDIS_CONF_DIR on the host and /conf in the container. You can edit the default or place your own `redis.conf` file in there.
### Environment variables
You can specify the `REDIS_PASSWORD` that will be used the first time
you launch the container to setup your redis server.
### Extra run parameters
You can add extra options to the docker run that will be
applied to the redis-server command.
## Docker Compose
```
docker run --rm -it bitnami/redis ---logfile path_to_your_log
redis:
image: bitnami/redis
```
You can also override the default redis-server command just adding your
own.
# Get this image
```
docker run --rm -it bitnami/redis redis-cli
The recommended way to get the Bitnami Redis Docker Image is to pull the prebuilt image from the [Docker Hub Registry](https://hub.docker.com).
```bash
docker pull bitnami/redis:3.0.2-2
```
## Linking
To always get the latest version, pull the `latest` tag.
You can link redis to a container running your application, e.g., using the Bitnami node container:
```
CONTAINER_REDIS_LINK_NAME=redis
docker run --rm -it \
--link $CONTAINER_REDIS_SERVER_NAME:$CONTAINER_REDIS_LINK_NAME bitnami/node \
npm start --production
```bash
docker pull bitnami/redis:latest
```
Inside your application, use the value of $CONTAINER_REDIS_LINK_NAME when setting the redis host.
If you wish, you can also build the image yourself.
## Logging
```bash
git clone https://github.com/bitnami/bitnami-docker-redis.git
cd docker-redis
docker build -t bitnami/redis
```
The container is set up to log to stdout, which means logs can be obtained as follows:
# Persisting your database
If you remove the container all your data will be lost, and the next time you run the image the
database will be reinitialized. To avoid this loss of data, you should mount a volume that will
persist even after the container is removed.
**Note!**
If you have already started using your database, follow the steps on
[backing up](#backing-up-your-container) and [restoring](#restoring-a-backup) to pull the data from
your running container down to your host.
The Redis image exposes a volume at `/bitnami/redis/data`, you can mount a directory from your
host to serve as the data store. If the directory you mount is empty, the database will be
initialized.
```bash
docker run -v /path/to/data:/bitnami/redis/data bitnami/redis
```
or using Docker Compose:
```
redis:
image: bitnami/redis
volumes:
- path/to/data:/bitnami/redis/data
```
# Linking
If you want to connect to your Redis server inside another container, you can use the linking
system provided by Docker.
## Connecting a Redis client container to the Redis server container
### Step 1: Run the Redis image with a specific name
The first step is to start our Redis server.
Docker's linking system uses container ids or names to reference containers. We can explicitly
specify a name for our Redis server to make it easier to connect to other containers.
```bash
docker run --name redis-server bitnami/redis
```
### Step 2: Run Redis as a client and link to our server
Now that we have our Redis server running, we can create another container that links to it by
giving Docker the `--link` option. This option takes the id or name of the container we want to link
it to as well as a hostname to use inside the container, separated by a colon. For example, to have
our Redis server accessible in another container with `redis` as it's hostname we would pass
`--link redis-server:redis` to the Docker run command.
The Bitnami Redis Docker Image also ships with a Redis client, but by default it will start a
server. To start the client instead, we can override the default command Docker runs by stating a
different command to run after the image name.
```bash
docker run --rm -it --link redis-server:redis bitnami/redis redis-cli -h redis
```
We started the Redis client passing in the `-h` option that allows us to specify the hostname of the
server, which we set to the hostname we created in the link.
**Note!**
You can also run the Redis client in the same container the server is running in using the Docker
[exec](https://docs.docker.com/reference/commandline/cli/#exec) command.
```bash
docker exec -it redis-server redis-cli
```
## Linking with Docker Compose
### Step 1: Add a Redis entry in your `docker-compose.yml`
Copy the snippet below into your `docker-compose.yml` to add Redis to your application.
```
redis:
image: bitnami/redis
```
### Step 2: Link it to another container in your application
Update the definitions for containers you want to access your Redis server from to include a link
to the `redis` entry you added in Step 1.
```
myapp:
image: myapp
links:
- redis:redis
```
Inside `myapp`, use `redis` as the hostname for the Redis server.
# Configuration
## Setting the server password on first run
Passing the `REDIS_PASSWORD` environment variable when running the image for the first time will
set the Redis server password to the value of `REDIS_PASSWORD`.
```bash
docker run --name redis -e REDIS_PASSWORD=my_password bitnami/redis
```
or using Docker Compose:
```
redis:
image: bitnami/redis
environment:
- REDIS_PASSWORD=my_password
```
## Command-line options
The simplest way to configure your Redis server is to pass custom command-line options when
running the image.
```bash
docker run bitnami/redis --maxclients 10
```
or using Docker Compose:
```
redis:
image: bitnami/redis
command: --maxclients 10
```
## Configuration file
This image looks for configuration in `/bitnami/redis/conf`. You can mount a volume there with
your own configuration, or the default configuration will be copied to your volume if it is empty.
### Step 1: Run the Redis image
Run the Redis image, mounting a directory from your host.
```bash
docker run --name redis -v /path/to/redis/conf:/bitnami/redis/conf bitnami/redis
```
or using Docker Compose:
```
redis:
image: bitnami/redis
volumes:
- path/to/redis/conf:/bitnami/redis/conf
```
### Step 2: Edit the configuration
Edit the configuration on your host using your favorite editor.
```bash
vi /path/to/redis/conf/redis.conf
```
### Step 3: Restart Redis
After changing the configuration, restart your Redis container for changes to take effect.
```bash
docker restart redis
```
or using Docker Compose:
```bash
docker-compose restart redis
```
**Further Reading:**
- [Redis Configuration Documentation](http://redis.io/topics/config)
# Logging
The Bitnami Redis Docker Image supports two different logging modes: logging to stdout, and
logging to a file.
## Logging to stdout
The default behavior is to log to stdout, as Docker expects. These will be collected by Docker,
converted to JSON and stored in the host, to be accessible via the `docker logs` command.
```bash
docker logs redis
```
If you would like to log to a file instead, you can mount a volume at `/logs`.
or using Docker Compose:
```bash
docker-compose logs redis
```
This method of logging has the downside of not being easy to manage. Without an easy way to rotate
logs, they could grow exponentially and take up large amounts of disk space on your host.
## Logging to file
To log to file, run the Redis image, mounting a directory from your host at `/bitnami/redis/logs`.
This will instruct the container to send logs to a `redis-server.log` file in the mounted volume.
```bash
docker run --name redis -v /path/to/redis/logs:/bitnami/redis/logs bitnami/redis
```
or using Docker Compose:
```
redis:
image: bitnami/redis
volumes:
- path/to/redis/logs:/bitnami/redis/logs
```
To perform operations (e.g. logrotate) on the logs, mount the same directory in a container designed
to operate on log files, such as logstash.
# Maintenance
## Backing up your container
To backup your data, configuration and logs, follow these simple steps:
### Step 1: Stop the currently running container
```bash
docker stop redis
```
or using Docker Compose:
```bash
docker-compose stop redis
```
### Step 2: Run the backup command
We need to mount two volumes in a container we will use to create the backup: a directory on your
host to store the backup in, and the volumes from the container we just stopped so we can access the
data.
```bash
docker run --rm -v /path/to/backups:/backups --volumes-from redis busybox \
cp -a /bitnami/redis /backups/latest
```
or using Docker Compose:
```bash
docker run --rm -v /path/to/backups:/backups --volumes-from `docker-compose ps -q redis` busybox \
cp -a /bitnami/redis /backups/latest
```
**Note!**
If you only need to backup database data, or configuration, you can change the first argument to
`cp` to `/bitnami/redis/data` or `/bitnami/redis/conf` respectively.
## Restoring a backup
Restoring a backup is as simple as mounting the backup as volumes in the container.
```bash
docker run -v /path/to/backups/latest/data:/bitnami/redis/data \
-v /path/to/backups/latest/conf:/bitnami/redis/conf \
-v /path/to/backups/latest/logs:/bitnami/redis/logs \
bitnami/redis
```
or using Docker Compose:
```
redis:
image: bitnami/redis
volumes:
- path/to/backups/latest/data:/bitnami/redis/data
- path/to/backups/latest/conf:/bitnami/redis/conf
- path/to/backups/latest/logs:/bitnami/redis/logs
```
## Upgrade this image
Bitnami provides up-to-date versions of Redis, including security patches, soon after they are
made upstream. We recommend that you follow these steps to upgrade your container.
### Step 1: Get the updated image
```bash
docker pull bitnami/redis:3.0.2-2
```
or if you're using Docker Compose, update the value of the image property to
`bitnami/redis:3.0.2-2`.
### Step 2: Stop and backup the currently running container
Before continuing, you should backup your container's data, configuration and logs, unless you are
mounting these volumes from your host.
Follow the steps on [creating a backup](#backing-up-your-container).
### Step 3: Remove the currently running container
```bash
docker rm -v redis
```
or using Docker Compose:
```bash
docker-compose rm -v redis
```
### Step 4: Run the new image
Re-create your container from the new image, [restoring your backup](#restoring-a-backup) if
necessary.
```bash
docker run --name redis bitnami/redis:3.0.2-2
```
or using Docker Compose:
```bash
docker-compose start redis
```
# Contributing
We'd love for you to contribute to this container. You can request new features by creating an
[issue](https://github.com/bitnami/bitnami-docker-redis/issues), or submit a
[pull request](https://github.com/bitnami/bitnami-docker-redis/pulls) with your contribution.
# Issues
If you encountered a problem running this container, you can file an
[issue](https://github.com/bitnami/bitnami-docker-redis/issues). For us to provide better support,
be sure to include the following information in your issue:
- Host OS and version
- Docker version (`docker version`)
- Output of `docker info`
- Version of this container (`echo $BITNAMI_APP_VERSION` inside the container)
- The command you used to run the container, and any relevant output you saw (masking any sensitive
information)
# License