Bitnami/containers
2
0
Fork 0
mirror of https://github.com/bitnami/containers.git synced 2026-04-02 07:18:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

readme: updated

Browse Source
This commit is contained in:
Sameer Naik
2016-05-31 17:22:57 +05:30
parent 25f0f29378
commit 795af1bd1b
1 changed files with 60 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
bitnami/mongodb/README.md
View File

@@ -7,14 +7,14 @@
# TLDR
```bash
docker run --name mongodb bitnami/mongodb
docker run --name mongodb bitnami/mongodb:latest
```
## Docker Compose
```
```yaml
mongodb:
image: bitnami/mongodb
image: bitnami/mongodb:latest
```
# Get this image
@@ -34,31 +34,30 @@ docker pull bitnami/mongodb:[TAG]
If you wish, you can also build the image yourself.
```bash
git clone https://github.com/bitnami/bitnami-docker-mongodb.git
cd bitnami-docker-mongodb
docker build -t bitnami/mongodb .
docker build -t bitnami/mongodb:latest https://github.com/bitnami/bitnami-docker-mongodb.git
```
# 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.
If you remove the container all your data and configurations 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.
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 MongoDB image exposes a volume at `/bitnami/mongodb/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.
The image exposes a volume at `/bitnami/mongodb` for the MongoDB data and configurations. For persistence you can mount a directory at this location from your host. If the mounted directory is empty, it will be initialized on the first run.
```bash
docker run -v /path/to/data:/bitnami/mongodb/data bitnami/mongodb
docker run -v /path/to/mongodb-persistence:/bitnami/mongodb bitnami/mongodb:latest
```
or using Docker Compose:
```
```yaml
mongodb:
image: bitnami/mongodb
image: bitnami/mongodb:latest
volumes:
- /path/to/data:/bitnami/mongodb/data
- /path/to/mongodb-persistence:/bitnami/mongodb
```
# Linking
@@ -74,7 +73,7 @@ The first step is to start our MongoDB server.
Docker's linking system uses container ids or names to reference containers. We can explicitly specify a name for our MongoDB server to make it easier to connect to other containers.
```bash
docker run --name mongodb bitnami/mongodb
docker run --name mongodb bitnami/mongodb:latest
```
### Step 2: Run MongoDB as a Mongo client and link to our server
@@ -84,7 +83,7 @@ Now that we have our MongoDB server running, we can create another container tha
The Bitnami MongoDB Docker Image also ships with a Mongo 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 mongodb:server bitnami/mongodb mongo --host server
docker run --rm -it --link mongodb:server bitnami/mongodb:latest mongo --host server
```
We started the Mongo client passing in the `--host` option that allows us to specify the hostname of the server, which we set to the hostname we created in the link.
@@ -102,16 +101,16 @@ docker exec -it mongodb mongo
Copy the snippet below into your `docker-compose.yml` to add MongoDB to your application.
```
```yaml
mongodb:
image: bitnami/mongodb
image: bitnami/mongodb:latest
```
### Step 2: Link it to another container in your application
Update the definitions for containers you want to access your MongoDB server from to include a link to the `mongodb` entry you added in Step 1.
```
```yaml
myapp:
image: myapp
links:
@@ -124,41 +123,39 @@ Inside `myapp`, use `mongodb` as the hostname for the MongoDB server.
## Setting the root password on first run
Passing the `MONGODB_PASSWORD` environment variable when running the image for the first time will set the password of the root user to the value of `MONGODB_PASSWORD`.
Passing the `MONGODB_ROOT_PASSWORD` environment variable when running the image for the first time will set the password of the root user to the value of `MONGODB_ROOT_PASSWORD` and enabled authentication on the MongoDB server.
```bash
docker run --name mongodb -e MONGODB_PASSWORD=password123 bitnami/mongodb
docker run --name mongodb \
-e MONGODB_ROOT_PASSWORD=password123 bitnami/mongodb:latest
```
or using Docker Compose:
```
```yaml
mongodb:
image: bitnami/mongodb
image: bitnami/mongodb:latest
environment:
- MONGODB_PASSWORD=password123
- MONGODB_ROOT_PASSWORD=password123
```
The `root` user is configured to have full administrative access to the MongoDB server. When `MONGODB_PASSWORD` is not specified the server allows unauthenticated and unrestricted access.
**Note!**
The `MONGODB_PASSWORD` enables authentication on the MongoDB server at runtime. Ensure that this parameter is **always** specified to ensure that authentication is enabled each time the container is started.
The `root` user is configured to have full administrative access to the MongoDB server. When `MONGODB_ROOT_PASSWORD` is not specified the server allows unauthenticated and unrestricted access.
## Creating a user and database on first run
You can create a user with restricted access to a database while starting the container for the first time. To do this, provide the `MONGODB_USER`, `MONGO_PASSWORD` and `MONGODB_DATABASE` environment variables.
**Warning!** In this case, a root user will not be created, and your restricted user will not have permissions to create a new database.
```bash
docker run --name mongodb -e MONGODB_USER=my_user -e MONGODB_PASSWORD=password123 -e MONGODB_DATABASE=my_database bitnami/mongodb
docker run --name mongodb \
-e MONGODB_USER=my_user -e MONGODB_PASSWORD=password123 \
-e MONGODB_DATABASE=my_database bitnami/mongodb:latest
```
or using Docker Compose:
```
```yaml
mongodb:
image: bitnami/mongodb
image: bitnami/mongodb:latest
environment:
- MONGODB_USER=my_user
- MONGODB_PASSWORD=password123
@@ -166,49 +163,27 @@ mongodb:
```
**Note!**
When `MONGODB_PASSWORD` is specified along with `MONGODB_USER`, the value specified in `MONGODB_PASSWORD` is set as the password of the newly created user specified in `MONGODB_USER`.
## Command-line options
The simplest way to configure your MongoDB server is to pass custom command-line options when running the image.
```bash
docker run -it --rm bitnami/mongodb --maxConns=1000
```
or using Docker Compose:
```
mongodb:
image: bitnami/mongodb
command: --maxConns=1000
```
**Further Reading:**
- [MongoDB Server Command Options](http://docs.mongodb.org/manual/reference/program/mongod/)
- [MongoDB Server Parameters](http://docs.mongodb.org/manual/reference/parameters/#mongodb-server-parameters)
- [Caveats](#caveats)
Creation of a user enables authentication on the MongoDB server and as a result unauthenticated access by *any* user is not permitted.
## Configuration file
This image looks for the configuration in `/bitnami/mongodb/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.
The image looks for configuration in the `conf/` directory of `/bitnami/mongodb`. As as mentioned in [Persisting your database](#persisting-your-data) you can mount a volume at this location and copy your own configurations in the `conf/` directory. The default configuration will be copied to the `conf/` directory if it's empty.
### Step 1: Run the MongoDB image
Run the MongoDB image, mounting a directory from your host.
```bash
docker run --name mongodb -v /path/to/mongodb/conf:/bitnami/mongodb/conf bitnami/mongodb
docker run --name mongodb -v /path/to/mongodb-persistence:/bitnami/mongodb bitnami/mongodb:latest
```
or using Docker Compose:
```
```yaml
mongodb:
image: bitnami/mongodb
image: bitnami/mongodb:latest
volumes:
- /path/to/mongodb/conf:/bitnami/mongodb/conf
- /path/to/mongodb-persistence:/bitnami/mongodb
```
### Step 2: Edit the configuration
@@ -216,7 +191,7 @@ mongodb:
Edit the configuration on your host using your favorite editor.
```bash
vi /path/to/mongodb/conf/mongodb.conf
vi /path/to/mongodb-persistence/conf/mongodb.conf
```
### Step 3: Restart MongoDB
@@ -236,24 +211,10 @@ docker-compose restart mongodb
**Further Reading:**
- [Configuration File Options](http://docs.mongodb.org/v2.4/reference/configuration-options/)
- [Caveats](#caveats)
## Caveats
The following options should not be modified, to ensure that the image runs correctly.
```bash
--config /opt/bitnami/mongodb/conf/mongodb.conf
--dbpath /opt/bitnami/mongodb/data
```
# Logging
The Bitnami MongoDB 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.
The Bitnami MongoDB Docker image sends the container logs to the `stdout`. To view the logs:
```bash
docker logs mongodb
@@ -265,26 +226,7 @@ or using Docker Compose:
docker-compose logs mongodb
```
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 MongoDB image, mounting a directory from your host at `/bitnami/mongodb/logs`. This will instruct the container to send logs to a `mongodb.log` file in the mounted volume.
```bash
docker run --name mongodb -v /path/to/mongodb/logs:/bitnami/mongodb/logs bitnami/mongodb
```
or using Docker Compose:
```
mongodb:
image: bitnami/mongodb
volumes:
- /path/to/mongodb/logs:/bitnami/mongodb/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.
You can configure the containers [logging driver](https://docs.docker.com/engine/admin/logging/overview/) using the `--log-driver` option if you wish to consume the container logs differently. In the default configuration docker uses the `json-file` driver.
# Maintenance
@@ -309,40 +251,37 @@ docker-compose stop mongodb
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 mongodb busybox \
cp -a /bitnami/mongodb /backups/latest
docker run --rm \
-v /path/to/mongodb-backups:/backups \
--volumes-from mongodb busybox \
cp -a /bitnami/mongodb:latest /backups/latest
```
or using Docker Compose:
```bash
docker run --rm -v /path/to/backups:/backups --volumes-from `docker-compose ps -q mongodb` busybox \
cp -a /bitnami/mongodb /backups/latest
docker run --rm \
-v /path/to/mongodb-backups:/backups \
--volumes-from `docker-compose ps -q mongodb` busybox \
cp -a /bitnami/mongodb:latest /backups/latest
```
**Note!**
If you only need to backup database data, or configuration, you can change the first argument to `cp` to `/bitnami/mongodb/data` or `/bitnami/mongodb/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/mongodb/data \
-v /path/to/backups/latest/conf:/bitnami/mongodb/conf \
-v /path/to/backups/latest/logs:/bitnami/mongodb/logs \
bitnami/mongodb
docker run \
-v /path/to/mongodb-backups/latest:/bitnami/mongodb bitnami/mongodb:latest
```
or using Docker Compose:
```
```yaml
mongodb:
image: bitnami/mongodb
image: bitnami/mongodb:latest
volumes:
- /path/to/backups/latest/data:/bitnami/mongodb/data
- /path/to/backups/latest/conf:/bitnami/mongodb/conf
- /path/to/backups/latest/logs:/bitnami/mongodb/logs
- /path/to/mongodb-backups/latest:/bitnami/mongodb
```
## Upgrade this image
@@ -393,10 +332,17 @@ docker-compose start mongodb
This image is tested for expected runtime behavior, using the [Bats](https://github.com/sstephenson/bats) testing framework. You can run the tests on your machine using the `bats` command.
```
```bash
bats test.sh
```
# Notable Changes
## 3.2.6-r0
- All volumes have been merged at `/bitnami/mongodb`. Now you only need to mount a single volume at `/bitnami/mongodb` for persistence.
- The logs are always sent to the `stdout` and are no longer collected in the volume.
# 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-mongodb/issues), or submit a [pull request](https://github.com/bitnami/bitnami-docker-mongodb/pulls) with your contribution.
@@ -409,8 +355,7 @@ If you encountered a problem running this container, you can file an [issue](htt
- 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)
- The command you used to run the container, and any relevant output you saw (masking any sensitive information)
# License