diff --git a/Makefile b/Makefile index c9360f60..6fc3467d 100644 --- a/Makefile +++ b/Makefile @@ -8,6 +8,7 @@ SPHINXBUILD ?= sphinx-build SOURCEDIR = source BUILDDIR = build GITDIR = $(shell git rev-parse --abbrev-ref HEAD) +DEB = $(curl https://min.io/assets/downloads-minio.json | jq '.Linux."MinIO Server".amd64.DEB.download') # Put it first so that "make" without argument is like "make help". help: @@ -25,6 +26,30 @@ clean: @echo "Cleaning $(BUILDDIR)/$(GITDIR)" @rm -rf $(BUILDDIR)/$(GITDIR) +sync-minio-version: + @echo "Retrieving current MinIO version" + $(shell wget -O /tmp/downloads-minio.json https://min.io/assets/downloads-minio.json) + $(eval DEB = $(shell cat /tmp/downloads-minio.json | jq '.Linux."MinIO Server".amd64.DEB.download')) + $(eval RPM = $(shell cat /tmp/downloads-minio.json | jq '.Linux."MinIO Server".amd64.RPM.download')) + $(eval MINIO = $(shell curl --retry 10 -Ls -o /dev/null -w "%{url_effective}" https://github.com/minio/minio/releases/latest | sed "s/https:\/\/github.com\/minio\/minio\/releases\/tag\///")) + + @echo "Replacing Variables" + + @cp source/default-conf.py source/conf.py + + @sed -i "s|MINIOLATEST|${MINIO}|g" source/conf.py + @sed -i "s|DEBURL|${DEB}|g" source/conf.py + @sed -i "s|RPMURL|${RPM}|g" source/conf.py + +stage: + @make clean && make html + python -m http.server --directory $(BUILDDIR)/$(GITDIR)/html + +publish: + @make sync-minio-version + @make clean + make html + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/source/conf.py b/source/conf.py index fd4e9063..32baafb9 100644 --- a/source/conf.py +++ b/source/conf.py @@ -137,4 +137,9 @@ rst_prolog = """ .. |podman| replace:: `Podman `__ .. |kes-stable| replace:: 0.16.1 +.. |minio-tag| replace:: `RELEASE.2022-01-08T03-11-54Z `__ +.. |minio-latest| replace:: RELEASE.2022-01-08T03-11-54Z +.. |minio-rpm| replace:: https://dl.min.io/server/minio/release/linux-amd64/minio-20220108031154.0.0.x86_64.rpm +.. |minio-deb| replace:: https://dl.min.io/server/minio/release/linux-amd64/minio_20220108031154.0.0_amd64.deb + """ \ No newline at end of file diff --git a/source/default-conf.py b/source/default-conf.py new file mode 100644 index 00000000..becced8c --- /dev/null +++ b/source/default-conf.py @@ -0,0 +1,145 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys + +# The current working dir seems to be /source, so we have to pop up a level +sys.path.append(os.path.abspath('../sphinxext')) + + +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'MinIO Baremetal Documentation' +copyright = '2020-Present, MinIO, Inc. ' +author = 'Ravind Kumar' + +# The full version, including alpha/beta/rc tags +release = '0.1' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.extlinks', + 'minio', + 'sphinx_copybutton', + 'sphinx_markdown_tables', + 'sphinx-prompt', + 'sphinx_substitution_extensions', + 'sphinx_togglebutton', + 'sphinxcontrib.images', + 'myst_parser', + 'sphinx_design', +] + +# -- External Links + +# Add roots for short external link references in the documentation. +# Helpful for sites we tend to make lots of references to. + +extlinks = { + 'kube-docs' : ('https://kubernetes.io/docs/%s', ''), + 'minio-git' : ('https://github.com/minio/%s',''), + 'github' : ('https://github.com/%s',''), + 'kube-api' : ('https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/%s',''), + 'aws-docs' : ('https://docs.aws.amazon.com/%s',''), + 's3-docs' : ('https://docs.aws.amazon.com/AmazonS3/latest/userguide/%s',''), + 's3-api' : ('https://docs.aws.amazon.com/AmazonS3/latest/API/%s',''), + 'iam-docs' : ('https://docs.aws.amazon.com/IAM/latest/UserGuide/%s',''), + 'minio-release' : ('https://github.com/minio/minio/releases/tag/%s',''), + 'mc-release' : ('https://github.com/minio/mc/releases/tag/%s',''), + 'legacy' : ('https://docs.min.io/docs/%s',''), + 'docs-k8s' : ('https://docs.min.io/minio/k8s/%s',''), + 'prometheus-docs' : ('https://prometheus.io/docs/%s',''), + 'podman-docs' : ('https://docs.podman.io/en/latest/%s',''), + 'podman-git' : ('https://github.com/containers/podman/%s','') + +} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['includes/*.rst', 'includes/imports/*', '*-template.rst'] + +# Copy-Button Customization + +copybutton_selector = "div.copyable pre" + +# sphinxcontrib-images customization + +images_config = { + 'override_image_directive' : True +} + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +html_favicon = '_static/favicon.png' + +html_sidebars = { + '**' : [ + 'searchbox.html', + 'navigation.html' + ] +} + +html_theme_options = { + 'fixed_sidebar' : 'true', + 'show_relbars': 'false' +} + +html_short_title = "MinIO Object Storage for Baremetal Infrastructure" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +html_css_files = ['css/main.min.css', 'custom.css'] + +html_js_files = ['js/main.js'] + +html_extra_path = [ 'extra'] + +html_permalinks_icon = "" + +html_title = 'MinIO Baremetal Documentation' + +# -- Options for Sphinx Tabs ------------------------------------------------- + +sphinx_tabs_disable_css_loading = True + +rst_prolog = """ + +.. |podman| replace:: `Podman `__ +.. |kes-stable| replace:: 0.16.1 + +.. |minio-tag| replace:: `MINIOLATEST `__ +.. |minio-latest| replace:: MINIOLATEST +.. |minio-rpm| replace:: RPMURL +.. |minio-deb| replace:: DEBURL + +""" \ No newline at end of file diff --git a/source/includes/common-installation.rst b/source/includes/common-installation.rst index d2ccab00..798e37f2 100644 --- a/source/includes/common-installation.rst +++ b/source/includes/common-installation.rst @@ -16,8 +16,9 @@ recommends using RPM or DEB installation routes. .. code-block:: shell :class: copyable + :substitutions: - wget https://dl.min.io/server/minio/release/linux-amd64/minio.rpm + wget |minio-rpm| -O minio.deb sudo dnf install minio.rpm .. tab-item:: DEB (Debian/Ubuntu) @@ -28,8 +29,9 @@ recommends using RPM or DEB installation routes. .. code-block:: shell :class: copyable + :substitutions: - wget https://dl.min.io/server/minio/release/linux-amd64/minio.deb + wget |minio-deb| -O minio.deb sudo dpkg -i minio.deb .. tab-item:: Binary @@ -53,13 +55,26 @@ MinIO enables :ref:`Transport Layer Security (TLS) ` 1.2+ automatically upon detecting a valid x.509 certificate (``.crt``) and private key (``.key``) in the MinIO ``${HOME}/.minio/certs`` directory. -If *any* MinIO server or client uses certificates signed by an unknown -Certificate Authority (self-signed or internal CA), you *must* place the CA -certs in the ``${HOME}/.minio/certs/CAs`` on all MinIO hosts in the deployment. -MinIO rejects invalid certificates (untrusted, expired, or malformed). +For ``systemd``-managed deployments, use the ``$HOME`` directory for the +user which runs the MinIO server process. The provided ``minio.service`` +file runs the process as ``minio-user``. The previous step includes instructions +for creating this user with a home directory ``/home/minio-user``. -You can override the certificate directory using the -:mc-cmd-option:`minio server certs-dir` commandline argument. +- Place TLS certificates into ``/home/minio-user/.minio/certs``. + +- If *any* MinIO server or client uses certificates signed by an unknown + Certificate Authority (self-signed or internal CA), you *must* place the CA + certs in the ``/home/minio-user/.minio/certs/CAs`` on all MinIO hosts in the + deployment. MinIO rejects invalid certificates (untrusted, expired, or + malformed). + +If the ``minio.service`` file specifies a different user account, use the +``$HOME`` directory for that account. Alternatively, specify a custom +certificate directory using the :mc-cmd-option:`minio server certs-dir` +commandline argument. Modify the ``MINIO_OPTS`` variable in +``/etc/defaults/minio`` to set this option. The ``systemd`` user which runs the +MinIO server process *must* have read and listing permissions for the specified +directory. For more specific guidance on configuring MinIO for TLS, including multi-domain support via Server Name Indication (SNI), see :ref:`minio-tls`. You can diff --git a/source/index.rst b/source/index.rst index 3a625f3d..be6431ff 100644 --- a/source/index.rst +++ b/source/index.rst @@ -8,7 +8,9 @@ Welcome to the MinIO Documentation! 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 -`__. +`__. + +This documentation targets the latest stable version of MinIO, |minio-tag|. You can get started exploring MinIO features using our ``play`` server at https://play.min.io. ``play`` is a *public* MinIO cluster running the latest diff --git a/source/installation/deploy-minio-distributed.rst b/source/installation/deploy-minio-distributed.rst index 219ab79d..42e6bac9 100644 --- a/source/installation/deploy-minio-distributed.rst +++ b/source/installation/deploy-minio-distributed.rst @@ -222,22 +222,14 @@ procedure. :start-after: start-install-minio-binary-desc :end-before: end-install-minio-binary-desc -2) Add TLS/SSL Certificates -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/common-installation.rst - :start-after: start-install-minio-tls-desc - :end-before: end-install-minio-tls-desc - - -3) Create the ``systemd`` Service File +2) Create the ``systemd`` Service File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/common-installation.rst :start-after: start-install-minio-systemd-desc :end-before: end-install-minio-systemd-desc -4) Create the Service Environment File +3) Create the Service Environment File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Create an environment file at ``/etc/default/minio``. The MinIO @@ -313,6 +305,13 @@ You may specify other :ref:`environment variables by your deployment. All MinIO nodes in the deployment should include the same environment variables with the same values for each variable. +4) Add TLS/SSL Certificates +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/common-installation.rst + :start-after: start-install-minio-tls-desc + :end-before: end-install-minio-tls-desc + 5) Run the MinIO Server Process ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~