---
title: "Deploy S3-Compatible Bucket di Helipod dan Akses dari Local"
url: "https://helipod.io/blog/helipod-s3-bucket-tutorial"
date: "2026-05-06"
updated: "2026-05-06"
author: "Tim Helipod"
tags: ["bucket", "s3", "minio", "storage", "tutorial"]
excerpt: "Cara deploy S3-compatible bucket (MinIO) di Helipod, lalu akses dan upload file dari terminal lokal kamu dengan AWS CLI dan path-style addressing."
---

# Deploy S3-Compatible Bucket di Helipod dan Akses dari Local

Butuh object storage yang kompatibel dengan S3 API tanpa perlu setup server sendiri? Helipod menyediakan **Bucket service** berbasis MinIO, S3-compatible, siap pakai dalam hitungan menit, dan bisa langsung diakses dari aplikasi maupun terminal lokal kamu.

Di artikel ini kita akan deploy bucket, konfigurasi variabel, generate domain publik, lalu langsung coba upload file dari terminal menggunakan AWS CLI. Termasuk penjelasan tentang **path-style vs virtual-hosted-style** dan opsi konfigurasi MinIO lainnya.

## Yang Kamu Butuhkan

Sebelum mulai, pastikan kamu sudah punya:

- Akun Helipod (daftar gratis di [helipod.io](https://helipod.io))
- AWS CLI terinstall di lokal ([panduan install](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html))
- Project yang sudah dibuat di Helipod

## Langkah 1: Tambah Service Bucket

Buka project kamu di dashboard Helipod, lalu klik **+ Add Service** di pojok kanan atas canvas.

Di dialog **New deployment** yang muncul, pilih **Bucket**: deskripsinya: *S3-compatible bucket for managing files, media, and assets*.

Helipod akan otomatis membuat service MinIO dan menambahkannya ke canvas project kamu.

## Langkah 2: Konfigurasi Environment Variables

Setelah service bucket terbuat, klik service tersebut di canvas lalu buka tab **Variables**.

### Variabel Wajib

Tiga variabel ini harus selalu diset:

```env
MINIO_ROOT_USER=nama-user-kamu
MINIO_ROOT_PASSWORD=password-yang-kuat
MINIO_API_CORS_ALLOW_ORIGIN=*
```

> **Tips keamanan:** Gunakan password yang kuat untuk `MINIO_ROOT_PASSWORD`: minimal 8 karakter. Nilai ini akan menjadi **Secret Access Key** kamu saat mengakses bucket via AWS CLI. Variabel di Helipod dienkripsi at rest dan tidak pernah muncul di build logs.

### Variabel Opsional dan Konfigurasi Lanjutan

MinIO mendukung banyak variabel environment untuk menyesuaikan perilakunya. Berikut opsi-opsi yang paling sering dibutuhkan:

#### Addressing Style: Path-Style vs Virtual-Hosted-Style

Ini adalah pengaturan yang paling penting untuk kompatibilitas dengan berbagai SDK dan tool.

**Virtual-hosted-style** (default AWS): bucket name menjadi subdomain.
```
https://my-bucket.nama-bucket.helipod.app/object.jpg
```

**Path-style**: bucket name menjadi bagian dari path URL.
```
https://nama-bucket.helipod.app/my-bucket/object.jpg
```

Karena Helipod menggunakan satu magic domain (bukan wildcard subdomain), **path-style adalah pilihan yang lebih praktis**: tidak memerlukan konfigurasi DNS tambahan per bucket.

Untuk mengaktifkan path-style di MinIO, set variabel berikut:

```env
MINIO_API_SELECT_PARQUET=off
MINIO_DOMAIN=nama-bucket.helipod.app
```

Lalu saat menggunakan AWS CLI dari lokal, tambahkan flag `--no-sign-request` untuk bucket publik, atau gunakan config `s3.addressing_style`:

```bash
# Cara 1: flag per-command
aws s3 ls s3://my-bucket \
  --endpoint-url https://nama-bucket.helipod.app \
  --profile minio

# Cara 2: set addressing style di config AWS CLI (direkomendasikan)
aws configure set s3.addressing_style path --profile minio
```

Dengan `addressing_style = path`, AWS CLI akan selalu menggunakan path-style tanpa perlu flag tambahan.

Atau edit langsung file `~/.aws/config`:

```ini
[profile minio]
region = us-east-1
output = json

[profile minio.s3]
addressing_style = path
```

#### Konfigurasi Storage & Performa

```env
# Batas ukuran upload multipart (default: 16MB per part)
MINIO_API_REPLICATION_WORKERS=10

# Set timezone untuk timestamp logs
TZ=Asia/Jakarta

# Aktifkan compression untuk objek yang disimpan (hemat storage)
MINIO_COMPRESS_ENABLE=on
MINIO_COMPRESS_EXTENSIONS=.txt,.log,.csv,.json,.xml
MINIO_COMPRESS_MIME_TYPES=text/plain,application/json,text/csv
```

#### Konfigurasi CORS Spesifik

Untuk production, hindari `*` dan gunakan domain spesifik:

```env
# Izinkan dari satu domain
MINIO_API_CORS_ALLOW_ORIGIN=https://app.kamu.com

# Izinkan dari beberapa domain (pisahkan dengan koma)
MINIO_API_CORS_ALLOW_ORIGIN=https://app.kamu.com,https://staging.kamu.com
```

#### Site & Region

```env
# Set nama region (opsional, untuk kompatibilitas dengan SDK tertentu)
MINIO_SITE_REGION=ap-southeast-3
MINIO_SITE_NAME=helipod-bucket
```

### Ringkasan Semua Variabel

| Variabel | Default | Keterangan |
|----------|---------|------------|
| `MINIO_ROOT_USER` | - | **Wajib.** Username / Access Key ID |
| `MINIO_ROOT_PASSWORD` | - | **Wajib.** Password / Secret Access Key (min 8 karakter) |
| `MINIO_API_CORS_ALLOW_ORIGIN` | - | **Wajib.** `*` untuk semua origin |
| `MINIO_DOMAIN` | - | Set jika ingin virtual-hosted-style dengan domain sendiri |
| `MINIO_BROWSER` | `on` | Set `off` untuk nonaktifkan Console UI |
| `MINIO_SITE_REGION` | `us-east-1` | Region identifier |
| `MINIO_COMPRESS_ENABLE` | `off` | Aktifkan kompresi objek |
| `TZ` | UTC | Timezone untuk logs |

Klik **+ New variable** untuk menambahkan variabel yang kamu butuhkan, lalu klik **Deploy** untuk menerapkan perubahan.

## Langkah 3: Generate Magic Domain dan Point ke Port 9000

MinIO berjalan di port **9000** untuk S3 API. Kamu perlu memastikan domain publik sudah diarahkan ke port ini.

Buka tab **Settings** pada service bucket, lalu scroll ke bagian **Networking & Domains**.

Kamu akan melihat dua entry:

- **Internal DNS**: hostname privat untuk komunikasi antar pod di dalam cluster, tidak perlu diubah
- **Magic domain**: domain publik yang otomatis digenerate Helipod, format: `nama-bucket.helipod.app`

Pastikan routing magic domain sudah menunjuk ke port `:9000`:

```
Internet :443 → Traefik → :9000 your app
```

Magic domain inilah yang akan kita gunakan sebagai S3 endpoint dari terminal lokal.

## Langkah 4: Akses dari Terminal Lokal via AWS CLI

Bucket kamu sudah live dan bisa diakses dari luar. Saatnya connect dari terminal lokal.

### Setup Credentials dan Config

Buat profile khusus untuk MinIO agar tidak bentrok dengan konfigurasi AWS lain:

```bash
aws configure --profile minio
```

Isi saat diminta:

- **AWS Access Key ID:** nilai `MINIO_ROOT_USER` kamu
- **AWS Secret Access Key:** nilai `MINIO_ROOT_PASSWORD` kamu
- **Default region name:** `us-east-1`
- **Default output format:** `json`

Lalu set path-style addressing agar tidak perlu flag tambahan setiap perintah:

```bash
aws configure set s3.addressing_style path --profile minio
```

### Test Koneksi

```bash
aws s3 ls \
  --endpoint-url https://nama-bucket.helipod.app \
  --profile minio
```

### Operasi Dasar

```bash
# Buat bucket
aws s3 mb s3://my-first-bucket \
  --endpoint-url https://nama-bucket.helipod.app \
  --profile minio

# Upload file
aws s3 cp ./foto.jpg s3://my-first-bucket/ \
  --endpoint-url https://nama-bucket.helipod.app \
  --profile minio

# Upload seluruh folder
aws s3 sync ./assets s3://my-first-bucket/assets \
  --endpoint-url https://nama-bucket.helipod.app \
  --profile minio

# Download file
aws s3 cp s3://my-first-bucket/foto.jpg ./foto-download.jpg \
  --endpoint-url https://nama-bucket.helipod.app \
  --profile minio

# List isi bucket
aws s3 ls s3://my-first-bucket \
  --endpoint-url https://nama-bucket.helipod.app \
  --profile minio

# Hapus file
aws s3 rm s3://my-first-bucket/foto.jpg \
  --endpoint-url https://nama-bucket.helipod.app \
  --profile minio
```

### Buat Alias agar Lebih Ringkas

Tambahkan ke `~/.zshrc` atau `~/.bashrc`:

```bash
alias s3pod='aws s3 --endpoint-url https://nama-bucket.helipod.app --profile minio'
```

Setelah `source ~/.zshrc`:

```bash
s3pod ls
s3pod mb s3://my-bucket
s3pod cp ./file.txt s3://my-bucket/
s3pod sync ./folder s3://my-bucket/folder
```

## Integrasi dengan Aplikasi di Helipod

Jika kamu punya service lain (misalnya Laravel, Node.js, atau Python) di project yang sama, gunakan **internal DNS**: lebih cepat dan tidak keluar ke internet publik.

Format internal hostname bisa ditemukan di tab **Settings → Networking & Domains** dengan label "Internal only".

```env
# Internal network (untuk service di project yang sama: direkomendasikan)
S3_ENDPOINT=http://heli-xxxxxxxx.env-xxxx.svc.cluster.local
S3_ACCESS_KEY=nama-user-kamu
S3_SECRET_KEY=password-kamu
S3_REGION=us-east-1
S3_BUCKET=my-first-bucket
S3_PATH_STYLE=true

# Public endpoint (untuk akses dari luar Helipod)
S3_ENDPOINT=https://nama-bucket.helipod.app
```

> **Penting:** Saat menggunakan internal DNS, selalu set `S3_PATH_STYLE=true` (atau ekuivalennya di SDK kamu) karena internal hostname bukan wildcard subdomain. Ini berlaku untuk Laravel Flysystem, boto3, aws-sdk-js, dan lainnya.

Baca lebih lanjut di [Panduan Internal Network Helipod](https://helipod.io/blog/internal-network-pod-to-pod-helipod).

## Troubleshooting Umum

**Error "Token has expired and refresh failed"**
AWS CLI kamu memiliki SSO session lama yang aktif. Gunakan `--profile minio` agar CLI memakai credentials yang benar:

```bash
aws s3 ls --endpoint-url https://nama-bucket.helipod.app --profile minio
```

Atau lewati credentials langsung via environment variable:

```bash
AWS_ACCESS_KEY_ID=user AWS_SECRET_ACCESS_KEY=password \
  aws s3 ls --endpoint-url https://nama-bucket.helipod.app
```

**Error "PermanentRedirect" atau bucket tidak ditemukan**
Ini biasanya masalah addressing style. Pastikan path-style sudah aktif:

```bash
aws configure set s3.addressing_style path --profile minio
```

**Error "Connection refused" atau timeout**
Pastikan routing di Settings sudah mengarah ke port `:9000`. MinIO S3 API berjalan di port 9000, bukan 80 atau 443.

**Error "Access Denied"**
Periksa nilai `MINIO_ROOT_USER` dan `MINIO_ROOT_PASSWORD` di tab Variables, pastikan sama persis dengan yang dimasukkan saat `aws configure`.

**CORS error saat akses dari browser**
Pastikan `MINIO_API_CORS_ALLOW_ORIGIN` sudah diset dan service sudah di-redeploy setelah variabel ditambahkan. Perubahan variabel baru berlaku setelah deployment ulang.

**SDK melaporkan "invalid region"**
Set `MINIO_SITE_REGION` di Variables sesuai nilai yang kamu pakai di SDK (misalnya `ap-southeast-3`), lalu redeploy.

## Kesimpulan

Deploy S3-compatible bucket di Helipod hanya butuh beberapa menit. Kunci yang sering diabaikan adalah **path-style addressing**: karena Helipod menggunakan satu domain per service (bukan wildcard subdomain), mengaktifkan path-style via `aws configure set s3.addressing_style path` atau flag setara di SDK kamu akan mencegah sebagian besar error kompatibilitas.

Dari sana, semua tool yang kompatibel dengan S3 API bisa langsung digunakan: AWS CLI, Laravel Flysystem, boto3, aws-sdk untuk Node.js, dan lainnya.

Punya pertanyaan? Hubungi kami di [support@helipod.io](mailto:support@helipod.io) atau bergabung ke komunitas di [hangar.helipod.io](https://hangar.helipod.io).