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 in orchestrated environments, use the MinIO Kubernetes Operator to deploy a Tenant on multiple worker nodes.

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.

Exclusive access to drives

MinIO requires exclusive access to the drives or volumes provided for object storage. No other processes, software, scripts, or persons should perform any actions directly on the drives or volumes provided to MinIO or the objects or files MinIO places on them.

Unless directed by MinIO Engineering, do not use scripts or tools to directly modify, delete, or move any of the data shards, parity shards, or metadata files on the provided drives, including from one drive or node to another. Such operations are very likely to result in widespread corruption and data loss beyond MinIO’s ability to heal.

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) Pull the Latest Stable Image of MinIO

Select the tab for either Podman or Docker to see instructions for pulling the MinIO container image. The instructions include examples for both quay.io and DockerHub:

Podman

quay.io

podman pull quay.io/minio/minio

DockerHub

podman pull docker://minio/minio

Docker

quay.io

docker pull quay.io/minio/minio

DockerHub

docker pull docker://minio/minio

2) 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:

KES Release 2024-03-01T18-06-46Z or later running
Have not defined: - MINIO_ROOT_USER variable - MINIO_ROOT_PASSWORD variable
Have: - set up KES with a supported KMS target - disabled root access with the MinIO environment variable

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.

3) Create and Run the Container

Select the container management interface of your choice for the relevant command syntax.

Podman

Copy the command to a text file for further modification.

podman run -dt                                  \
  -p 9000:9000 -p 9001:9001                     \
  -v PATH:/mnt/data                             \
  -v /etc/default/minio:/etc/config.env         \
  -e "MINIO_CONFIG_ENV_FILE=/etc/config.env"    \
  --name "minio_local"                          \
  minio server --console-address ":9001"

Specify any other options to podman run as necessary for your local environment.

Docker

Copy the command to a text file for further modification.

docker run -dt                                  \
  -p 9000:9000 -p 9001:9001                     \
  -v PATH:/mnt/data                             \
  -v /etc/default/minio:/etc/config.env         \
  -e "MINIO_CONFIG_ENV_FILE=/etc/config.env"    \
  --name "minio_local"                          \
  minio server --console-address ":9001"

Specify any other options to docker run as necessary for your local environment.

For running Docker in Rootless mode, you may need to set the following additional Docker CLI options:

Linux: --user $(id -u):$(id -g) - directs the container to run as the currently logged in user.
Windows: --security-opt "credentialspec=file://path/to/file.json" - directs the container to run using a Windows Group Managed Service Account.

The following table describes each line of the command and provides additional configuration instructions:

Line	Description
`podman run -dt` `docker run -dt`	Directs Podman/Docker to create and start the container as a detached (`-d`) background process with a pseudo-TTY (`-t`). This allows the container to run in the background with an open TTY for bash-like access.
`-p 9000:9000 -p 9001:9001`	Binds the ports `9000` and `9090` on the local machine to the same ports on the container. This allows access to the container through the local machine.
`-v PATH:/data/minio`	Binds the storage volume `PATH` on the local machine to the `/data` path on the container. Replace this value with the full path to a storage volume or folder on the local machine. For example: Linux or MacOS `~/minio/data/` Windows `C:\minio\data`
`-v /etc/default/minio:/etc/config.env`	Mounts the environment file created in the previous step to the `/etc/config.env` path on the Container. For Windows hosts, specify the Windows-style path `-v C:\minio\config:/etc/config.env`. The MinIO Server uses this environment file for configuration.
`-e "MINIO_CONFIG_ENV_FILE=/etc/config.env"`	Sets a MinIO environment variable pointing to the container-mounted path of the environment file.
`--name "minio_local"`	Sets a custom name for the container. Omit this value to allow Podman/Docker to automatically generate a container name. You can replace this value to best reflect your requirements.
`minio server --console-address ":9001"`	Starts the MinIO server using the `minio:minio` image pulled from an earlier step. The `minio server --console-address ":9001"` option directs the server to set a static port for the MinIO Console Web Interface. This option is required for containerized environments. If you modify this value, ensure you set the proper port mapping using the `-p` flag to Podman/Docker to ensure traffic forwarding between the local host and the container.

Once you have applied any further customizations to the command, run it in your preferred terminal or shell environment. The command should return a unique ID for the created container.

4) Validate the Container Status

Podman

Run the following command to retrieve logs from the container. Replace the container name with the value specified to --name in the previous step.

podman logs minio

The command should return output similar to the following:

Docker

Run the following command to retrieve logs from the container. Replace the container name with the value specified to --name in the previous step.

docker logs minio

The command should return output similar to the following:

Status:         1 Online, 0 Offline.
API: http://10.0.2.100:9000  http://127.0.0.1:9000
RootUser: myminioadmin
RootPass: minio-secret-key-change-me
Console: http://10.0.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/container/index.html

Container Networks May Not Be Accessible Outside of the Host

The API and CONSOLE blocks may include the network interfaces for the container. Clients outside of the container network cannot access the MinIO API or Console using these addresses.

External access requires using a network address for the container host machine and assumes the host firewall allows access to the related ports (9000 and 9090 in the examples).

5) Connect to the MinIO Service

MinIO Web Console

You can access the MinIO Web Console by entering http://localhost:9001 in your preferred browser. Any traffic to the MinIO Console port on the local host redirects to the container.

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.

MinIO CLI (mc)

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. Use a hostname or IP address for your local machine along with the S3 API port 9000 to access the MinIO deployment. Any traffic to that port on the local host redirects to the container.

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.

The command should return success if the container is running and accessible at the specified port.

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.