Documentation

Deploy MinIO: Single-Node Single-Drive

The procedures on this page cover deploying MinIO in a Single-Node Single-Drive (SNSD) configuration for early development and evaluation. SNSD deployments use a zero-parity erasure coded backend that provides no added reliability or availability beyond what the underlying storage volume implements. These deployments are best suited for local testing and evaluation, or for small-scale data workloads that do not have availability or performance requirements.

For extended development or production environments, deploy MinIO in a Multi-Node Multi-Drive (Distributed) topology

Important

https://github.com/minio/minio/releases/tag/RELEASE.2022-10-29T06-21-33Z fully removes the deprecated Gateway/Filesystem backends. MinIO returns an error if it starts up and detects existing Filesystem backend files.

To migrate from an FS-backend deployment, use mc mirror or mc cp to copy your data over to a new MinIO SNSD deployment. You should also recreate any necessary users, groups, policies, and bucket configurations on the SNSD deployment.

Pre-Existing Data

MinIO startup behavior depends on the the contents of the specified storage volume or path. The server checks for both MinIO-internal backend data and the structure of existing folders and files. The following table lists the possible storage volume states and MinIO behavior:

Storage Volume State

Behavior

Empty with no files, folders, or MinIO backend data

MinIO starts in SNSD mode and creates the zero-parity backend

Existing SNSD zero-parity objects and MinIO backend data

MinIO resumes in SNSD mode

Existing filesystem folders, files, but no MinIO backend data

MinIO returns an error and does not start

Existing filesystem folders, files, and legacy “FS-mode” backend data

MinIO returns an error and does not start

Changed in version RELEASE.2022-10-29T06-21-33Z.

Prerequisites

Storage Requirements

The following requirements summarize the Storage section of MinIO’s hardware recommendations:

Use Local Storage

Direct-Attached Storage (DAS) has significant performance and consistency advantages over networked storage (NAS, SAN, NFS). MinIO strongly recommends flash storage (NVMe, SSD) for primary or “hot” data.

Use XFS-Formatting for Drives

MinIO strongly recommends provisioning XFS formatted drives for storage. MinIO uses XFS as part of internal testing and validation suites, providing additional confidence in performance and behavior at all scales.

Persist Drive Mounting and Mapping Across Reboots

Use /etc/fstab to ensure consistent drive-to-mount mapping across node reboots.

Non-Linux Operating Systems should use the equivalent drive mount management tool.

Memory Requirements

Changed in version RELEASE.2024-01-28T22-35-53Z: MinIO pre-allocates 2GiB of system memory at startup.

MinIO recommends a minimum of 32GiB of memory per host. See Memory for more guidance on memory allocation in MinIO.

Deploy Single-Node Single-Drive MinIO

The following procedure deploys MinIO consisting of a single MinIO server and a single drive or storage volume.

Network File System Volumes Break Consistency Guarantees

MinIO’s strict read-after-write and list-after-write consistency model requires local drive filesystems.

MinIO cannot provide consistency guarantees if the underlying storage volumes are NFS or a similar network-attached storage volume.

1) Download the MinIO Server

The following tabs provide examples of installing MinIO onto 64-bit Linux operating systems using RPM, DEB, or binary. The RPM and DEB packages automatically install MinIO to the necessary system paths and create a minio service for systemctl. MinIO strongly recommends using the RPM or DEB installation routes. To update deployments managed using systemctl, see Update systemctl-Managed MinIO Deployments.

amd64 (Intel or AMD 64-bit processors)

Use one of the following options to download the MinIO server installation file for a machine running Linux on an Intel or AMD 64-bit processor.

Use the following commands to download the latest stable MinIO RPM and install it.

wget https://dl.min.io/server/minio/release/linux-amd64/archive/minio-20240326221045.0.0-1.x86_64.rpm -O minio.rpm
sudo dnf install minio.rpm

Use the following commands to download the latest stable MinIO DEB and install it:

wget https://dl.min.io/server/minio/release/linux-amd64/archive/minio_20240326221045.0.0_amd64.deb -O minio.deb
sudo dpkg -i minio.deb

Use the following commands to download the latest stable MinIO binary and install it to the system $PATH:

wget https://dl.min.io/server/minio/release/linux-amd64/minio
chmod +x minio
sudo mv minio /usr/local/bin/
arm64 (Apple M1/M2 or other ARM 64-bit processors)

Use one of the following options to download the MinIO server installation file for a machine running Linux on an ARM 64-bit processor, such as the Apple M1 or M2.

Use the following commands to download the latest stable MinIO RPM and install it.

wget https://dl.min.io/server/minio/release/linux-arm64/archive/minio-20240326221045.0.0-1.aarch64.rpm -O minio.rpm
sudo dnf install minio.rpm

Use the following commands to download the latest stable MinIO DEB and install it:

wget https://dl.min.io/server/minio/release/linux-arm64/archive/minio_20240326221045.0.0_arm64.deb -O minio.deb
sudo dpkg -i minio.deb

Use the following commands to download the latest stable MinIO binary and install it to the system $PATH:

wget https://dl.min.io/server/minio/release/linux-arm64/minio
chmod +x minio
MINIO_ROOT_USER=admin MINIO_ROOT_PASSWORD=password ./minio server /mnt/data --console-address ":9001"
Other Architectures

MinIO also supports additional architectures:

  • ppc64le

  • s390x

For instructions to download the binary, RPM, or DEB files for those architectures, see the MinIO download page.

2) Create the systemd Service File

The .deb or .rpm packages install the following systemd service file to /usr/lib/systemd/system/minio.service. For binary installations, create this file manually on all MinIO hosts.

Note

systemd checks the /etc/systemd/... path before checking the /usr/lib/systemd/... path and uses the first file it finds. To avoid conflicting or unexpected configuration options, check that the file only exists at the /usr/lib/systemd/system/minio.service path.

Refer to the man page for systemd.unit for details on the file path search order.

[Unit]
Description=MinIO
Documentation=https://min.io/docs/minio/linux/index.html
Wants=network-online.target
After=network-online.target
AssertFileIsExecutable=/usr/local/bin/minio

[Service]
WorkingDirectory=/usr/local

User=minio-user
Group=minio-user
ProtectProc=invisible

EnvironmentFile=-/etc/default/minio
ExecStartPre=/bin/bash -c "if [ -z \"${MINIO_VOLUMES}\" ]; then echo \"Variable MINIO_VOLUMES not set in /etc/default/minio\"; exit 1; fi"
ExecStart=/usr/local/bin/minio server $MINIO_OPTS $MINIO_VOLUMES

# MinIO RELEASE.2023-05-04T21-44-30Z adds support for Type=notify (https://www.freedesktop.org/software/systemd/man/systemd.service.html#Type=)
# This may improve systemctl setups where other services use `After=minio.server`
# Uncomment the line to enable the functionality
# Type=notify

# Let systemd restart this service always
Restart=always

# Specifies the maximum file descriptor number that can be opened by this process
LimitNOFILE=65536

# Specifies the maximum number of threads this process can create
TasksMax=infinity

# Disable timeout logic and wait until process is stopped
TimeoutStopSec=infinity
SendSIGKILL=no

[Install]
WantedBy=multi-user.target

# Built for ${project.name}-${project.version} (${project.name})

The minio.service file runs as the minio-user User and Group by default. You can create the user and group using the groupadd and useradd commands. The following example creates the user, group, and sets permissions to access the folder paths intended for use by MinIO. These commands typically require root (sudo) permissions.

groupadd -r minio-user
useradd -M -r -g minio-user minio-user
chown minio-user:minio-user /mnt/disk1 /mnt/disk2 /mnt/disk3 /mnt/disk4

The specified drive paths are provided as an example. Change them to match the path to those drives intended for use by MinIO.

Alternatively, change the User and Group values to another user and group on the system host with the necessary access and permissions.

MinIO publishes additional startup script examples on github.com/minio/minio-service.

To update deployments managed using systemctl, see Update systemctl-Managed MinIO Deployments.

3) Create the Environment Variable File

Create an environment variable file at /etc/default/minio. For Windows hosts, specify a Windows-style path similar to C:\minio\config. The MinIO Server container can use this file as the source of all environment variables.

The following example provides a starting environment file:

# MINIO_ROOT_USER and MINIO_ROOT_PASSWORD sets the root account for the MinIO server.
# This user has unrestricted permissions to perform S3 and administrative API operations on any resource in the deployment.
# Omit to use the default values 'minioadmin:minioadmin'.
# MinIO recommends setting non-default values as a best practice, regardless of environment

MINIO_ROOT_USER=myminioadmin
MINIO_ROOT_PASSWORD=minio-secret-key-change-me

# MINIO_VOLUMES sets the storage volume or path to use for the MinIO server.

MINIO_VOLUMES="/mnt/data"

# MINIO_OPTS sets any additional commandline options to pass to the MinIO server.
# For example, `--console-address :9001` sets the MinIO Console listen port
MINIO_OPTS="--console-address :9001"

# MINIO_SERVER_URL sets the hostname of the local machine for use with the MinIO Server
# MinIO assumes your network control plane can correctly resolve this hostname to the local machine

# Uncomment the following line and replace the value with the correct hostname for the local machine and port for the MinIO server (9000 by default).

#MINIO_SERVER_URL="http://minio.example.net:9000"

Include any other environment variables as required for your deployment.

New in version Server: RELEASE.2024-03-03T17-50-39Z

MinIO automatically generates unique root credentials if all of the following conditions are true:

When those conditions are met at startup, MinIO uses the KMS to generate unique root credentials for the deployment using a hash-based message authentication code (HMAC).

If MinIO generates such credentials, the key used to generate the credentials must remain the same and continue to exist. All data on the deployment is encrypted with this key!

To rotate the generated root credentials, generate a new key in the KMS, then update the value of the MINIO_KMS_KES_KEY_NAME with the new key.

4) Start the MinIO Service

Issue the following command on the local host to start the MinIO SNSD deployment as a service:

sudo systemctl start minio.service

Use the following commands to confirm the service is online and functional:

sudo systemctl status minio.service
journalctl -f -u minio.service

MinIO may log an increased number of non-critical warnings while the server processes connect and synchronize. These warnings are typically transient and should resolve as the deployment comes online.

Changed in version RELEASE.2023-02-09T05-16-53Z: MinIO starts if it detects enough drives to meet the write quorum for the deployment.

If any drives remain offline after starting MinIO, check and cure any issues blocking their functionality before starting production workloads.

The MinIO service does not automatically start on host reboot. You must use systemctl enable minio.service to start the process as part of the host boot.

sudo systemctl enable minio.service

The journalctl output should resemble the following:

Status:         1 Online, 0 Offline.
API: http://192.168.2.100:9000  http://127.0.0.1:9000
RootUser: myminioadmin
RootPass: minio-secret-key-change-me
Console: http://192.168.2.100:9001 http://127.0.0.1:9001
RootUser: myminioadmin
RootPass: minio-secret-key-change-me

Command-line: https://min.io/docs/minio/linux/reference/minio-mc.html
   $ mc alias set myminio http://10.0.2.100:9000 myminioadmin minio-secret-key-change-me

Documentation: https://min.io/docs/minio/linux/index.html

The API block lists the network interfaces and port on which clients can access the MinIO S3 API. The Console block lists the network interfaces and port on which clients can access the MinIO Web Console.

5) Connect to the MinIO Service

You can access the MinIO Console by entering any of the hostnames or IP addresses from the MinIO server Console block in your preferred browser, such as http://localhost:9001.

Log in with the MINIO_ROOT_USER and MINIO_ROOT_PASSWORD configured in the environment file specified to the container.

MinIO Console displaying Buckets view in a fresh installation

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.

If your local host firewall permits external access to the Console port, other hosts on the same network can access the Console using the IP or hostname for your local host.

You can access the MinIO deployment over a Terminal or Shell using the MinIO Client (mc). See MinIO Client Installation Quickstart for instructions on installing mc.

Create a new alias corresponding to the MinIO deployment. Specify any of the hostnames or IP addresses from the MinIO Server API block, such as http://localhost:9000.

mc alias set http://localhost:9000 myminioadmin minio-secret-key-change-me

Replace myminioadmin and minio-secret-key-change-me with the MINIO_ROOT_USER and MINIO_ROOT_PASSWORD values in the environment file specified to the container.

You can then interact with the container using any mc command. If your local host firewall permits external access to the MinIO S3 API port, other hosts on the same network can access the MinIO deployment using the IP or hostname for your local host.