diff --git a/docs/docker/README.md b/docs/docker/README.md index a6a307695..62961228f 100644 --- a/docs/docker/README.md +++ b/docs/docker/README.md @@ -1,28 +1,20 @@ -# Minio Docker Quickstart Guide [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) +# Minio Docker Quickstart Guide [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) [![Go Report Card](https://goreportcard.com/badge/minio/minio)](https://goreportcard.com/report/minio/minio) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/minio.svg?maxAge=604800)](https://hub.docker.com/r/minio/minio/) [![codecov](https://codecov.io/gh/minio/minio/branch/master/graph/badge.svg)](https://codecov.io/gh/minio/minio) -## 1. Prerequisites +## Prerequisites -### GNU/Linux -Install Docker for GNU/Linux from [here](https://www.docker.com/products/docker#/linux) +Docker installed on your machine. Download the relevant installer from [here](https://www.docker.com/community-edition#/download). -### Microsoft Windows -Install Docker for Windows from [here](https://www.docker.com/products/docker#/windows) +## Run Standalone Minio on Docker. -### macOS -Install Docker for macOS from [here](https://www.docker.com/products/docker#/mac) - -## 2. Test Minio on Docker. -Minio generates new access and secret keys each time you run this command. Container state is lost after you end this session. This mode is only intended for testing purpose. +Minio needs a persistent volume to store configuration and application data. However, for testing purposes, you can launch Minio by simply passing a directory (`/export` in the example below). This directory gets created in the container filesystem at the time of container start. But all the data is lost after container exits. ```sh docker run -p 9000:9000 minio/minio server /export ``` -## 3. Run Minio Standalone on Docker. +To create a Minio container with persistent storage, you need to map local persistent directories from the host OS to virtual config `~/.minio` and export `/export` directories. To do this, run the below commands -Minio container requires a persistent volume to store configuration and application data. Following command maps local persistent directories from the host OS to virtual config `~/.minio` and export `/export` directories. - -### GNU/Linux and macOS +#### GNU/Linux and macOS ```sh docker run -p 9000:9000 --name minio1 \ @@ -31,7 +23,7 @@ docker run -p 9000:9000 --name minio1 \ minio/minio server /export ``` -### Microsoft Windows +#### Windows ```sh docker run -p 9000:9000 --name minio1 \ @@ -40,11 +32,22 @@ docker run -p 9000:9000 --name minio1 \ minio/minio server /export ``` -## 4. Run Minio Standalone on Docker with Custom Access and Secret Keys +## Run Distributed Minio on Docker + +Distributed Minio can be deployed via [Docker Compose](https://docs.docker.com/compose/overview/) or [Swarm mode](https://docs.docker.com/engine/swarm/). The major difference between these two being, Docker Compose creates a single host, multi-container deployment, while Swarm mode creates a multi-host, multi-container deployment. + +This means Docker Compose lets you quickly get started with Distributed Minio on your computer - ideal for development, testing, staging environments. While deploying Distributed Minio on Swarm offers a more robust, production level deployment. + +* To deploy Distributed Minio on Docker Compose, refer [this guide](http://docs.minio.io/docs/deploy-minio-on-docker-compose). +* To deploy Distributed Minio on Docker Swarm, refer [this guide](https://docs.minio.io/docs/deploy-minio-on-docker-swarm). + +## Minio Docker Tips + +### Minio Custom Access and Secret Keys To override Minio's auto-generated keys, you may pass secret and access keys explicitly as environment variables. Minio server also allows regular strings as access and secret keys. -### GNU/Linux and macOS +#### GNU/Linux and macOS ```sh docker run -p 9000:9000 --name minio1 \ @@ -55,7 +58,7 @@ docker run -p 9000:9000 --name minio1 \ minio/minio server /export ``` -### Microsoft Windows +#### Windows ```sh docker run -p 9000:9000 --name minio1 \ @@ -65,31 +68,48 @@ docker run -p 9000:9000 --name minio1 \ -v D:\export\minio1-config:/root/.minio \ minio/minio server /export ``` +### Retrieving Container ID -## 5. Test Distributed Minio on Docker - -This example shows how to run 4 node Minio cluster inside different docker containers using [docker-compose](https://docs.docker.com/compose/). Please download [docker-compose.yml](https://raw.githubusercontent.com/minio/minio/master/docs/docker/docker-compose.yml) to your current working directory, docker-compose pulls the Minio Docker image. - - -#### Run `docker-compose` on GNU/Linux and macOS +To use Docker commands on a specific container, you need to know the `Container ID` for that container. To get the `Container ID`, run ```sh -docker-compose pull -docker-compose up +docker ps -a ``` -#### Run `docker-compose.exe` on Microsoft Windows +`-a` flag makes sure you get all the containers (Created, Running, Exited). Then identify the `Container ID` from the output. + +### Starting and Stopping Containers + +To start a stopped container, you can use the [`docker start`](https://docs.docker.com/engine/reference/commandline/start/) command. ```sh -docker-compose.exe pull -docker-compose.exe up +docker start ``` -Each instance is accessible on the host at ports 9001 through 9004, proceed to access the Web browser at http://127.0.0.1:9001/ +To stop a running container, you can use the [`docker stop`](https://docs.docker.com/engine/reference/commandline/stop/) command. -## 6. Explore Further +```sh +docker stop +``` + +### Minio container logs + +To access Minio logs, you can use the [`docker logs`](https://docs.docker.com/engine/reference/commandline/logs/) command. + +```sh +docker logs +``` + +### Monitor Minio Docker Container + +To monitor the resources used by Minio container, you can use the [`docker stats`](https://docs.docker.com/engine/reference/commandline/stats/) command. + +```sh +docker stats +``` + +## Explore Further * [Minio Erasure Code QuickStart Guide](https://docs.minio.io/docs/minio-erasure-code-quickstart-guide) * [Distributed Minio Quickstart Guide ](https://docs.minio.io/docs/distributed-minio-quickstart-guide) * [Docker Compose](https://docs.docker.com/compose/) - diff --git a/docs/orchestration/README.md b/docs/orchestration/README.md index b5a264579..e3aa535af 100644 --- a/docs/orchestration/README.md +++ b/docs/orchestration/README.md @@ -5,6 +5,7 @@ Minio is a cloud-native application designed to scale in a sustainable manner in | Orchestration platforms| |:---| | [`Docker Swarm`](http://docs.minio.io/docs/deploy-minio-on-docker-swarm) | +| [`Docker Compose`](http://docs.minio.io/docs/deploy-minio-on-docker-compose) | | [`Kubernetes`](http://docs.minio.io/docs/deploy-minio-on-kubernetes) | | [`DC/OS`](http://docs.minio.io/docs/deploy-minio-on-dc-os) | diff --git a/docs/orchestration/docker-compose/README.md b/docs/orchestration/docker-compose/README.md new file mode 100644 index 000000000..6731ad13f --- /dev/null +++ b/docs/orchestration/docker-compose/README.md @@ -0,0 +1,51 @@ +# Deploy Minio on Docker Compose [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) [![Go Report Card](https://goreportcard.com/badge/minio/minio)](https://goreportcard.com/report/minio/minio) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/minio.svg?maxAge=604800)](https://hub.docker.com/r/minio/minio/) [![codecov](https://codecov.io/gh/minio/minio/branch/master/graph/badge.svg)](https://codecov.io/gh/minio/minio) + +Docker Compose allows defining and running single host, multi-container Docker applications. + +With Compose, you use a Compose file to configure Minio services. Then, using a single command, you can create and launch all the Distributed Minio instances from your configuration. Distributed Minio instances will be deployed in multiple containers on the same host. This is a great way to set up development, testing, and staging environments, based on Distributed Minio. + +## 1. Prerequisites + +* Familiarity with [Docker Compose](https://docs.docker.com/compose/overview/). +* Docker installed on your machine. Download the relevant installer from [here](https://www.docker.com/community-edition#/download). + +## 2. Run Distributed Minio on Docker Compose + +To deploy Distributed Minio on Docker Compose, please download [docker-compose.yaml](https://github.com/minio/minio/blob/master/docs/orchestration/docker-compose/docker-compose.yaml?raw=true) to your current working directory. Note that Docker Compose pulls the Minio Docker image, so there is no need to explicitly download Minio binary. Then run one of the below commands + +### GNU/Linux and macOS + +```sh +docker-compose pull +docker-compose up +``` + +### Windows + +```sh +docker-compose.exe pull +docker-compose.exe up +``` + +Each instance is now accessible on the host at ports 9001 through 9004, proceed to access the Web browser at http://127.0.0.1:9001/ + +### Notes + +* By default the Docker Compose file uses the Docker image for latest Minio server release. You can change the image tag to pull a specific [Minio Docker image](https://hub.docker.com/r/minio/minio/). + +* There are 4 minio distributed instances created by default. You can add more Minio services (up to total 16) to your Minio Compose deployment. To add a service + * Replicate a service definition and change the name of the new service appropriately. + * Update the command section in each service. + * Update the port number to exposed for the new service. Also, make sure the port assigned for the new service is not already being used on the host. + + Read more about distributed Minio [here](https://docs.minio.io/docs/distributed-minio-quickstart-guide). + +* Minio services in the Docker compose file expose ports 9001 to 9004. This allows multiple services to run on a host. + +### Explore Further +- [Minio Erasure Code QuickStart Guide](https://docs.minio.io/docs/minio-erasure-code-quickstart-guide) +- [Use `mc` with Minio Server](https://docs.minio.io/docs/minio-client-quickstart-guide) +- [Use `aws-cli` with Minio Server](https://docs.minio.io/docs/aws-cli-with-minio) +- [Use `s3cmd` with Minio Server](https://docs.minio.io/docs/s3cmd-with-minio) +- [Use `minio-go` SDK with Minio Server](https://docs.minio.io/docs/golang-client-quickstart-guide) +- [The Minio documentation website](https://docs.minio.io) diff --git a/docs/docker/docker-compose.yml b/docs/orchestration/docker-compose/docker-compose.yml similarity index 84% rename from docs/docker/docker-compose.yml rename to docs/orchestration/docker-compose/docker-compose.yml index d8320c8ff..f8a6ca7c7 100644 --- a/docs/docker/docker-compose.yml +++ b/docs/orchestration/docker-compose/docker-compose.yml @@ -5,7 +5,7 @@ version: '2' # 9001 through 9004. services: minio1: - image: minio/minio + image: minio/minio:RELEASE.2017-03-16T21-50-32Z ports: - "9001:9000" environment: @@ -13,7 +13,7 @@ services: MINIO_SECRET_KEY: minio123 command: server http://minio1/myexport http://minio2/myexport http://minio3/myexport http://minio4/myexport minio2: - image: minio/minio + image: minio/minio:RELEASE.2017-03-16T21-50-32Z ports: - "9002:9000" environment: @@ -21,7 +21,7 @@ services: MINIO_SECRET_KEY: minio123 command: server http://minio1/myexport http://minio2/myexport http://minio3/myexport http://minio4/myexport minio3: - image: minio/minio + image: minio/minio:RELEASE.2017-03-16T21-50-32Z ports: - "9003:9000" environment: @@ -29,7 +29,7 @@ services: MINIO_SECRET_KEY: minio123 command: server http://minio1/myexport http://minio2/myexport http://minio3/myexport http://minio4/myexport minio4: - image: minio/minio + image: minio/minio:RELEASE.2017-03-16T21-50-32Z ports: - "9004:9000" environment: diff --git a/docs/orchestration/docker-swarm/README.md b/docs/orchestration/docker-swarm/README.md index 542a94208..6ae86564c 100644 --- a/docs/orchestration/docker-swarm/README.md +++ b/docs/orchestration/docker-swarm/README.md @@ -1,13 +1,13 @@ # Deploy Minio on Docker Swarm [![Slack](https://slack.minio.io/slack?type=svg)](https://slack.minio.io) [![Go Report Card](https://goreportcard.com/badge/minio/minio)](https://goreportcard.com/report/minio/minio) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/minio.svg?maxAge=604800)](https://hub.docker.com/r/minio/minio/) [![codecov](https://codecov.io/gh/minio/minio/branch/master/graph/badge.svg)](https://codecov.io/gh/minio/minio) -Docker Engine provides cluster management and orchestration features in Swarm mode. Minio server can be easily deployed in distributed mode on Swarm to create a multi-tenant, highly-available and scalable object store. +Docker Engine provides cluster management and orchestration features in Swarm mode. Minio server can be easily deployed in distributed mode on Swarm to create a multi-tenant, highly-available and scalable object store. As of [Docker Engine v1.13.0](https://blog.docker.com/2017/01/whats-new-in-docker-1-13/) (Docker Compose v3.0), Docker Swarm and Compose are [cross-compatible](https://docs.docker.com/compose/compose-file/#version-3). This allows a Compose file to be used as a template to deploy services on Swarm. We have used a Docker Compose file to create distributed Minio setup. ## 1. Prerequisites * Familiarity with [Swarm mode key concepts](https://docs.docker.com/engine/swarm/key-concepts/). -* Docker engine v1.13.0 running on a cluster of [networked host machines](https://docs.docker.com/engine/swarm/swarm-tutorial/#/three-networked-host-machines). +* Docker engine v1.13.0 running on a cluster of [networked host machines](https://docs.docker.com/engine/swarm/swarm-tutorial/#/three-networked-host-machines). ## 2. Create a Swarm @@ -16,22 +16,22 @@ SSH into the machine supposed to serve as Swarm manager. If the machine is named ```shell docker-machine ssh manager ``` -After logging in to the designated manager node, create the Swarm by +After logging in to the designated manager node, create the Swarm by ```shell docker swarm init --advertise-addr ``` -After the manager is up, [add worker nodes](https://docs.docker.com/engine/swarm/swarm-tutorial/add-nodes/) to the Swarm. Find detailed steps to create the Swarm on [Docker documentation site](https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/). +After the manager is up, [add worker nodes](https://docs.docker.com/engine/swarm/swarm-tutorial/add-nodes/) to the Swarm. Find detailed steps to create the Swarm on [Docker documentation site](https://docs.docker.com/engine/swarm/swarm-tutorial/create-swarm/). ## 3. Deploy distributed Minio services -Download the [Docker Compose file](https://github.com/minio/minio/blob/master/docs/orchestration/docker-swarm/docker-compose.yaml) on your Swarm master. Then execute the command +Download the [Docker Compose file](https://github.com/minio/minio/blob/master/docs/orchestration/docker-swarm/docker-compose.yaml?raw=true) on your Swarm master. Then execute the command ```shell docker stack deploy --compose-file=docker-compose.yaml minio_stack ``` -This deploys services described in the Compose file as Docker stack `minio_stack`. Look up the `docker stack` [command reference](https://docs.docker.com/engine/reference/commandline/stack/) for more info. +This deploys services described in the Compose file as Docker stack `minio_stack`. Look up the `docker stack` [command reference](https://docs.docker.com/engine/reference/commandline/stack/) for more info. After the stack is successfully deployed, you should be able to access Minio server via [Minio Client](https://docs.minio.io/docs/minio-client-complete-guide) `mc` or your browser at http://[Node_Public_IP_Address]:[Expose_Port_on_Host] @@ -45,21 +45,21 @@ docker stack rm minio_stack ### Notes -* By default the Docker Compose file uses the Docker image for latest Minio server release. You can change the image tag to pull a specific [Minio Docker image](https://hub.docker.com/r/minio/minio/). +* By default the Docker Compose file uses the Docker image for latest Minio server release. You can change the image tag to pull a specific [Minio Docker image](https://hub.docker.com/r/minio/minio/). -* There are 4 minio distributed instances created by default. You can add more Minio services (upto total 16) to your Minio Swarm deployment. To add a deployment +* There are 4 minio distributed instances created by default. You can add more Minio services (up to total 16) to your Minio Swarm deployment. To add a service * Replicate a service definition and change the name of the new service appropriately. * Add a volume in volumes section, and update volume section in the service accordingly. - * Update the command section in each service. Specifically, add the drive location to be used as storage on the new service. - * Update the port number to exposed for the new service. + * Update the command section in each service. Specifically, add the drive location to be used as storage on the new service. + * Update the port number to exposed for the new service. Read more about distributed Minio [here](https://docs.minio.io/docs/distributed-minio-quickstart-guide). -* By default the services use `local` volume driver. Refer to [Docker documentation](https://docs.docker.com/compose/compose-file/#/volume-configuration-reference) to explore further options. +* By default the services use `local` volume driver. Refer to [Docker documentation](https://docs.docker.com/compose/compose-file/#/volume-configuration-reference) to explore further options. * Minio services in the Docker compose file expose ports 9001 to 9004. This allows multiple services to run on a host. Explore other configuration options in [Docker documentation](https://docs.docker.com/compose/compose-file/#/ports). -* Docker Swarm uses ingress load balancing by default. You can configure [external load balancer based](https://docs.docker.com/engine/swarm/ingress/#/configure-an-external-load-balancer) on requirements. +* Docker Swarm uses ingress load balancing by default. You can configure [external load balancer based](https://docs.docker.com/engine/swarm/ingress/#/configure-an-external-load-balancer) on requirements. ### Explore Further - [Minio Erasure Code QuickStart Guide](https://docs.minio.io/docs/minio-erasure-code-quickstart-guide) diff --git a/docs/orchestration/docker-swarm/docker-compose.yaml b/docs/orchestration/docker-swarm/docker-compose.yaml index f6e482b72..be7e38867 100644 --- a/docs/orchestration/docker-swarm/docker-compose.yaml +++ b/docs/orchestration/docker-swarm/docker-compose.yaml @@ -2,7 +2,7 @@ version: '3' services: minio1: - image: minio/minio:RELEASE.2017-01-25T03-14-52Z + image: minio/minio:RELEASE.2017-03-16T21-50-32Z volumes: - minio1-data:/export ports: @@ -20,7 +20,7 @@ services: command: server http://minio1/export http://minio2/export http://minio3/export http://minio4/export minio2: - image: minio/minio:RELEASE.2017-01-25T03-14-52Z + image: minio/minio:RELEASE.2017-03-16T21-50-32Z volumes: - minio2-data:/export ports: @@ -38,7 +38,7 @@ services: command: server http://minio1/export http://minio2/export http://minio3/export http://minio4/export minio3: - image: minio/minio:RELEASE.2017-01-25T03-14-52Z + image: minio/minio:RELEASE.2017-03-16T21-50-32Z volumes: - minio3-data:/export ports: @@ -56,7 +56,7 @@ services: command: server http://minio1/export http://minio2/export http://minio3/export http://minio4/export minio4: - image: minio/minio:RELEASE.2017-01-25T03-14-52Z + image: minio/minio:RELEASE.2017-03-16T21-50-32Z volumes: - minio4-data:/export ports: