Root & Alias #

root dan alias keduanya digunakan untuk menentukan dari mana Nginx membaca file, tapi cara mereka membentuk path file sangat berbeda. Ini adalah salah satu sumber kebingungan yang paling umum bagi pengguna Nginx baru — bahkan pengguna yang sudah cukup berpengalaman pun kadang salah di sini.

root: URI Ditambahkan ke Path #

Dengan root, Nginx membentuk path file dengan menggabungkan nilai root dan URI request secara langsung:

Path = root + URI

Contoh:
  root /var/www/html;
  Request: GET /images/photo.jpg
  Path: /var/www/html + /images/photo.jpg = /var/www/html/images/photo.jpg

server {
    root /var/www/html;

    location /images/ {
        # Request: GET /images/photo.jpg
        # File: /var/www/html/images/photo.jpg  ← /images/ ikut digabungkan
    }
}

Perhatikan bahwa /images/ dari URI ikut masuk ke path. Ini wajar dan sering diinginkan — tapi masalah muncul ketika lokasi file di disk tidak mencerminkan struktur URL.

alias: URI Diganti dengan Path Baru #

Dengan alias, Nginx menggantikan bagian location dengan nilai alias, bukan menambahkannya:

Path = alias + (URI setelah bagian yang cocok dengan location)

Contoh:
  location /images/ {
      alias /data/media/;
  }
  Request: GET /images/photo.jpg
  Path: /data/media/ + photo.jpg = /data/media/photo.jpg

server {
    location /images/ {
        alias /data/media/;
        # Request: GET /images/photo.jpg
        # File: /data/media/photo.jpg  ← /images/ DIGANTI dengan /data/media/
    }
}

Di sini /images/ dari URI tidak ikut ke path. Nginx mengambil bagian setelah /images/ (yaitu photo.jpg) dan menggabungkannya dengan nilai alias.

Perbandingan Langsung #

# Dengan root:
location /static/ {
    root /var/www;
}
# GET /static/app.css → /var/www/static/app.css
# (perhatikan: /static/ ikut di path)

# Dengan alias:
location /static/ {
    alias /var/www/assets/;
}
# GET /static/app.css → /var/www/assets/app.css
# (perhatikan: /static/ diganti dengan /var/www/assets/)

Perbedaannya jelas ketika nama di URL tidak sama dengan nama direktori di disk. root membutuhkan struktur direktori yang mencerminkan URL; alias membolehkan pemetaan yang berbeda.

Kapan Menggunakan root vs alias #

Gunakan root ketika struktur direktori di disk mencerminkan struktur URL:

server {
    root /var/www/mysite;
    # /var/www/mysite/
    # ├── index.html        → GET /
    # ├── about.html        → GET /about.html
    # ├── images/           → GET /images/
    # └── css/              → GET /css/

    location / {
        try_files $uri $uri/ =404;
    }
}

Gunakan alias ketika file ada di lokasi yang berbeda dari apa yang diimplkasikan URL, atau ketika kamu memetakan path URL ke direktori yang sama sekali berbeda:

server {
    root /var/www/myapp;

    # File upload disimpan di /mnt/storage/uploads/,
    # tapi diakses via /files/
    location /files/ {
        alias /mnt/storage/uploads/;
        # GET /files/report.pdf → /mnt/storage/uploads/report.pdf
    }

    # Dokumentasi di direktori terpisah
    location / {
        alias /opt/documentation/html/;
        # GET /guide.html → /opt/documentation/html/guide.html
    }
}

Kesalahan Umum dengan alias #

Trailing slash yang tidak konsisten #

# ANTI-PATTERN: trailing slash tidak konsisten
location /images {        # ← tidak ada trailing slash di location
    alias /data/media/;   # ← ada trailing slash di alias
}
# GET /images/photo.jpg → /data/media//photo.jpg (double slash, bermasalah)

# BENAR: keduanya konsisten
location /images/ {       # ← ada trailing slash
    alias /data/media/;   # ← ada trailing slash
}
# atau
location /images {
    alias /data/media;
}

Aturan praktisnya: pastikan trailing slash di location dan alias konsisten — keduanya ada atau keduanya tidak ada.

root di dalam location dengan nama berbeda #

# ANTI-PATTERN yang sering terjadi:
location /static/ {
    root /var/www/assets;
    # GET /static/app.css → /var/www/assets/static/app.css
    # File tidak ada! Yang ada mungkin /var/www/assets/app.css
}

# BENAR: gunakan alias karena nama direktori berbeda dari URL
location /static/ {
    alias /var/www/assets/;
    # GET /static/app.css → /var/www/assets/app.css ✓
}

# ATAU gunakan root dengan struktur direktori yang sesuai:
# /var/www/assets/static/app.css  → root /var/www/assets;

alias dengan try_files #

Saat menggunakan alias dengan try_files, ada sintaks khusus yang perlu diperhatikan:

location /files/ {
    alias /data/uploads/;

    # try_files dengan alias: gunakan $uri bukan hanya nama file
    try_files $uri =404;

    # Atau jika butuh fallback ke index:
    # try_files $uri $uri/ =404;
}

Ringkasan #

root: path file = nilai root + URI penuh. Gunakan ketika struktur direktori mencerminkan struktur URL.
alias: path file = nilai alias + URI setelah bagian yang cocok dengan location. Gunakan ketika nama direktori berbeda dari URL.
Trailing slash harus konsisten antara location dan alias — keduanya ada atau keduanya tidak ada.
Jika location /static/ tapi file ada di /var/www/assets/ (bukan /var/www/assets/static/), gunakan alias, bukan root.
root bisa diletakkan di server block (diwarisi semua location); alias hanya valid di dalam location block.

← Sebelumnya: Virtual Host Berikutnya: Index & Autoindex →