diff --git a/source/_static/scss/includes/_base.scss b/source/_static/scss/includes/_base.scss index 8d57174c..1bf9322e 100644 --- a/source/_static/scss/includes/_base.scss +++ b/source/_static/scss/includes/_base.scss @@ -199,9 +199,13 @@ button.toggle-button { } .content__main { - img { + a img { box-shadow: 0px 0px 5px lightgray; } + + a.noshadow img { + box-shadow: none; + } } ul.simple li { diff --git a/source/extra/examples/minio-dev.yaml b/source/extra/examples/minio-dev.yaml new file mode 100644 index 00000000..10de9ad1 --- /dev/null +++ b/source/extra/examples/minio-dev.yaml @@ -0,0 +1,40 @@ +# Deploys a new Namespace for the MinIO Pod +apiVersion: v1 +kind: Namespace +metadata: + name: minio-dev # Change this value if you want a different namespace name + labels: + name: minio-dev # Change this value to match metadata.name +--- +# Deploys a new MinIO Pod into the metadata.namespace Kubernetes namespace +# +# The `spec.containers[0].args` contains the command run on the pod +# The `/data` directory corresponds to the `spec.containers[0].volumeMounts[0].mountPath` +# That mount path corresponds to a Kubernetes HostPath which binds `/data` to a local drive or volume on the worker node where the pod runs +# +apiVersion: v1 +kind: Pod +metadata: + labels: + app: minio + name: minio + namespace: minio-dev # Change this value to match the namespace metadata.name +spec: + containers: + - name: minio + image: quay.io/minio/minio:latest + command: + - /bin/bash + - -c + args: + - minio server /data --console-address :9090 + volumeMounts: + - mountPath: /data + name: localvolume # Corresponds to the `spec.volumes` Persistent Volume + nodeSelector: + kubernetes.io/hostname: kubealpha.local # Specify a node label associated to the Worker Node on which you want to deploy the pod. + volumes: + - name: localvolume + hostPath: # MinIO generally recommends using locally-attached volumes + path: /mnt/disk1/data # Specify a path to a local drive or volume on the Kubernetes worker node + type: DirectoryOrCreate # The path to the last directory must exist diff --git a/source/images/logos/docker.svg b/source/images/logos/docker.svg new file mode 100644 index 00000000..87311692 --- /dev/null +++ b/source/images/logos/docker.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/source/images/logos/kubernetes.svg b/source/images/logos/kubernetes.svg new file mode 100644 index 00000000..38fb2f82 --- /dev/null +++ b/source/images/logos/kubernetes.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/source/images/logos/linux.svg b/source/images/logos/linux.svg new file mode 100644 index 00000000..71c1646f --- /dev/null +++ b/source/images/logos/linux.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/source/images/logos/macos.svg b/source/images/logos/macos.svg new file mode 100644 index 00000000..a59454a3 --- /dev/null +++ b/source/images/logos/macos.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/source/images/logos/windows.svg b/source/images/logos/windows.svg new file mode 100644 index 00000000..e245f0b1 --- /dev/null +++ b/source/images/logos/windows.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/source/images/minio-console-buckets.png b/source/images/minio-console-buckets.png new file mode 100644 index 00000000..27ca9314 Binary files /dev/null and b/source/images/minio-console-buckets.png differ diff --git a/source/images/minio-console-login.png b/source/images/minio-console-login.png new file mode 100644 index 00000000..75af7334 Binary files /dev/null and b/source/images/minio-console-login.png differ diff --git a/source/index.rst b/source/index.rst index bb8a4e78..49cf1277 100644 --- a/source/index.rst +++ b/source/index.rst @@ -41,94 +41,68 @@ for complete documentation on the available :mc:`mc` commands. Quickstart ---------- -The following steps deploys MinIO in filesystem mode with a single folder or -disk on the local host. This deployment is best used for initial evaluation of -MinIO S3-compatible object storage. Filesystem mode does not support features -such as versioning and replication. +Select the card corresponding to the platform on which you want to deploy MinIO to display instructions for deploying a :ref:`Standalone ` MinIO server appropriate for early development and evaluation environments. -1\) Create a Data Folder - Create a folder on the local drive for MinIO to use for object storage - operations. For example: +.. grid:: 3 + :gutter: 3 - .. code-block:: shell - :class: copyable - - mkdir /mnt/data - sudo chmod -R 775 /mnt/data + .. grid-item-card:: Linux + :link-type: ref + :link: quickstart-linux -2\) Download MinIO Server and Commandline Tools - Visit `https://min.io/downloads `__ and - following the instructions for your host operating system to download and - configure the :mc:`minio` and :mc:`mc` binaries. Consider adding the - ``minio`` and ``mc`` binaries to the operating system PATH for simplified - operations. + .. image:: /images/logos/linux.svg + :width: 100px + :height: 100px + :alt: Linux Quickstart + :align: center + :class: noshadow - Follow the instructions on the download site to start the :mc:`minio server` - process. For example, the following command starts the - :mc:`minio server` using the created directory: + .. grid-item-card:: MacOS + :link-type: ref + :link: quickstart-macos + + .. image:: /images/logos/macos.svg + :width: 100px + :height: 100px + :alt: MacOS Quickstart + :align: center + :class: noshadow - .. code-block:: shell - :class: copyable + .. grid-item-card:: Windows + :link-type: ref + :link: quickstart-windows + + .. image:: /images/logos/windows.svg + :width: 100px + :height: 100px + :alt: Windows Quickstart + :align: center + :class: noshadow - export MINIO_ROOT_USER=myminioaccesskey - export MINIO_ROOT_PASSWORD=myminiosecretkey + .. grid-item-card:: Kubernetes (Generic) + :link-type: ref + :link: quickstart-kubernetes + + .. image:: /images/logos/kubernetes.svg + :width: 100px + :height: 100px + :alt: Kubernetes Quickstart + :align: center + :class: noshadow - minio server /mnt/data + .. grid-item-card:: Docker / Podman + :link-type: ref + :link: quickstart-container + + .. image:: /images/logos/docker.svg + :width: 100px + :height: 100px + :alt: Docker Quickstart + :align: center + :class: noshadow + - .. list-table:: - :stub-columns: 1 - :widths: 30 60 - :width: 100% - - * - :envvar:`MINIO_ROOT_USER` - - The :ref:`root user ` access key. Replace the - sample value with a long, random, and unique string. - - * - :envvar:`MINIO_ROOT_PASSWORD` - - The :ref:`root user ` secret key. Replace the - sample value with a long, random, and unique string. - - The output resembles the following: - - .. code-block:: shell - - API: http://127.0.0.1:9000 - RootUser: minioadmin - RootPass: minioadmin - Region: us-east-1 - Console: http://127.0.0.1:64518 - RootUser: minioadmin - RootPass: minioadmin - Command-line: https://docs.min.io/docs/minio-client-quickstart-guide - $ mc alias set myminio http://127.0.0.1:9000 minioadmin minioadmin - Documentation: https://docs.min.io - - Applications should use one of the addresses listed in the :guilabel:`API` - key for connecting to and performing operations on the MinIO Tenant. - For early development and application, applications can authenticate - using the :guilabel:`RootUser` and :guilabel:`RootPass` credentials. - For long-term development and production, create dedicated users. - See :doc:`/security/iam-overview` for more information. - - You can also use the :mc:`mc` commandline tool to perform operations on the - MinIO server. Use :mc:`mc alias set` to update the ``myminio`` alias with - the access key and secret key set on the MinIO server. - -3\) Open MinIO Console - Open your browser and http://127.0.0.1:9000 to open the - :ref:`MinIO Console ` login page. - - Log in with the :guilabel:`Root User` and :guilabel:`Root Pass` from the - previous step. - - .. image:: /images/minio-console-dashboard.png - :width: 600px - :alt: MinIO Console Dashboard displaying Monitoring Data - :align: center - - You can use the MinIO Console for general administration tasks like - Identity and Access Management, Metrics and Log Monitoring, or - Server Configuration. See :ref:`minio-console` for more information. +:subscript:`All trademarks or logos displayed on this page are the property of their respective owners, and constitute neither an endorsement nor a recommendation of those organizations. In addition, such use of trademarks or links to the web sites of third-party organizations is not intended to imply, directly or indirectly, that those organizations endorse or have any affiliation with MinIO.` Licensing --------- @@ -157,6 +131,7 @@ without validating their usage do so at their own risk. :hidden: /introduction/minio-overview + /quickstart/quickstart /installation/deployment-and-management /security/iam-overview /security/encryption-overview diff --git a/source/installation/deployment-and-management.rst b/source/installation/deployment-and-management.rst index dd395774..d1584b57 100644 --- a/source/installation/deployment-and-management.rst +++ b/source/installation/deployment-and-management.rst @@ -18,20 +18,12 @@ MinIO supports two deployment modes: :guilabel:`Standalone` and :guilabel:`Distributed`: Standalone Deployments - A single MinIO server with a single storage volume or folder. Standalone - deployments are best suited for evaluation and initial development of - applications using MinIO for object storage, *or* for providing an S3 access - layer to single storage volume. Standalone deployments do not provide access - to the full set of MinIO's advanced S3 features and functionality. + A single MinIO server with a single storage volume or folder. Standalone deployments are best suited for evaluation and initial development of applications using MinIO for object storage, *or* for providing an S3 access layer to single storage volume. Standalone deployments do not provide access to the full set of MinIO's advanced S3 features and functionality - specifically those dependent on :ref:`Erasure Coding `. Distributed Deployments - One or more MinIO servers with *at least* four total storage volumes across - all servers. Distributed deployments are best for production environments and - workloads and support all of MinIO's core and advanced S3 features and - functionality. + One or more MinIO servers with *at least* four total storage volumes across all servers. Distributed deployments are best for production environments and workloads and support all of MinIO's core and advanced S3 features and functionality. - MinIO recommends a baseline topology of 4 nodes with 4 drives each - for production environments. + MinIO recommends a baseline topology of 4 nodes with 4 drives each for production environments. .. _minio-installation-comparison: diff --git a/source/quickstart/container.rst b/source/quickstart/container.rst new file mode 100644 index 00000000..e3eb1d0a --- /dev/null +++ b/source/quickstart/container.rst @@ -0,0 +1,373 @@ +.. _quickstart-container: + +========================= +Quickstart for Containers +========================= + +.. default-domain:: minio + +.. |OS| replace:: Docker or Podman + +This procedure deploys a :ref:`Standalone ` MinIO server onto |OS| for early development and evaluation of MinIO Object Storage and it's S3-compatible API layer. + +Standalone deployments (also called "filesystem mode") support a :ref:`subset of MinIO features ` where redundancy or availability are dependent entirely on the underlying drive or volume. + +For instructions on deploying to production environments, see :ref:`deploy-minio-distributed`. + +Prerequisites +------------- + +- `Podman `_ or `Docker `_ installed. +- Read, write, and delete access to the folder or drive used for the persistent volume. + +Procedure +--------- + +#. Start the container + + Select a container type to view instructions to create the container. + Instructions are available for either GNU/Linux and MacOS or for Windows. + + .. dropdown:: Podman (Rootfull or Rootless) + :name: podman-root-rootless + + These steps work for both rootfull and rootless containers. + + .. tab-set:: + + .. tab-item:: GNU/Linux or MacOS + + .. code-block:: shell + :class: copyable + + podman run \ + -p 9000:9000 \ + -p 9090:9090 \ + -v ~/minio/data:/data \ + -e "MINIO_ROOT_USER=ROOTNAME`" \ + -e "MINIO_ROOT_PASSWORD=CHANGEME123" \ + quay.io/minio/minio server /data --console-address ":9090" + + The example above works this way: + + - ``podman run`` starts the container. + The process is attached to the terminal session and ends when exiting the terminal. + - ``-p`` binds a local port to a container port. + - ``-v`` sets a file path as a persistent volume location for the container to use. + When MinIO writes data to ``/data``, that data mirrors to the local path ``~/minio/data``, allowing it to persist between container restarts. + You can set any file path to which the user has read, write, and delete permissions to use. + - ``-e`` sets the environment variables :envvar:`MINIO_ROOT_USER` and :envvar:`MINIO_ROOT_PASSWORD`, respectively. + These set the :ref:`root user credentials `. + Change the example values to use for your container. + + .. tab-item:: Windows + + .. code-block:: shell + :class: copyable + + podman run \ + -p 9000:9000 \ + -p 9090:9090 \ + -v D:\data:/data \ + -e "MINIO_ROOT_USER=ROOTNAME`" \ + -e "MINIO_ROOT_PASSWORD=CHANGEME123" \ + quay.io/minio/minio server /data --console-address ":9090" + + The example above works this way: + + - ``podman run`` starts the container. + - ``-p`` binds a local port to a container port. + - ``-v`` sets a file path as a persistent volume location for the container to use. + When MinIO writes data to ``/data``, that data mirrors to the local path ``D:\data``, allowing it to persist between container restarts. + You can set any file path to which the user has read, write, and delete permissions to use. + - ``-e`` sets the environment variables :envvar:`MINIO_ROOT_USER` and :envvar:`MINIO_ROOT_PASSWORD`, respectively. + These set the :ref:`root user credentials `. + Change the example values to use for your container. + + .. dropdown:: Docker (Rootfull) + :name: docker-rootfull + + .. tab-set:: + + .. tab-item:: GNU/Linux or MacOS + + .. code-block:: shell + :class: copyable + + mkdir -p ~/minio/data + + docker run \ + -p 9000:9000 \ + -p 9090:9090 \ + --name minio \ + -v ~/minio/data:/data \ + -e "MINIO_ROOT_USER=ROOTNAME`" \ + -e "MINIO_ROOT_PASSWORD=CHANGEME123" \ + quay.io/minio/minio server /data --console-address ":9090" + + The example above works this way: + + - ``mkdir`` creates a new local directory at ``~/minio/data`` in your home directory. + - ``docker run`` starts the MinIO container. + - ``-p`` binds a local port to a container port. + - ``-name`` creates a name for the container. + - ``-v`` sets a file path as a persistent volume location for the container to use. + When MinIO writes data to ``/data``, that data mirrors to the local path ``~/minio/data``, allowing it to persist between container restarts. + You can replace ``~/minio/data`` with another local file location to which the user has read, write, and delete access. + - ``-e`` sets the environment variables :envvar:`MINIO_ROOT_USER` and :envvar:`MINIO_ROOT_PASSWORD`, respectively. + These set the :ref:`root user credentials `. + Change the example values to use for your container. + + .. tab-item:: Windows + + .. code-block:: shell + :class: copyable + + docker run \ + -p 9000:9000 \ + -p 9090:9090 \ + --name minio1 \ + -v D:\data:/data \ + -e "MINIO_ROOT_USER=ROOTUSER" \ + -e "MINIO_ROOT_PASSWORD=CHANGEME123" \ + quay.io/minio/minio server /data --console-address ":9090" + + The example above works this way: + + - ``docker run`` starts the MinIO container. + - ``-p`` binds a local port to a container port. + - ``-v`` sets a file path as a persistent volume location for the container to use. + When MinIO writes data to ``/data``, that data mirrors to the local path ``D:\data``, allowing it to persist between container restarts. + You can replace ``D:\data`` with another local file location to which the user has read, write, and delete access. + - ``-e`` sets the environment variables :envvar:`MINIO_ROOT_USER` and :envvar:`MINIO_ROOT_PASSWORD`, respectively. + These set the :ref:`root user credentials `. + Change the example values to use for your container. + + .. dropdown:: Docker (Rootless) + :name: docker-rootless + + .. tab-set:: + + .. tab-item:: GNU/Linux or MacOS + + .. code-block:: shell + :class: copyable + + mkdir -p ${HOME}/data + + docker run \ + -p 9000:9000 \ + -p 9090:9090 \ + --user $(id -u):$(id -g) \ + --name minio1 \ + -e "MINIO_ROOT_USER=ROOTUSER" \ + -e "MINIO_ROOT_PASSWORD=CHANGEME123" \ + -v ${HOME}/minio/data:/data \ + quay.io/minio/minio server /data --console-address ":9090" + + The example above works this way: + + - ``mkdir`` creates a new local directory at ``~/minio/data`` in your home directory. + - ``docker run`` starts the MinIO container. + - ``-p`` binds a local port to a container port. + - ``-user`` sets the username for the container to the policies for the current user and user group. + - ``-name`` creates a name for the container. + - ``-v`` sets a file path as a persistent volume location for the container to use. + When MinIO writes data to ``/data``, that data actually writes to the local path ``~/minio/data`` where it can persist between container restarts. + You can replace ``${HOME}/minio/data`` with another location in the user's home directory to which the user has read, write, and delete access. + - ``-e`` sets the environment variables :envvar:`MINIO_ROOT_USER` and :envvar:`MINIO_ROOT_PASSWORD`, respectively. + These set the :ref:`root user credentials `. + Change the example values to use for your container. + + .. tab-item:: Windows + + Prerequisite: + + - Windows `Group Managed Service Account `_ already defined. + + .. code-block:: shell + :class: copyable + + docker run \ + -p 9000:9000 \ + -p 9090:9090 \ + --name minio1 \ + --security-opt "credentialspec=file://path/to/file.json" + -e "MINIO_ROOT_USER=ROOTUSER" \ + -e "MINIO_ROOT_PASSWORD=CHANGEME123" \ + -v D:\data:/data \ + quay.io/minio/minio server /data --console-address ":9090" + + The example above works this way: + + - ``docker run`` starts the MinIO container. + - ``-p`` binds a local port to a container port. + - ``-name`` creates a name for the container. + - ``--security-opt`` grants access to the container via a ``credentialspec`` file for a `Group Managed Service Account (gMSA) `_ + - ``-v`` sets a file path as a persistent volume location for the container to use. + When MinIO writes data to ``/data``, that data actually writes to the local path ``D:\data`` where it can persist between container restarts. + You can replace ``D:\data`` with another local file location to which the user has read, write, and delete access. + - ``-e`` sets the environment variables :envvar:`MINIO_ROOT_USER` and :envvar:`MINIO_ROOT_PASSWORD`, respectively. + These set the :ref:`root user credentials `. + Change the example values to use for your container. + +#. Connect your Browser to the MinIO Server + + Access the :ref:`minio-console` by going to a browser and going to ``http://127.0.0.1:9000`` or one of the Console addresses specified in the :mc:`minio server` command's output. + For example, :guilabel:`Console: http://192.0.2.10:9090 http://127.0.0.1:9090` in the example output indicates two possible addresses to use for connecting to the Console. + + While port ``9000`` is used for connecting to the API, MinIO automatically redirects browser access to the MinIO Console. + + Log in to the Console with the credentials you defined in the :envvar:`MINIO_ROOT_USER` and :envvar:`MINIO_ROOT_PASSWORD` environment variables. + + .. image:: /images/minio-console-login.png + :width: 600px + :alt: MinIO Console displaying login screen + :align: center + + You can use the MinIO Console for general administration tasks like Identity and Access Management, Metrics and Log Monitoring, or Server Configuration. + Each MinIO server includes its own embedded MinIO Console. + + .. image:: /images/minio-console-buckets.png + :width: 600px + :alt: MinIO Console displaying bucket start screen + :align: center + + For more information, see the :ref:`minio-console` documentation. + +#. `(Optional)` Install the MinIO Client + + The :ref:`MinIO Client ` allows you to work with your MinIO volume from the commandline. + + Select your operating system for instructions. + + .. dropdown:: GNU/Linux + + The :ref:`MinIO Client ` allows you to work with your MinIO server from the commandline. + + Download the :mc:`mc` client and install it to a location on your system ``PATH`` such as + ``/usr/local/bin``. You can alternatively run the binary from the download location. + + .. code-block:: shell + :class: copyable + + wget https://dl.min.io/client/mc/release/linux-amd64/mc + chmod +x mc + sudo mv mc /usr/local/bin/mc + + Use :mc-cmd:`mc alias set` to create a new alias associated to your local deployment. + You can run :mc-cmd:`mc` commands against this alias: + + .. code-block:: shell + :class: copyable + + mc alias set local http://127.0.0.1:9000 {MINIO_ROOT_USER} {MINIO_ROOT_PASSWORD} + mc admin info local + + Replace ``{MINIO_ROOT_USER}`` and ``{MINIO_ROOT_PASSWORD}`` with the credentials you defined for the container with the ``-e`` flags. + + The :mc-cmd:`mc alias set` takes four arguments: + + - The name of the alias + - The hostname or IP address and port of the MinIO server + - The Access Key for a MinIO :ref:`user ` + - The Secret Key for a MinIO :ref:`user ` + + For additional details about this command, see :ref:`alias`. + + .. dropdown:: MacOS + + The :ref:`MinIO Client ` allows you to work with your MinIO volume from the commandline. + + .. tab-set:: + + .. tab-item:: Homebrew + + Run the following command to install the latest stable MinIO Client package using `Homebrew `_. + + .. code-block:: shell + :class: copyable + + brew install minio/stable/mc + + .. tab-item:: Binary (arm64) + + Run the following commands to install the latest stable MinIO Client package using a binary package for Apple chips. + + .. code-block:: shell + :class: copyable + + curl -O https://dl.min.io/client/mc/release/darwin-arm64/mc + chmod +x mc + sudo mv mc /usr/local/bin/mc + + .. tab-item:: Binary (amd64) + + Run the following commands to install the latest stable MinIO Client package using a binary package for Intel chips. + + .. code-block:: shell + :class: copyable + + curl -O https://dl.min.io/client/mc/release/darwin-amd64/mc + chmod +x mc + sudo mv mc /usr/local/bin/mc + + Use :mc-cmd:`mc alias set` to quickly authenticate and connect to the MinIO deployment. + + .. code-block:: shell + :class: copyable + + mc alias set local http://127.0.0.1:9000 {MINIO_ROOT_USER} {MINIO_ROOT_PASSWORD} + mc admin info local + + Replace ``{MINIO_ROOT_USER}`` and ``{MINIO_ROOT_PASSWORD}`` with the credentials you defined for the container with the ``-e`` flags. + + The :mc-cmd:`mc alias set` takes four arguments: + + - The name of the alias + - The hostname or IP address and port of the MinIO server + - The Access Key for a MinIO :ref:`user ` + - The Secret Key for a MinIO :ref:`user ` + + For additional details about this command, see :ref:`alias`. + + .. dropdown:: Windows + + Download the standalone MinIO server for Windows from the following link: + + https://dl.min.io/client/mc/release/windows-amd64/mc.exe + + Double click on the file to run it. + Or, run the following in the Command Prompt or PowerShell. + + .. code-block:: + :class: copyable + + \path\to\mc.exe --help + + Use :mc-cmd:`mc alias set` to quickly authenticate and connect to the MinIO deployment. + + .. code-block:: shell + :class: copyable + + mc.exe alias set local http://127.0.0.1:9000 {MINIO_ROOT_USER} {MINIO_ROOT_PASSWORD} + mc.exe admin info local + + Replace ``{MINIO_ROOT_USER}`` and ``{MINIO_ROOT_PASSWORD}`` with the credentials you defined for the container with the ``-e`` flags. + + The :mc-cmd:`mc alias set` takes four arguments: + + - The name of the alias + - The hostname or IP address and port of the MinIO server + - The Access Key for a MinIO :ref:`user ` + - The Secret Key for a MinIO :ref:`user ` + + For additional details about this command, see :ref:`alias`. + +Next Steps +---------- + +- :ref:`Connect your applications to MinIO ` +- :ref:`Configure Object Retention ` +- :ref:`Configure Security ` +- :ref:`Deploy MinIO in a Distrbuted Environment ` \ No newline at end of file diff --git a/source/quickstart/k8s.rst b/source/quickstart/k8s.rst new file mode 100644 index 00000000..a36e63df --- /dev/null +++ b/source/quickstart/k8s.rst @@ -0,0 +1,168 @@ +.. _quickstart-kubernetes: + +========================= +Quickstart for Kubernetes +========================= + +.. default-domain:: minio + +.. |OS| replace:: Kubernetes + +This procedure deploys a :ref:`Standalone ` MinIO server onto |OS| for early development and evaluation of MinIO Object Storage and it's S3-compatible API layer. + +Standalone deployments (also called "filesystem mode") support a :ref:`subset of MinIO features ` where redundancy or availability are dependent entirely on the underlying drive or volume. + +For production-ready :ref:`Distributed ` MinIO deployments on Kubernetes, use the :docs-k8s:`MinIO Kubernetes Operator <>`. + +Prerequisites +------------- + +- An existing Kubernetes deployment where *at least* one Worker Node has a locally-attached drive. +- A local ``kubectl`` installation configured to create and access resources on the target Kubernetes deployment. +- Familiarity with Kubernetes environments +- Familiarity with using a Terminal or Shell environment + +Procedure +--------- + +#. **Download the MinIO Object** + + .. tab-set:: + + .. tab-item:: Download the MinIO Kubernetes Object Definition + + Download `minio-dev.yaml `__ to your host machine: + + .. code-block:: shell + :class: copyable + + curl https://raw.githubusercontent.com/minio/docs/master/source/extra/examples/minio-dev.yaml -O + + The file describes two Kubernetes resources: + + - A new namespace ``minio-dev``, and + - A MinIO pod using a drive or volume on the Worker Node for serving data + + Select the :guilabel:`Overview of the MinIO Object YAML` for a more detailed description of the object. + + .. tab-item:: Overview of the MinIO Object YAML + + The ``minio-dev.yaml`` contains the following Kubernetes resources: + + .. literalinclude:: /extra/examples/minio-dev.yaml + :language: yaml + + The object deploys two resources: + + - A new namespace ``minio-dev``, and + - A MinIO pod using a drive or volume on the Worker Node for serving data + + The MinIO resource definition uses Kubernetes :kube-docs:`Node Selectors and Labels ` to restrict the pod to a node with matching hostname label. + Use ``kubectl get nodes --show-labels`` to view all labels assigned to each node in the cluster. + + The MinIO Pod uses a :kube-docs:`hostPath ` volume for storing data. This path *must* correspond to a local drive or folder on the Kubernetes worker node. + + Users familiar with Kubernetes scheduling and volume provisioning may modify the ``spec.nodeSelector``, ``volumeMounts.name``, and ``volumes`` fields to meet more specific requirements. + +#. **Apply the MinIO Object Definition** + + The following command applies the ``minio-dev.yaml`` configuration and deploys the objects to Kubernetes: + + .. code-block:: shell + :class: copyable + + kubectl apply -f minio-dev.yaml + + The command output should resemble the following: + + .. code-block:: shell + + namespace/minio-dev created + pod/minio created + + You can verify the state of the pod by running ``kubectl get pods``: + + .. code-block:: shell + :class: copyable + + kubectl get pods -n minio-dev + + The output should resemble the following: + + .. code-block:: shell + + NAME READY STATUS RESTARTS AGE + minio 1/1 Running 0 77s + + You can also use the following commands to retrieve detailed information on the pod status: + + .. code-block:: shell + :class: copyable + + kubectl describe pod/minio -n minio-dev + + kubectl logs pod/minio -n minio-dev + +#. **Temporarily Access the MinIO S3 API and Console** + + Use the ``kubectl port-forward`` command to temporarily forward traffic from the MinIO pod to the local machine: + + .. code-block:: shell + :class: copyable + + kubectl port-forward pod/minio 9000 9090 + + The command forwards the pod ports ``9000`` and ``9090`` to the matching port on the local machine while active in the shell. + The ``kubectl port-forward`` command only functions while active in the shell session. + Terminating the session closes the ports on the local machine. + + .. note:: + + The following steps of this procedure assume an active ``kubectl port-forward`` command. + + To configure long term access to the pod, configure :kube-docs:`Ingress ` or similar network control components within Kubernetes to route traffic to and from the pod. Configuring Ingress is out of the scope for this documentation. + +#. **Connect your Browser to the MinIO Server** + + Access the :ref:`minio-console` by opening a browser on the local machine and navigating to ``http://127.0.0.1:9090``. + + Log in to the Console with the credentials ``minioadmin | minioadmin``. + These are the default :ref:`root user ` credentials. + + .. image:: /images/minio-console-login.png + :width: 600px + :alt: MinIO Console displaying login screen + :align: center + + You can use the MinIO Console for general administration tasks like Identity and Access Management, Metrics and Log Monitoring, or Server Configuration. + Each MinIO server includes its own embedded MinIO Console. + + .. image:: /images/minio-console-buckets.png + :width: 600px + :alt: MinIO Console displaying bucket start screen + :align: center + + For more information, see the :ref:`minio-console` documentation. + +#. **(Optional) Connect the MinIO Client** + + If your local machine has :mc:`mc` :ref:`installed `, use the :mc-cmd:`mc alias set` command to authenticate and connect to the MinIO deployment: + + .. code-block:: shell + :class: copyable + + mc alias set k8s-minio-dev http://127.0.0.1:9000 minioadmin minioadmin + mc admin info k8s-minio-dev + + - The name of the alias + - The hostname or IP address and port of the MinIO server + - The Access Key for a MinIO :ref:`user ` + - The Secret Key for a MinIO :ref:`user ` + +Next Steps +---------- + +- :ref:`Connect your applications to MinIO ` +- :ref:`Configure Object Retention ` +- :ref:`Configure Security ` +- :ref:`Deploy MinIO for Production Environments ` diff --git a/source/quickstart/linux.rst b/source/quickstart/linux.rst new file mode 100644 index 00000000..961a4826 --- /dev/null +++ b/source/quickstart/linux.rst @@ -0,0 +1,132 @@ +.. _quickstart-linux: + +==================== +Quickstart for Linux +==================== + +.. default-domain:: minio + +.. |OS| replace:: Linux + +This procedure deploys a :ref:`Standalone ` MinIO server onto |OS| for early development and evaluation of MinIO Object Storage and it's S3-compatible API layer. + +Standalone deployments (also called "filesystem mode") support a :ref:`subset of MinIO features ` where redundancy or availability are dependent entirely on the underlying drive or volume. + +For instructions on deploying to production environments, see :ref:`deploy-minio-distributed`. + +Prerequisites +------------- + +- Read, Write and Execute permissions on your local user folder (e.g. ``~/minio``). +- Permission to install binaries to the system ``PATH`` (e.g. access to ``/usr/local/bin``). +- Familiarity with the Linux terminal or shell (Bash, ZSH, etc.). +- A 64-bit Linux OS (e.g. RHEL 8, Ubuntu LTS releases). + +Procedure +--------- + +#. **Install the MinIO Server** + + .. include:: /includes/common-installation.rst + :start-after: start-install-minio-binary-desc + :end-before: end-install-minio-binary-desc + +#. **Launch the MinIO Server** + + Run the following command from the system terminal or shell to start a local MinIO instance using the ``~/minio`` folder. You can replace this path with another folder path on the local machine: + + .. code-block:: shell + :class: copyable + + mkdir ~/minio + minio server ~/minio --console-address :9090 + + The ``mkdir`` command creates the folder explicitly at the specified path. + + The ``minio server`` command starts the MinIO server. The path argument + ``~/minio`` identifies the folder in which the server operates. + + The :mc:`minio server` process prints its output to the system console, similar to the following: + + .. code-block:: shell + + API: http://192.0.2.10:9000 http://127.0.0.1:9000 + RootUser: minioadmin + RootPass: minioadmin + + Console: http://192.0.2.10:9090 http://127.0.0.1:9090 + RootUser: minioadmin + RootPass: minioadmin + + Command-line: https://docs.min.io/docs/minio-client-quickstart-guide + $ mc alias set myminio http://192.0.2.10:9000 minioadmin minioadmin + + Documentation: https://docs.min.io + + WARNING: Detected default credentials 'minioadmin:minioadmin', we recommend that you change these values with 'MINIO_ROOT_USER' and 'MINIO_ROOT_PASSWORD' environment variables. + +#. **Connect Your Browser to the MinIO Server** + + Open http://127.0.0.1:9000 in a web browser to access the :ref:`MinIO Console `. + You can alternatively enter any of the network addresses specified as part of the server command output. + For example, :guilabel:`Console: http://192.0.2.10:9090 http://127.0.0.1:9090` in the example output indicates two possible addresses to use for connecting to the Console. + + While the port ``9000`` is used for connecting to the API, MinIO automatically redirects browser access to the MinIO Console. + + Log in to the Console with the ``RootUser`` and ``RootPass`` user credentials displayed in the output. + These default to ``minioadmin | minioadmin``. + + .. image:: /images/minio-console-login.png + :width: 600px + :alt: MinIO Console displaying login screen + :align: center + + You can use the MinIO Console for general administration tasks like Identity and Access Management, Metrics and Log Monitoring, or Server Configuration. + Each MinIO server includes its own embedded MinIO Console. + + .. image:: /images/minio-console-buckets.png + :width: 600px + :alt: MinIO Console displaying bucket start screen + :align: center + + For more information, see the :ref:`minio-console` documentation. + +#. `(Optional)` **Install the MinIO Client** + + The :ref:`MinIO Client ` allows you to work with your MinIO server from the commandline. + + Download the :mc:`mc` client and install it to a location on your system ``PATH`` such as + ``/usr/local/bin``. You can alternatively run the binary from the download location. + + .. code-block:: shell + :class: copyable + + wget https://dl.min.io/client/mc/release/linux-amd64/mc + chmod +x mc + sudo mv mc /usr/local/bin/mc + + Use :mc-cmd:`mc alias set` to create a new alias associated to your local deployment. + You can run :mc-cmd:`mc` commands against this alias: + + .. code-block:: shell + :class: copyable + + mc alias set local http://127.0.0.1:9000 minioadmin minioadmin + mc admin info local + + The :mc-cmd:`mc alias set` takes four arguments: + + - The name of the alias + - The hostname or IP address and port of the MinIO server + - The Access Key for a MinIO :ref:`user ` + - The Secret Key for a MinIO :ref:`user ` + + The example above uses the :ref:`root user `. + +Next Steps +---------- + +- :ref:`Connect your applications to MinIO ` +- :ref:`Configure Object Retention ` +- :ref:`Configure Security ` +- :ref:`Deploy MinIO for Production Environments ` diff --git a/source/quickstart/macos.rst b/source/quickstart/macos.rst new file mode 100644 index 00000000..7e1c9e63 --- /dev/null +++ b/source/quickstart/macos.rst @@ -0,0 +1,203 @@ +.. _quickstart-macos: + +======================= +Quickstart for Mac OSX +======================= + +.. default-domain:: minio + +.. |OS| replace:: MacOS + +This procedure deploys a :ref:`Standalone ` MinIO server onto |OS| for early development and evaluation of MinIO Object Storage and it's S3-compatible API layer. + +Standalone deployments (also called "filesystem mode") support a :ref:`subset of MinIO features ` where redundancy or availability are dependent entirely on the underlying drive or volume. + +For instructions on deploying to production environments, see :ref:`deploy-minio-distributed`. + +Prerequisites +------------- + +- Read, write, and execute permissions for the user's home directory +- Familiarity with using the Terminal + +Procedure +--------- + +#. Install the MinIO Server + + .. tab-set:: + + .. tab-item:: Homebrew + + Open a Terminal and run the following command to install the latest stable MinIO package using `Homebrew `_. + + .. code-block:: shell + :class: copyable + + brew install minio/stable/minio + + .. important:: + + If you previously installed the MinIO server using ``brew install minio``, then we recommend that you reinstall from ``minio/stable/minio`` instead. + + .. code-block:: shell + :class: copyable + + brew uninstall minio + brew install minio/stable/minio + + .. tab-item:: Binary - arm64 + + Open a Terminal, then use the following commands to download the standalone MinIO server for MacOS and make it executable. + + .. code-block:: shell + :class: copyable + + curl -O https://dl.min.io/server/minio/release/darwin-arm64/minio + chmod +x minio + + .. tab-item:: Binary - amd64 + + Open a Terminal, then use the following commands to download the standalone MinIO server for MacOS and make it executable. + + .. code-block:: shell + :class: copyable + + curl -O https://dl.min.io/server/minio/release/darwin-amd64/minio + chmod +x minio + +#. Launch the :mc:`minio server` + + From the Terminal, use this command to start a local MinIO instance in the ``~/data`` folder. + If desired, you can replace ``~/data`` with another location to which the user has read, write, and delete access for the MinIO instance. + + .. code-block:: shell + :class: copyable + + ~/minio server ~/data --console-address :9090 + + If you installed with Homebrew, do not include the ``~/`` at the beginning of the command. + + The :mc:`minio server` process prints its output to the system console, similar to the following: + + .. code-block:: shell + + API: http://192.0.2.10:9000 http://127.0.0.1:9000 + RootUser: minioadmin + RootPass: minioadmin + + Console: http://192.0.2.10:9090 http://127.0.0.1:9090 + RootUser: minioadmin + RootPass: minioadmin + + Command-line: https://docs.min.io/docs/minio-client-quickstart-guide + $ mc alias set myminio http://192.0.2.10:9000 minioadmin minioadmin + + Documentation: https://docs.min.io + + WARNING: Detected default credentials 'minioadmin:minioadmin', we recommend that you change these values with 'MINIO_ROOT_USER' and 'MINIO_ROOT_PASSWORD' environment variables. + +#. Connect your Browser to the MinIO Server + + Access the :ref:`minio-console` by going to a browser (such as Safari) and going to ``https://127.0.0.1:9000`` or one of the Console addresses specified in the :mc:`minio server` command's output. + For example, :guilabel:`Console: http://192.0.2.10:9090 http://127.0.0.1:9090` in the example output indicates two possible addresses to use for connecting to the Console. + + While port ``9000`` is used for connecting to the API, MinIO automatically redirects browser access to the MinIO Console. + + Log in to the Console with the ``RootUser`` and ``RootPass`` user credentials displayed in the output. + These default to ``minioadmin | minioadmin``. + + .. image:: /images/minio-console-login.png + :width: 600px + :alt: MinIO Console displaying login screen + :align: center + + You can use the MinIO Console for general administration tasks like Identity and Access Management, Metrics and Log Monitoring, or Server Configuration. + Each MinIO server includes its own embedded MinIO Console. + + .. image:: /images/minio-console-buckets.png + :width: 600px + :alt: MinIO Console displaying bucket start screen + :align: center + + For more information, see the :ref:`minio-console` documentation. + +#. `(Optional)` Install the MinIO Client + + The :ref:`MinIO Client ` allows you to work with your MinIO volume from the commandline. + + .. tab-set:: + + .. tab-item:: Homebrew + + Run the following commands to install the latest stable MinIO Client package using `Homebrew `_. + + .. code-block:: shell + :class: copyable + + brew install minio/stable/mc + + To use the command, run + + .. code-block:: + + mc {command} {flag} + + .. tab-item:: Binary (arm64) + + Download the standalone MinIO server for MacOS and make it executable. + + .. code-block:: shell + :class: copyable + + curl -O https://dl.min.io/client/mc/release/darwin-arm64/mc + chmod +x mc + sudo mv mc /usr/local/bin/mc + + To use the command, run + + .. code-block:: shell + + mc {command} {flag} + + .. tab-item:: Binary (amd64) + + Download the standalone MinIO server for MacOS and make it executable. + + .. code-block:: shell + :class: copyable + + curl -O https://dl.min.io/client/mc/release/darwin-amd64/mc + chmod +x mc + sudo mv mc /usr/local/bin/mc + + To use the command, run + + .. code-block:: shell + + mc {command} {flag} + + Use :mc-cmd:`mc alias set` to quickly authenticate and connect to the MinIO deployment. + + .. code-block:: shell + :class: copyable + + mc alias set local http://127.0.0.1:9000 minioadmin minioadmin + mc admin info local + + The :mc-cmd:`mc alias set` takes four arguments: + + - The name of the alias + - The hostname or IP address and port of the MinIO server + - The Access Key for a MinIO :ref:`user ` + - The Secret Key for a MinIO :ref:`user ` + + For additional details about this command, see :ref:`alias`. + +Next Steps +---------- + +- :ref:`Connect your applications to MinIO ` +- :ref:`Configure Object Retention ` +- :ref:`Configure Security ` +- :ref:`Deploy MinIO for Production Environments ` diff --git a/source/quickstart/quickstart.rst b/source/quickstart/quickstart.rst new file mode 100644 index 00000000..ffa84427 --- /dev/null +++ b/source/quickstart/quickstart.rst @@ -0,0 +1,83 @@ +.. _quickstart-index: + +========== +Quickstart +========== + +.. default-domain:: minio + +MinIO is a high performance object storage solution with native support for Kubernetes deployments. MinIO provides an Amazon Web Services S3-compatible API and supports all core S3 features. MinIO is released under `GNU Affero General Public License v3.0 `__. + +Select the card corresponding to the platform on which you want to deploy MinIO to display instructions for deploying a :ref:`Standalone ` MinIO server appropriate for early development and evaluation environments. + +.. grid:: 3 + :gutter: 3 + + .. grid-item-card:: Linux + :link-type: ref + :link: quickstart-linux + + .. image:: /images/logos/linux.svg + :width: 100px + :height: 100px + :alt: Linux Quickstart + :align: center + :class: noshadow + + .. grid-item-card:: MacOS + :link-type: ref + :link: quickstart-macos + + .. image:: /images/logos/macos.svg + :width: 100px + :height: 100px + :alt: MacOS Quickstart + :align: center + :class: noshadow + + .. grid-item-card:: Windows + :link-type: ref + :link: quickstart-windows + + .. image:: /images/logos/windows.svg + :width: 100px + :height: 100px + :alt: Windows Quickstart + :align: center + :class: noshadow + + .. grid-item-card:: Kubernetes (Generic) + :link-type: ref + :link: quickstart-kubernetes + + .. image:: /images/logos/kubernetes.svg + :width: 100px + :height: 100px + :alt: Kubernetes Quickstart + :align: center + :class: noshadow + + .. grid-item-card:: Docker / Podman + :link-type: ref + :link: quickstart-container + + .. image:: /images/logos/docker.svg + :width: 100px + :height: 100px + :alt: Docker Quickstart + :align: center + :class: noshadow + + + +:subscript:`All trademarks or logos displayed on this page are the property of their respective owners, and constitute neither an endorsement nor a recommendation of those organizations. In addition, such use of trademarks or links to the web sites of third-party organizations is not intended to imply, directly or indirectly, that those organizations endorse or have any affiliation with MinIO.` + +.. toctree:: + :titlesonly: + :hidden: + + /quickstart/linux + /quickstart/container + /quickstart/macos + /quickstart/windows + /quickstart/k8s \ No newline at end of file diff --git a/source/quickstart/windows.rst b/source/quickstart/windows.rst new file mode 100644 index 00000000..98b79f54 --- /dev/null +++ b/source/quickstart/windows.rst @@ -0,0 +1,137 @@ +.. _quickstart-windows: + +====================== +Quickstart for Windows +====================== + +.. default-domain:: minio + +.. |OS| replace:: Windows + +This procedure deploys a :ref:`Standalone ` MinIO server onto |OS| for early development and evaluation of MinIO Object Storage and it's S3-compatible API layer. + +Standalone deployments (also called "filesystem mode") support a :ref:`subset of MinIO features ` where redundancy or availability are dependent entirely on the underlying drive or volume. + +For instructions on deploying to production environments, see :ref:`deploy-minio-distributed`. + +Prerequisites +------------- + +- Read, write, and execute permissions for the preferred local directory or file path +- Familiarity with using the Command Prompt or PowerShell + +Procedure +--------- + +#. Install the MinIO Server + + Download the MinIO executable from the following URL: + + .. code-block:: shell + :class: copyable + + https://dl.min.io/server/minio/release/windows-amd64/minio.exe + + The next step includes instructions for running the executable. + You cannot run the executable from the Explorer or by double clicking the file. + Instead, you call the executable to launch the server. + +#. Launch the :mc:`minio server` + + In PowerShell or the Command Prompt, navigate to the location of the executable or add the path of the ``minio.exe`` file to the system ``$PATH``. + + Use this command to start a local MinIO instance in the ``C:\minio`` folder. + You can replace ``C:\minio`` with another drive or folder path on the local computer. + + .. code-block:: + :class: copyable + + .\minio.exe server C:\minio --console-address :9090 + + The :mc:`minio server` process prints its output to the system console, similar to the following: + + .. code-block:: shell + + API: http://192.0.2.10:9000 http://127.0.0.1:9000 + RootUser: minioadmin + RootPass: minioadmin + + Console: http://192.0.2.10:9090 http://127.0.0.1:9090 + RootUser: minioadmin + RootPass: minioadmin + + Command-line: https://docs.min.io/docs/minio-client-quickstart-guide + $ mc alias set myminio http://192.0.2.10:9000 minioadmin minioadmin + + Documentation: https://docs.min.io + + WARNING: Detected default credentials 'minioadmin:minioadmin', we recommend that you change these values with 'MINIO_ROOT_USER' and 'MINIO_ROOT_PASSWORD' environment variables. + + The process is tied to the current PowerShell or Command Prompt window. + Closing the window stops the server and ends the process. + +#. Connect your Browser to the MinIO Server + + Access the :ref:`minio-console` by going to a browser (such as Microsoft Edge) and going to ``http://127.0.0.1:9000`` or one of the Console addresses specified in the :mc:`minio server` command's output. + For example, :guilabel:`Console: http://192.0.2.10:9090 http://127.0.0.1:9090` in the example output indicates two possible addresses to use for connecting to the Console. + + While port ``9000`` is used for connecting to the API, MinIO automatically redirects browser access to the MinIO Console. + + Log in to the Console with the ``RootUser`` and ``RootPass`` user credentials displayed in the output. + These default to ``minioadmin | minioadmin``. + + .. image:: /images/minio-console-login.png + :width: 600px + :alt: MinIO Console displaying login screen + :align: center + + You can use the MinIO Console for general administration tasks like Identity and Access Management, Metrics and Log Monitoring, or Server Configuration. + Each MinIO server includes its own embedded MinIO Console. + + .. image:: /images/minio-console-buckets.png + :width: 600px + :alt: MinIO Console displaying bucket start screen + :align: center + + For more information, see the :ref:`minio-console` documentation. + +#. `(Optional)` Install the MinIO Client + + The :ref:`MinIO Client ` allows you to work with your MinIO volume from the commandline. + + Download the standalone MinIO server for Windows from the following link: + + https://dl.min.io/client/mc/release/windows-amd64/mc.exe + + Double click on the file to run it. + Or, run the following in the Command Prompt or PowerShell. + + .. code-block:: + :class: copyable + + \path\to\mc.exe --help + + Use :mc-cmd:`mc.exe alias set ` to quickly authenticate and connect to the MinIO deployment. + + .. code-block:: shell + :class: copyable + + mc.exe alias set local http://127.0.0.1:9000 minioadmin minioadmin + mc.exe admin info local + + The :mc-cmd:`mc.exe alias set ` takes four arguments: + + - The name of the alias + - The hostname or IP address and port of the MinIO server + - The Access Key for a MinIO :ref:`user ` + - The Secret Key for a MinIO :ref:`user ` + + For additional details about this command, see :ref:`alias`. + +Next Steps +---------- + +- :ref:`Connect your applications to MinIO ` +- :ref:`Configure Object Retention ` +- :ref:`Configure Security ` +- :ref:`Deploy MinIO for Production Environments ` diff --git a/source/reference/minio-mc.rst b/source/reference/minio-mc.rst index 4555fb8a..c797aa5a 100644 --- a/source/reference/minio-mc.rst +++ b/source/reference/minio-mc.rst @@ -1,3 +1,5 @@ +.. _minio-client: + ===================== MinIO Client (``mc``) =====================