Deploy on Vexlo Cloud in 60s (₹149/mo UPI) — India's First & Only Developer PaaS. Instant INR UPI & 17 global currencies ($5/mo).
Deploy Now
Bucket 3: Self-Hosted Open-Source Docker Templates6 min readVerified

Deploying Self-Hosted MinIO S3 Storage Behind Traefik on Ports 9000 and 9001

Complete docker-compose.yml for deploying MinIO behind Traefik v3 TLS. Configure dual Traefik routers and services for S3 API (port 9000) and MinIO Console UI (port 9001) without InvalidArgument S3 port errors.

TL;DR — Immediate Production Fix

MinIO exposes two separate servers inside a single container: the S3-compatible Object Storage API on port `9000` (e.g., `s3.vexlo.cloud`) and the Web Administration Console on port `9001` (e.g., `minio.vexlo.cloud`). When deploying MinIO behind Traefik in Docker Compose, defining only a single Traefik router causes either `Error: S3 API Requests must be made to API port` or a 502 Bad Gateway. You must explicitly bind two distinct Traefik routers (`minio-s3` and `minio-console`) to two distinct Traefik services (`port=9000` and `port=9001`) AND pass `MINIO_SERVER_URL` and `MINIO_BROWSER_REDIRECT_URL` so presigned S3 upload URLs and Console OAuth/WebSocket sessions work over HTTPS.

Verified Root Causes in Production Environments

  • Single-Service Port Collision in Traefik Labels: Because the MinIO container exposes two ports, Traefik requires two named services (`traefik.http.routers.s3.service=s3-svc` -> `9000` and `traefik.http.routers.console.service=console-svc` -> `9001`).
  • S3 API Requests Routed to Console Port 9001 (`S3 API Requests must be made to API port`): Pointing the AWS SDK `endpoint` at the Console subdomain (`9001`) instead of the S3 API subdomain (`9000`) triggers an XML `InvalidArgument` rejection.
  • Missing MINIO_SERVER_URL Breaking Presigned Upload Signatures: Without `MINIO_SERVER_URL=https://s3.vexlo.cloud`, the MinIO Console generates presigned URLs using the internal container hostname (`http://minio:9000`), which fails AWS Signature V4 host validation in the browser.

1. Production MinIO docker-compose.yml With Dual Traefik v3 Routers & Services

To route two different subdomains (`s3.vexlo.cloud` and `console.s3.vexlo.cloud`) to two different ports (`9000` and `9001`) on the exact same Docker container, every Traefik router label must include an explicit `.service=<service_name>` mapping.

In addition, always pass `--console-address ":9001"` in the `command:` directive; without it, MinIO dynamically chooses a random ephemeral port for the web console on every restart, immediately breaking your reverse proxy.

docker-compose.yml
yaml
services:
  minio:
    image: quay.io/minio/minio:latest
    container_name: vexlo-minio
    restart: unless-stopped
    command: server /data --address ":9000" --console-address ":9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER:-vexlo_admin}
      # Password must be at least 8 characters
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
      # Critical for AWS SigV4 presigned URLs and Console login redirects
      MINIO_SERVER_URL: https://s3.vexlo.cloud
      MINIO_BROWSER_REDIRECT_URL: https://minio.vexlo.cloud
    volumes:
      - minio_data:/data
    networks:
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.docker.network=proxy"

      # Router 1: S3 API Endpoint (s3.vexlo.cloud -> internal port 9000)
      - "traefik.http.routers.minio-s3.rule=Host(`s3.vexlo.cloud`)"
      - "traefik.http.routers.minio-s3.entrypoints=websecure"
      - "traefik.http.routers.minio-s3.tls.certresolver=letsencrypt"
      - "traefik.http.routers.minio-s3.service=minio-s3-svc"
      - "traefik.http.services.minio-s3-svc.loadbalancer.server.port=9000"

      # Router 2: Web Admin Console (minio.vexlo.cloud -> internal port 9001)
      - "traefik.http.routers.minio-console.rule=Host(`minio.vexlo.cloud`)"
      - "traefik.http.routers.minio-console.entrypoints=websecure"
      - "traefik.http.routers.minio-console.tls.certresolver=letsencrypt"
      - "traefik.http.routers.minio-console.service=minio-console-svc"
      - "traefik.http.services.minio-console-svc.loadbalancer.server.port=9001"
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 15s
      timeout: 5s
      retries: 3

volumes:
  minio_data:

networks:
  proxy:
    external: true

2. Connecting @aws-sdk/client-s3 in Node.js With forcePathStyle: true

By default, the official AWS SDK v3 for JavaScript (`@aws-sdk/client-s3`) constructs virtual-hosted style bucket URLs (`https://<bucket>.s3.vexlo.cloud`). Unless you have configured wildcard DNS (`*.s3.vexlo.cloud`) and `MINIO_DOMAIN=s3.vexlo.cloud`, virtual-hosted requests will fail TLS certificate validation.

When connecting to a self-hosted MinIO instance from Next.js or Node.js, set `forcePathStyle: true` so the SDK addresses buckets at `https://s3.vexlo.cloud/<bucket>/<key>`.

minio-s3-client.ts
typescript
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';

export const minioClient = new S3Client({
  region: 'ap-south-1', // Any valid string region works with MinIO
  endpoint: 'https://s3.vexlo.cloud', // MUST point to port 9000 router, NEVER port 9001!
  forcePathStyle: true, // Required unless wildcard DNS (*.s3.vexlo.cloud) is configured
  credentials: {
    accessKeyId: process.env.MINIO_ACCESS_KEY!,
    secretAccessKey: process.env.MINIO_SECRET_KEY!,
  },
});

export async function createPresignedUploadUrl(bucket: string, key: string, contentType: string) {
  const command = new PutObjectCommand({
    Bucket: bucket,
    Key: key,
    ContentType: contentType,
  });
  return getSignedUrl(minioClient, command, { expiresIn: 900 });
}

3. Automating Bucket Creation & Public Read Policies With MinIO Client (mc)

You can automate initial bucket creation and CORS/public-download policies directly in Docker Compose using an ephemeral `minio/mc` initialization container that runs once after `minio` reports healthy.

init-minio-buckets.sh
bash
# Connect MinIO Client (mc) inside the running container and create an 'assets' bucket
docker exec -it vexlo-minio sh -c "
  mc alias set local http://127.0.0.1:9000 \$MINIO_ROOT_USER \$MINIO_ROOT_PASSWORD && \
  mc mb --ignore-existing local/public-assets && \
  mc anonymous set download local/public-assets
"

Pre-Deployment Verification Checklist

  • Pass `--address ":9000" --console-address ":9001"` in the MinIO `command:` block.
  • Explicitly link `routers.minio-s3.service=minio-s3-svc` (`9000`) and `routers.minio-console.service=minio-console-svc` (`9001`) in Traefik labels.
  • Set `MINIO_SERVER_URL=https://s3.yourdomain.com` so the Console can upload files without SignatureDoesNotMatch errors.
  • Set `forcePathStyle: true` in `@aws-sdk/client-s3`.
India's First & Only Developer PaaS

Deploy on Vexlo Cloud in 60s (₹149/mo UPI)

Automated Docker & Nixpacks builds, managed PostgreSQL/Redis, and AI Deployment Doctor. Instant INR UPI for India or USD/EUR/GBP across 17 global currencies.

Frequently Asked Questions

Why does MinIO return 'InvalidArgument: S3 API Requests must be made to API port'?

Your S3 client or Traefik router is sending S3 API requests to port `9001` (the Web Console port) instead of port `9000` (the S3 API port). Point your S3 SDK `endpoint` to the subdomain routed to port `9000`.

Why do file uploads inside the MinIO Web Console fail or spin forever behind Traefik?

When you upload a file in the MinIO Web Console (`minio.yourdomain.com`), the browser makes a direct XHR/WebSocket request to the S3 API URL. If `MINIO_SERVER_URL` is not set to your public HTTPS S3 domain (`https://s3.yourdomain.com`), the Console tries to upload to `http://127.0.0.1:9000` or internal container IP, which fails in your browser.

Can I host both the MinIO S3 API and Console on the same domain using URL subpaths?

MinIO strongly recommends using two distinct subdomains (`s3.example.com` and `minio.example.com`) rather than subpath prefix stripping, because AWS Signature V4 calculates cryptographic signatures over the exact canonical URI path.

Primary Upstream References & Specifications

Keep Debugging

Related Guides

Browse all 30 guides →