Instalasi dan Konfigurasi Sculpin di Lingkungan ServBay

Ringkasan

Sculpin adalah generator situs statis berbasis PHP yang kuat dan fleksibel, sangat cocok untuk membangun blog, situs dokumentasi, atau proyek yang membutuhkan konversi konten dinamis (seperti template Twig dan file Markdown) menjadi halaman HTML statis berperforma tinggi. Sculpin menggunakan Composer untuk manajemen dependensi dan dibangun dengan komponen Symfony, memberikan pengalaman pengembangan yang andal dan familiar.

ServBay adalah lingkungan pengembangan web lokal khusus untuk macOS, mengintegrasikan berbagai paket perangkat lunak yang umum dipakai seperti PHP, Composer, database (MySQL, PostgreSQL, MongoDB, Redis), serta web server (Caddy, Nginx); dan semua dapat dikelola secara mudah melalui antarmuka grafis. Dengan ServBay, proses membangun lingkungan pengembangan Sculpin di macOS jadi jauh lebih mudah, terutama dalam mengelola versi PHP, dependensi, dan konfigurasi web server.

Panduan ini akan membahas secara lengkap cara memasang dan mengonfigurasi Sculpin di lingkungan ServBay, serta menyiapkan sebuah situs website pengembangan lokal.

Skenario Penggunaan

• Membuat blog statis berkinerja tinggi menggunakan teknologi PHP.
• Membuat situs dokumentasi statis untuk proyek atau produk open source.
• Membuat landing page atau situs perusahaan statis tanpa backend database secara praktis.
• Menggunakan template engine Twig dan Markdown untuk menulis konten, sekaligus menikmati kecepatan dan keamanan situs statis.

Persyaratan

Sebelum memulai, pastikan Anda sudah memenuhi syarat berikut:

1. ServBay telah terpasang dan berjalan di macOS. ServBay sudah menyediakan lingkungan PHP, Composer, dan web server (Caddy atau Nginx) yang dibutuhkan.
2. Memiliki pemahaman dasar tentang penggunaan command line atau terminal.
3. Mengenal konsep dasar PHP, Composer, dan Markdown.

Langkah-Langkah Instalasi Sculpin

Berikut adalah cara rinci pemasangan dan konfigurasi Sculpin di lingkungan ServBay:

Langkah 1: Membuat Direktori Proyek

Pertama, buatlah direktori proyek baru di root direktori website ServBay (/Applications/ServBay/www). Kita akan menggunakan contoh nama proyek servbay-sculpin-app.

Buka Terminal dan jalankan perintah berikut:

cd /Applications/ServBay/www
mkdir servbay-sculpin-app
cd servbay-sculpin-app

Direktori ini akan menjadi tempat seluruh file proyek Sculpin Anda.

Langkah 2: Membuat Proyek Sculpin dengan Composer

ServBay sudah dilengkapi Composer, sehingga Anda tidak perlu menginstal Composer secara terpisah. Anda dapat langsung menggunakan perintah composer di Terminal.

Untuk memulai dengan cepat, kita gunakan skeleton blog resmi dari Sculpin. Di dalam folder servbay-sculpin-app yang baru saja dibuat, jalankan perintah berikut:

composer create-project sculpin/sculpin-blog-skeleton .

Perintah ini akan mengunduh skeleton blog Sculpin dan semua dependensinya, lalu menginstalnya ke direktori saat ini (.).

Langkah 3: Konfigurasi Website di ServBay

Agar bisa diakses melalui web server ServBay (Caddy atau Nginx), Anda perlu menambahkan konfigurasi website baru di ServBay.

1. Buka aplikasi ServBay: Jalankan aplikasi ServBay.
2. Buka Tab "Situs": Klik tab "Situs" di bilah navigasi jendela ServBay.
3. Tambah Website Baru: Klik tombol "+" di pojok kiri bawah untuk menambahkan konfigurasi situs baru.
4. Isi Informasi Website:

   • Nama (Name): Masukkan nama yang mudah dikenali, misalnya My Sculpin Site.

   • Domain: Masukkan domain lokal yang akan digunakan, misalnya servbay-sculpin.local. ServBay otomatis mengatur resolusi domain .local dengan sertifikat SSL (menggunakan ServBay User CA).

   • Tipe Situs (Type): Pilih PHP, karena Sculpin adalah aplikasi PHP.

   • Versi PHP (PHP Version): Pilih versi PHP yang diinginkan. ServBay mendukung multi versi PHP—pilih versi yang kompatibel dengan Sculpin (biasanya versi terbaru).

   • Root Direktori Website (Document Root): Ini langkah penting. File statis hasil generate Sculpin secara default ada di output_dev atau output_prod pada direktori proyek. Untuk pengembangan lokal, arahkan root website ke output development:

     /Applications/ServBay/www/servbay-sculpin-app/output_dev

5. Simpan Konfigurasi: Setelah seluruh file diisi, klik tombol "Simpan". ServBay akan otomatis menerapkan pengaturan ini ke web server (Caddy atau Nginx). Biasanya, tidak perlu me-restart ServBay secara manual.

Langkah 4: Generate Website Sculpin

Setelah konfigurasi website di ServBay selesai, sekarang waktunya membangun file statis website Anda dengan Sculpin.

Di Terminal, pastikan Anda masih berada di direktori proyek /Applications/ServBay/www/servbay-sculpin-app, lalu jalankan perintah berikut untuk memastikan semua dependensi terpasang (kalau sudah menjalankan langkah 2, biasanya cukup aman, tapi jalankan untuk memastikan):

composer install

Selanjutnya, jalankan perintah generate Sculpin untuk membangun website:

vendor/bin/sculpin generate --watch

• vendor/bin/sculpin: Path ke file executable Sculpin yang di-install Composer.
• generate: Perintah utama Sculpin untuk membangun situs statis. Ia akan membaca isi direktori source dan template, lalu menghasilkan file statis di direktori output (default-nya output_dev).
• --watch: Flag ini membuat Sculpin memonitor perubahan file di folder source. Bila ada perubahan, Sculpin otomatis generate ulang website—sangat berguna untuk pengembangan.

Ketika perintah selesai dan muncul pesan seperti "Sculpin has generated your site!" di Terminal, file statis sudah tersedia di folder output_dev.

Langkah 5: Mengakses Website Pengembangan Lokal

Kini Anda sudah dapat mengakses situs Sculpin menggunakan domain yang telah Anda setel di ServBay.

Buka browser dan kunjungi domain yang dikonfigurasi pada langkah 3:

https://servbay-sculpin.local

Karena root direktori sudah diarahkan ke output_dev dan perintah sculpin generate --watch masih berjalan untuk memantau perubahan file, Anda dapat melihat preview update situs secara real time melalui https://servbay-sculpin.local. Sertifikat SSL otomatis dari ServBay memastikan Anda dapat mengakses secara aman dengan HTTPS.

Pengembangan dengan Sculpin

Sekarang Anda sudah berhasil memasang dan mengonfigurasi Sculpin di ServBay, dan siap membangun situs statis Anda. Berikut beberapa hal dasar yang bisa dilakukan:

Struktur Proyek Sculpin

Mengetahui struktur dasar proyek Sculpin akan sangat membantu pengembangan:

servbay-sculpin-app/
├── app/                # Konfigurasi aplikasi & cache
├── output_dev/         # Hasil file statis untuk lingkungan development (Root website ServBay diarahkan ke sini)
├── output_prod/        # Hasil file statis untuk produksi
├── source/             # Sumber konten website (Markdown, template Twig, static asset, dsb.)
│   ├── _layouts/       # File layout Twig
│   ├── _posts/         # Artikel blog (Markdown)
│   ├── assets/         # Aset statis (CSS, JS, gambar, dsb.)
│   └── index.md        # File Markdown halaman depan
├── vendor/             # Library dependensi yang di-install Composer
├── sculpin.yml         # Konfigurasi utama Sculpin
├── composer.json       # Konfigurasi dependensi Composer
└── ...file lain

Sebagian besar pekerjaan Anda ada di dalam folder source.

Membuat Artikel Blog

Untuk menulis artikel baru di blog Sculpin, cukup buat file Markdown baru di folder source/_posts. Biasanya penamaan file mengikuti format YYYY-MM-DD-slug.md.

Contoh, buat file 2024-06-06-my-first-post.md:

---
title: "Artikel Pertama Saya"
date: 2024-06-06
tags: [Tutorial, Sculpin, ServBay]
---

# Artikel Pertama Saya

Ini adalah konten untuk artikel pertama saya di blog Sculpin. Di sini saya berbagi pengalaman mengenai penggunaan ServBay dan Sculpin.

Anda dapat menulis konten menggunakan sintaks Markdown di sini.

## Subjudul

Daftar:
- Item 1
- Item 2

Setelah Anda simpan file-nya, perintah sculpin generate --watch akan mendeteksi perubahan, membangun ulang website, dan Anda bisa refresh browser di https://servbay-sculpin.local untuk melihat artikel baru.

Membuat Halaman Baru

Untuk menambah halaman khusus (misalnya halaman "Tentang Kami"), cukup buat file Markdown di folder source, misalnya about.md:

---
title: "Tentang Kami"
layout: page.html.twig # Tentukan file layout yang dipakai
---

# Panduan ServBay Sculpin

Halaman ini berisi panduan membangun situs statis menggunakan ServBay dan Sculpin.

Setelah disimpan, Sculpin akan menghasilkan file output_dev/about/index.html (bila pretty URL diaktifkan). Akses dengan https://servbay-sculpin.local/about/.

Kustomisasi Gaya dan Script

Aset statis seperti CSS dan file JavaScript ada di folder source/assets. Anda bisa langsung edit file tersebut.

Sebagai contoh, edit file source/assets/css/style.css untuk mengubah gaya website.

Semua aset ini akan otomatis disalin ke folder output ketika proses generate. Bila Anda mengubah file di folder ini, Sculpin dengan mode --watch juga akan langsung membangun ulang website.

Build Website untuk Produksi

Jika Anda sudah selesai membangun website dan ingin upload versi produksi, biasanya dilakukan optimasi dan minifikasi resource.

Jalankan perintah berikut untuk build versi production:

vendor/bin/sculpin generate --env=prod

File hasil build akan disimpan di output_prod. Anda bisa upload seluruh isi folder output_prod ke layanan hosting website statis apa saja seperti GitHub Pages, Netlify, Vercel, maupun server web Anda sendiri.

Jika Anda ingin mengecek hasil build production di ServBay, tinggal arahkan root direktori website ke /Applications/ServBay/www/servbay-sculpin-app/output_prod, simpan konfigurasi, lalu akses domain yang sama.

Catatan Penting

• Pastikan ServBay sudah berjalan, dan website yang Anda konfigurasi sudah aktif.
• Jalankan sculpin generate --watch di terminal untuk update otomatis selama pengembangan.
• Pastikan root direktori di konfigurasi ServBay sesuai dengan output Sculpin (default development adalah output_dev).
• ServBay menyediakan sertifikat SSL otomatis untuk domain .local, namun terkadang OS Anda perlu meng-trust ServBay User CA. Silakan cek dokumentasi ServBay untuk langkah detailnya.

Tanya Jawab (FAQ)

T: Saya sudah mengubah file, tapi website tidak update?

J: Pastikan Anda menjalankan vendor/bin/sculpin generate --watch di direktori proyek dan perintah tersebut tidak berhenti karena error. Cek output terminal untuk pesan error. Bersihkan cache browser atau akses via mode privat.

T: Muncul error SSL saat mengakses https://servbay-sculpin.local?

J: Biasanya karena Sertifikat untuk domain .local yang di-generate ServBay adalah self-signed. Anda perlu meng-trust ServBay User CA pada sistem operasi Anda. Ikuti petunjuk di dokumentasi ServBay.

T: Bagaimana cara mengganti versi PHP?

J: Di tab "Paket" pada aplikasi ServBay, Anda bisa menginstal dan mengatur berbagai versi PHP. Lalu di tab "Situs", edit konfigurasi situs Sculpin Anda, pilih versi PHP yang diinginkan, dan simpan.

T: Apa saja template engine dan markup language yang didukung Sculpin?

J: Secara default Sculpin memakai Twig untuk template engine, dan sangat mendukung Markdown untuk penulisan konten.

Penutup

Dengan lingkungan terintegrasi dari ServBay, memasang dan mengonfigurasi generator situs statis Sculpin di macOS menjadi jauh lebih praktis. ServBay menyediakan PHP dan Composer siap pakai, serta web server mudah konfigurasi dengan fitur SSL otomatis; memberikan fondasi yang kokoh untuk pengembangan lokal dengan Sculpin. Dengan mengikuti panduan ini, Anda dapat menyiapkan lingkungan pengembangan Sculpin dengan cepat, lalu membangun dan me-review website statis Anda dengan efisiensi maksimal. Optimalkan kekuatan Sculpin dan kemudahan ServBay—fokus pada pembuatan konten berkualitas, tanpa harus repot mengatur lingkungan pengembangan yang kompleks.