Skip to main content

Instalasi Docusaurus

Persiapan​

Sebelum menginstall Docusaurus, pastikan sistem kalian sudah diperbarui dengan menjalankan perintah berikut:

sudo apt update && sudo apt upgrade -y

Kemudian, pastikan kalian sudah menginstal Node.js dan npm. Jika belum, kalian bisa menginstalnya dengan:

sudo apt install nodejs npm -y

Pastikan versi Node.js yang terpasang minimal versi 16 dengan perintah:

node -v

Instalasi Docusaurus​

Setelah memastikan Node.js dan npm sudah terpasang, buat proyek baru menggunakan perintah berikut:

npx create-docusaurus@latest websiteku classic

Jika ingin menggunakan JavaScript atau TypeScript secara spesifik, gunakan:

npx create-docusaurus@latest websiteku classic --javascript

atau

npx create-docusaurus@latest websiteku classic --typescript

Konfirmasi Instalasi​

Saat menjalankan perintah di atas, akan muncul output seperti berikut:

Need to install the following packages:
  [email protected]
Ok to proceed? (y)

Tekan y untuk melanjutkan instalasi.

Setelah itu, akan ada pilihan bahasa pemrograman:

? Which language do you want to use? › - Use arrow-keys. Return to submit.
❯   JavaScript
    TypeScript

Jika sebelumnya tidak memilih --typescript atau --javascript, kalian bisa memilih di tahap ini. Gunakan tombol panah atas/bawah untuk memilih, lalu tekan Enter.

Menjalankan Docusaurus​

Setelah instalasi selesai, kalian akan melihat pesan seperti berikut:

[SUCCESS] Created websiteku.
[INFO] Inside that directory, you can run several commands:

  `npm start`
    Starts the development server.

  `npm run build`
    Bundles your website into static files for production.

  `npm run serve`
    Serves the built website locally.

  `npm run deploy`
    Publishes the website to GitHub pages.

We recommend that you begin by typing:

  `cd websiteku`
  `npm start`

Penjelasan perintah:

  • npm start → Menjalankan server pengembangan di port 3000 secara default.
  • npm run build → Membangun website dalam format static files untuk produksi.
  • npm run serve → Menjalankan website yang sudah dibangun secara lokal.
  • npm run deploy → Mempublikasikan website ke GitHub Pages.

Untuk menjalankan website, masuk ke folder proyek:

cd websiteku
npm start

Jika ingin menjalankan di port 80, gunakan perintah berikut:

npm start -- --host 0.0.0.0 --port 80

Jika berhasil, akan muncul output berikut:

[SUCCESS] Docusaurus website is running at: http://localhost:80/

Akses website melalui browser dengan mengetikkan:

  • http://localhost:3000/ jika menggunakan port default.
  • http://<IP-Kalian>/ jika menggunakan port 80.

Struktur Proyek Docusaurus

Jika kamu memilih template Classic dan menamai situs kamu my-website, maka struktur proyek yang dihasilkan akan terlihat seperti ini:

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Penjelasan Struktur Proyek​

📂 /blog/​

Folder ini berisi file Markdown untuk blog. Jika fitur blog tidak digunakan, kamu bisa:

  • Menghapus folder ini, atau
  • Mengubah namanya setelah mengatur path option di konfigurasi.
    🔗 Referensi: Panduan Blog Docusaurus

📂 /docs/​

Folder ini berisi file Markdown untuk dokumentasi.

  • Urutan dokumen di sidebar dapat disesuaikan di sidebars.js.
  • Jika tidak menggunakan fitur dokumentasi, folder ini bisa dihapus atau diganti namanya setelah mengatur path option.
    🔗 Referensi: Panduan Dokumentasi

📂 /src/​

Folder untuk menyimpan file yang bukan bagian dari dokumentasi, seperti halaman kustom atau komponen React.

  • /src/pages/ → File JSX/TSX/MDX dalam folder ini akan dikonversi menjadi halaman website.
    🔗 Referensi: Panduan Halaman

📂 /static/​

Folder untuk menyimpan file statis seperti gambar, favicon, dan aset lainnya.

  • Semua konten dalam folder ini akan otomatis disalin ke direktori build saat proyek dikompilasi.

📜 docusaurus.config.js​

File konfigurasi utama untuk Docusaurus.

  • Ini adalah pengganti siteConfig.js dari Docusaurus v1.

📜 package.json​

Docusaurus adalah aplikasi berbasis React, sehingga kamu bisa menginstal dan menggunakan paket npm di dalamnya.

📜 sidebars.js​

File ini digunakan untuk mengatur urutan dokumen yang muncul di sidebar pada bagian dokumentasi.

Dengan memahami struktur ini, kamu bisa lebih mudah mengelola proyek Docusaurus dan menyesuaikannya sesuai kebutuhan! 🚀

Menjalankan Docusaurus di Background dengan systemd

Dengan menggunakan systemd, kamu bisa menjalankan Docusaurus secara otomatis di background sebagai layanan. Ini memungkinkan Docusaurus untuk tetap berjalan meskipun terminal ditutup dan juga dapat diatur untuk memulai saat booting.

Langkah 1: Membuat File Service systemd​

Untuk menjalankan Docusaurus sebagai layanan di background, kamu perlu membuat file unit systemd. Berikut adalah contoh file unit yang bisa kamu gunakan untuk Docusaurus:

Contoh File /etc/systemd/system/docu_production.service​

[Unit]
Description=Docusaurus Blog
After=network.target

[Service]
User=root
WorkingDirectory=/opt/docu_blog
ExecStart=/usr/bin/npm run serve -- --host 0.0.0.0 --port 80
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

*fyi Pada bagian ExecStart bisa diatur jika ingin mode production atau developer.

ExecStart=/usr/bin/npm run serve -- --host 0.0.0.0 --port 80

untuk mode production dan jika ingin menjalankan untuk mode developer

ExecStart=/usr/bin/npm start -- --host 0.0.0.0 --port 80
info

Jika ingin menggunakan mode production jangan lupa kita npm run build terlebihdahulu.

Penjelasan dari setiap bagian:

  • Description: Deskripsi layanan, misalnya "Docusaurus Blog".
  • After: Layanan ini akan mulai setelah jaringan siap.
  • User: Menentukan pengguna yang akan menjalankan layanan, di sini root, tapi sebaiknya gunakan pengguna khusus untuk keamanan.
  • WorkingDirectory: Lokasi folder tempat proyek Docusaurus kamu berada (misalnya /opt/docu_blog).
  • ExecStart: Perintah untuk menjalankan Docusaurus, di sini menggunakan npm run serve untuk menjalankan Docusaurus secara production di port 80 dan host 0.0.0.0 (agar dapat diakses dari semua alamat IP).
  • Restart: Mengatur agar layanan ini otomatis restart jika berhenti.
  • Environment: Mengatur variabel lingkungan, di sini NODE_ENV=production untuk menjalankan Docusaurus dalam mode produksi.
  • WantedBy: Layanan akan dimulai pada run level multi-user.target (mode multi-pengguna).

Langkah 2: Menggunakan User Khusus​

Untuk keamanan yang lebih baik, disarankan untuk menjalankan Docusaurus dengan pengguna yang tidak memiliki hak istimewa penuh. Kamu bisa membuat pengguna baru seperti docusaurus dan mengubah bagian User pada file service menjadi pengguna tersebut.

Membuat Pengguna Baru​

sudo useradd -r -m docusaurus

Kemudian, pastikan file dan direktori di /opt/docu_blog memiliki izin yang benar agar dapat diakses oleh pengguna ini.

Memberikan Permission ke Direktori​

sudo chown -R docusaurus:docusaurus /opt/docu_blog

Setelah itu, ubah User pada file docu_production.service menjadi docusaurus:

User=docusaurus

Langkah 3: Memberikan Permission pada npm​

Pastikan bahwa pengguna yang menjalankan Docusaurus (misalnya docusaurus) memiliki izin untuk menjalankan perintah npm. Kamu bisa memberikan izin dengan cara berikut:

sudo chmod -R 755 /opt/docu_blog

Pastikan juga bahwa direktori node_modules dapat diakses oleh pengguna yang menjalankan Docusaurus.

Langkah 4: Menyimpan dan Memulai Layanan systemd​

Setelah file service selesai dibuat, simpan perubahan dan jalankan perintah berikut untuk memuat file layanan baru dan memulai Docusaurus:

Memuat Layanan Baru​

sudo systemctl daemon-reload

Memulai Layanan​

sudo systemctl start docu_production.service

Menambahkan Layanan agar Dijalankan Secara Otomatis Saat Boot​

sudo systemctl enable docu_production.service

Langkah 5: Memeriksa Status Layanan​

Untuk memeriksa status dari layanan Docusaurus, kamu bisa menggunakan perintah berikut:

sudo systemctl status docu_production.service

Ini akan menampilkan status layanan dan memberi tahu kamu apakah layanan berjalan dengan baik.

Dengan mengikuti langkah-langkah ini, kamu bisa menjalankan Docusaurus di background menggunakan systemd dan memastikan layanan ini berjalan secara otomatis saat booting. Jangan lupa untuk selalu menggunakan pengguna yang tepat dan memberikan izin yang sesuai agar semuanya berjalan dengan aman!

Kesimpulan​

Sampai di sini, kalian sudah berhasil menginstall dan menjalankan Docusaurus 🎉. Sekarang, kalian bisa mulai mengembangkan dokumentasi atau website kalian menggunakan Docusaurus!