s3/docs/docker

S3 Docker Quickstart Guide

See our web documentation on [Deploying S3 in Standalone Mode](Deploy Standalone S3 in a Container) for a more structured tutorial on deploying S3 in a container.

Prerequisites

Docker installed on your machine. Download the relevant installer from here.

Run Standalone S3 on Docker

Note: Standalone S3 is intended for early development and evaluation. For production clusters, deploy a Distributed S3 deployment.

S3 needs a persistent volume to store configuration and application data. For testing purposes, you can launch S3 by simply passing a directory (/data 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.

docker run \
  -p 9000:9000 \
  -p 9001:9001 \
  -e "S3_ROOT_USER=AKIAIOSFODNN7EXAMPLE" \
  -e "S3_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  ghcr.io/hanzoai/s3 server /data --console-address ":9001"

To create a S3 container with persistent storage, you need to map local persistent directories from the host OS to virtual config. To do this, run the below commands

GNU/Linux and macOS

mkdir -p ~/minio/data

docker run \
  -p 9000:9000 \
  -p 9001:9001 \
  --name minio1 \
  -v ~/minio/data:/data \
  -e "S3_ROOT_USER=AKIAIOSFODNN7EXAMPLE" \
  -e "S3_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  ghcr.io/hanzoai/s3 server /data --console-address ":9001"

The command creates a new local directory ~/minio/data in your user home directory. It then starts the S3 container with the -v argument to map the local path (~/minio/data) to the specified virtual container directory (/data). When S3 writes data to /data, that data is actually written to the local path ~/minio/data where it can persist between container restarts.

Windows

docker run \
  -p 9000:9000 \
  -p 9001:9001 \
  --name minio1 \
  -v D:\data:/data \
  -e "S3_ROOT_USER=AKIAIOSFODNN7EXAMPLE" \
  -e "S3_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  ghcr.io/hanzoai/s3 server /data --console-address ":9001"

Run Distributed S3 on Containers

We recommend kubernetes based deployment for production level deployment https://github.com/minio/operator.

See the Kubernetes documentation for more information.

S3 Docker Tips

S3 Custom Access and Secret Keys

To override S3's auto-generated keys, you may pass secret and access keys explicitly as environment variables. S3 server also allows regular strings as access and secret keys.

GNU/Linux and macOS (custom access and secret keys)

docker run \
  -p 9000:9000 \
  -p 9001:9001 \
  --name minio1 \
  -e "S3_ROOT_USER=AKIAIOSFODNN7EXAMPLE" \
  -e "S3_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  -v /mnt/data:/data \
  ghcr.io/hanzoai/s3 server /data --console-address ":9001"

Windows (custom access and secret keys)

docker run \
  -p 9000:9000 \
  -p 9001:9001 \
  --name minio1 \
  -e "S3_ROOT_USER=AKIAIOSFODNN7EXAMPLE" \
  -e "S3_ROOT_PASSWORD=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  -v D:\data:/data \
  ghcr.io/hanzoai/s3 server /data --console-address ":9001"

Run S3 Docker as a regular user

Docker provides standardized mechanisms to run docker containers as non-root users.

GNU/Linux and macOS (regular user)

On Linux and macOS you can use --user to run the container as regular user.

NOTE: make sure --user has write permission to ${HOME}/data prior to using --user.

mkdir -p ${HOME}/data
docker run \
  -p 9000:9000 \
  -p 9001:9001 \
  --user $(id -u):$(id -g) \
  --name minio1 \
  -e "S3_ROOT_USER=AKIAIOSFODNN7EXAMPLE" \
  -e "S3_ROOT_PASSWORD=wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY" \
  -v ${HOME}/data:/data \
  ghcr.io/hanzoai/s3 server /data --console-address ":9001"

Windows (regular user)

On windows you would need to use Docker integrated windows authentication and Create a container with Active Directory Support

NOTE: make sure your AD/Windows user has write permissions to D:\data prior to using credentialspec=.

docker run \
  -p 9000:9000 \
  -p 9001:9001 \
  --name minio1 \
  --security-opt "credentialspec=file://myuser.json"
  -e "S3_ROOT_USER=AKIAIOSFODNN7EXAMPLE" \
  -e "S3_ROOT_PASSWORD=wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY" \
  -v D:\data:/data \
  ghcr.io/hanzoai/s3 server /data --console-address ":9001"

S3 Custom Access and Secret Keys using Docker secrets

To override S3's auto-generated keys, you may pass secret and access keys explicitly by creating access and secret keys as Docker secrets. S3 server also allows regular strings as access and secret keys.

echo "AKIAIOSFODNN7EXAMPLE" | docker secret create access_key -
echo "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" | docker secret create secret_key -

Create a S3 service using docker service to read from Docker secrets.

docker service create --name="minio-service" --secret="access_key" --secret="secret_key" ghcr.io/hanzoai/s3 server /data

Read more about docker service here

S3 Custom Access and Secret Key files

To use other secret names follow the instructions above and replace access_key and secret_key with your custom names (e.g. my_secret_key,my_custom_key). Run your service with

docker service create --name="minio-service" \
  --secret="my_access_key" \
  --secret="my_secret_key" \
  --env="S3_ROOT_USER_FILE=my_access_key" \
  --env="S3_ROOT_PASSWORD_FILE=my_secret_key" \
  ghcr.io/hanzoai/s3 server /data

S3_ROOT_USER_FILE and S3_ROOT_PASSWORD_FILE also support custom absolute paths, in case Docker secrets are mounted to custom locations or other tools are used to mount secrets into the container. For example, HashiCorp Vault injects secrets to /vault/secrets. With the custom names above, set the environment variables to

S3_ROOT_USER_FILE=/vault/secrets/my_access_key
S3_ROOT_PASSWORD_FILE=/vault/secrets/my_secret_key

Retrieving Container ID

To use Docker commands on a specific container, you need to know the Container ID for that container. To get the Container ID, run

docker ps -a

-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 command.

docker start <container_id>

To stop a running container, you can use the docker stop command.

docker stop <container_id>

S3 container logs

To access S3 logs, you can use the docker logs command.

docker logs <container_id>

Monitor S3 Docker Container

To monitor the resources used by S3 container, you can use the docker stats command.

docker stats <container_id>

Explore Further

• S3 in a Container Installation Guide
• S3 Erasure Code QuickStart Guide