Running MinIO with Docker gives self-hosted applications an S3-compatible storage endpoint for uploads, backups, media, and generated files. This checklist covers a durable deployment, bucket design, least-privilege access, TLS, lifecycle rules, upgrades, and recovery testing.
Overview
MinIO is best treated as infrastructure rather than as another disposable container. The container can be recreated; the object data, credentials, configuration, and recovery process must be deliberately managed. Before starting, decide whether the service belongs on a home server, a private network, or a VPS for self-hosting. A public deployment needs firewall rules, HTTPS, monitoring, and an offsite copy. A private deployment still needs access controls and tested backups.
Use separate storage for MinIO data and the operating system when practical. Confirm that the filesystem is mounted before Docker starts, because an absent mount can otherwise cause Docker to create an ordinary directory on the root disk. Also reserve capacity for temporary growth, object versions, logs, and recovery operations rather than planning to fill the disk completely.
The following Docker Compose example is a starting point, not a production architecture:
services:
minio:
image: minio/minio:REVIEWED_RELEASE_TAG
container_name: minio
restart: unless-stopped
command: server /data --console-address ":9001"
environment:
MINIO_ROOT_USER: ${MINIO_ROOT_USER}
MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
ports:
- "9000:9000"
- "9001:9001"
volumes:
- /srv/minio/data:/data
healthcheck:
test: ["CMD", "mc", "ready", "local"]
interval: 30s
timeout: 10s
retries: 3
Replace REVIEWED_RELEASE_TAG with a version you have reviewed and tested. Do not use an unreviewed floating image tag for a service that holds application data. Store the environment file outside source control, restrict its permissions, and keep the root credentials out of application configuration.
For a first deployment, bind the S3 API and console to a private interface or place them behind a reverse proxy. The S3 API normally uses port 9000 and the administrative console uses port 9001 in this layout. A reverse proxy should provide separate hostnames, such as s3.example.net and minio-console.example.net, with valid TLS certificates and any required upload-size or timeout settings.
Checklist by scenario
For a new self-hosted application
- Create a dedicated bucket, rather than placing every application in one shared bucket.
- Create a dedicated application access key and secret. Do not give the application root credentials.
- Record the endpoint, region value expected by the client, bucket name, and whether path-style addressing is required.
- Grant only the actions the application needs. A file uploader may need object read and write access but not bucket administration.
- Test an upload, download, overwrite, and delete operation using the application itself.
For backups
- Use a separate backup bucket or separate MinIO deployment where practical.
- Keep database dumps and application files distinguishable with prefixes such as
postgres/,uploads/, andexports/. - Decide whether versioning is needed. It can help recover from accidental overwrites, but it also increases storage consumption.
- Copy important objects to a different storage system or location. A second bucket on the same disk is not an independent backup.
- Document how to restore both the objects and the application metadata that refers to them.
For a homelab or private network
- Keep the console and API off the public internet unless there is a clear reason to expose them.
- Use firewall rules, VPN access, or an authenticated reverse proxy for administration.
- Monitor disk usage, filesystem health, container restarts, and failed authentication attempts.
- Protect the server from loss of power and verify that storage mounts return correctly after reboot.
For a public VPS deployment
- Allow only required ports through the host and provider firewalls.
- Terminate TLS at a maintained reverse proxy or configure MinIO TLS according to the release documentation.
- Use strong, unique credentials and rotate application keys without interrupting service.
- Set resource and storage alerts before applications begin uploading data.
Bucket, policy, and client configuration
A useful S3-compatible configuration record looks like this:
| Setting | Example or decision | Why it matters |
|---|---|---|
| Endpoint | https://s3.example.net | The URL applications use to reach the S3 API. |
| Bucket | paperless-files | Separates data ownership and permissions. |
| Region | The value required by the client | Some SDKs require a non-empty region even when the server is private. |
| Addressing | Virtual-hosted or path-style | DNS and TLS setup can affect which mode works reliably. |
| Credentials | Dedicated application key pair | Limits the impact of a leaked secret. |
| TLS verification | Enabled | Prevents silent interception and certificate mistakes. |
Use the MinIO Client, commonly called mc, for repeatable administration. The exact administrative command names can change between releases, so check mc --help and the documentation for the image you selected. A basic workflow is:
mc alias set local https://s3.example.net ADMIN_USER ADMIN_SECRET
mc mb local/paperless-files
mc version enable local/paperless-files
mc ls local
For policies, define the smallest useful permission set. A read-write application policy might allow s3:GetObject, s3:PutObject, and s3:DeleteObject only against one bucket's object path. A read-only worker should receive only s3:GetObject. Bucket listing and administrative actions should be omitted unless the application explicitly requires them. Bind the policy to a dedicated identity using the supported mc admin commands for your installed client version.
Lifecycle rules should match retention requirements, not merely reduce disk usage. For example, temporary exports can expire after a defined period, while legal, financial, or user-managed files may need indefinite retention. Test lifecycle behavior with disposable objects first, and remember that versioning can retain older versions after a current object appears to be deleted.
What to double-check
- Persistent storage: Confirm the host path, ownership, filesystem capacity, mount order, and available inode capacity.
- Credentials: Keep root access for administration only. Store secrets in a protected environment file or secret manager.
- TLS: Verify the certificate hostname, renewal process, proxy WebSocket behavior for the console, and large-upload timeouts.
- Policies: Test permissions with the actual application identity. A policy that is too broad is a security risk; one that is too narrow creates confusing application failures.
- Backups: Confirm that backups include object data, bucket configuration, policies, and the application database that maps records to object keys.
- Capacity: Track current use, growth rate, retained versions, replication copies, and the space required for a restore test.
- Compatibility: Check the SDK's required region, signing behavior, multipart upload support, and path-style addressing before migrating an application.
For a restore-validation workflow, create a temporary bucket, restore a representative sample, and compare object counts, sizes, checksums where available, metadata, and application behavior. Then restore the related database into an isolated environment and confirm that links resolve. A backup that can be copied but cannot be consumed by the application is not a complete recovery plan. See the Docker backup strategy for self-hosted apps for a broader volume, database, and restore-testing checklist.
Common mistakes
- Using root credentials in a web application or putting them in a committed Compose file.
- Exposing the console directly to the internet without TLS and administrative access controls.
- Using one bucket and one unrestricted identity for every self-hosted app.
- Running a floating container image and discovering an incompatibility during an unattended update.
- Assuming RAID, snapshots, or object versioning alone constitute an offsite backup.
- Deleting old objects without considering versioned objects, incomplete multipart uploads, or application references.
- Testing only the S3 API while ignoring the reverse proxy, DNS, certificate renewal, and upload-size limits.
When upgrading, record the current image tag, Compose configuration, host mounts, and client version. Take a verified backup, read the release notes and upgrade guidance, pull the new image, recreate the container, inspect logs, and test authentication, listing, upload, download, deletion, and console access. Keep the previous image available for rollback, but do not roll back blindly if the data format or configuration has changed. Review image updates with an automated tool such as Renovate for Docker Compose, while retaining human review for storage services.
When to revisit
Return to this checklist before adding an application, changing its storage backend, or exposing MinIO through a new hostname. Revisit it during seasonal planning cycles, after a major MinIO or client release, and whenever workflows or retention requirements change. It is also worth scheduling a regular review of storage growth, unused identities, bucket policies, lifecycle rules, certificate renewal, backup freshness, and restore results.
Keep a short operational record containing the Compose file version, image tag, endpoint details, bucket inventory, identity owners, policy files, backup destination, and last successful restore test. After every material change, run a small end-to-end test: authenticate with a non-root identity, upload an object, retrieve it, verify its metadata, and remove the test object. That habit turns a one-time MinIO Docker deployment into a maintainable part of your self-hosted toolkit.