DEV Community: hardyweb

Penjelasan Layman: Agent Harness (PiG / KiloCode)

hardyweb — Sat, 10 Oct 2026 13:19:38 +0000

Dokumen ini menerangkan lima komponen utama dalam workflow coding agent yang aku gunakan. Tujuannya mudah: memahami bagaimana agent menerima arahan, menyimpan konteks, mempelajari cara kerja dan mengikuti prinsip pembangunan perisian.

Kita tak perlu bermula dengan jargon teknikal. Kita gunakan analogi pekerja, buku panduan dan buku log supaya konsep lebih mudah difahami.

Nota: Dokumen ini menggabungkan konsep umum coding agent dengan konfigurasi peribadi aku. Tidak semua agent mempunyai mekanisme atau struktur fail yang sama. Perincian teknikal perlu dirujuk kepada dokumentasi agent masing-masing.

1. Skills — Buku Panduan Kerja

Apa itu Skills?

Bayangkan agent AI sebagai pekerja baru yang sangat pintar, tetapi belum tahu cara kerja di tempat kita.

Dia tahu menulis kod, memahami arahan dan menyelesaikan masalah. Tetapi dia mungkin belum tahu:

Macam mana kita suka commit message ditulis.
Format laporan bulanan yang kita gunakan.
Langkah-langkah deployment ke server.
Standard keselamatan dalam projek.
Cara kita mengurus projek Laravel.

Skills ialah panduan yang mengajar agent cara melakukan sesuatu tugas mengikut keperluan kita.

Bezakan Capability dengan Knowledge

Perkara	Extension / Tool	Skill
Fungsi	Memberi keupayaan melakukan sesuatu	Memberi panduan bagaimana melakukan sesuatu
Contoh	Menjalankan arahan Git	Menulis commit message mengikut format projek
Bentuk	Kod, integrasi atau mekanisme alat	Arahan dan bahan rujukan
Kegunaan	Agent perlu melakukan sesuatu tindakan	Agent perlu mengikuti kaedah kerja tertentu

Contoh mudah:

Extension atau tool memberikan agent tangan untuk menggunakan Git. Skill pula mengajarnya cara menulis commit message yang kita kehendaki.

Bagaimana Skills berfungsi?

Dalam PiG, salah satu bentuk skill ialah fail SKILL.md yang disimpan dalam direktori skill.

Contoh:

~/.pig/skills/commit/SKILL.md

Kandungan fail boleh menerangkan nama skill, tujuan penggunaannya dan arahan yang perlu diikuti.

Contoh ringkas:

---
name: commit
description: Tulis commit message mengikut format projek.
---

Gunakan format:

type(scope): ringkasan

Ringkasan mestilah padat dan jelas.
Terangkan sebab perubahan dalam body jika perlu.
Jangan masukkan perubahan yang tidak berkaitan.

Apabila agent menemui skill tersebut, ia boleh menggunakan maklumat dan arahan yang disediakan apabila skill berkenaan diperlukan.

Cara pemuatan dan penggunaan skill bergantung pada implementasi agent. Jangan anggap semua agent membaca keseluruhan kandungan setiap skill pada permulaan sesi.

Bagaimana PiG menemui Skills?

PiG menyokong pemuatan skill secara eksplisit, termasuk penggunaan pilihan --skill, serta mekanisme discovery daripada direktori yang disokong.

Contoh:

pig --skill commit

Direktori yang digunakan perlu mengikut struktur dan konfigurasi yang disokong oleh versi PiG berkenaan.

Kenapa Skills berguna?

Tanpa skill, kita mungkin perlu menerangkan semula cara kerja yang sama berulang kali.

Dengan skill, kita boleh menyimpan panduan tersebut dan menggunakannya semula.

Ibarat SOP (Standard Operating Procedure) untuk pekerja manusia.

Ringkasan: Skills ialah panduan kerja khusus yang boleh digunakan semula supaya agent dapat mengikuti kaedah kerja yang kita kehendaki.

2. AGENTS.md — Buku Peraturan Tetap

Kalau skill ialah panduan untuk tugas tertentu, AGENTS.md pula boleh digunakan untuk menetapkan peraturan umum dan arahan bagi agent yang bekerja dalam sesuatu projek.

Contohnya, sebelum mula bekerja, kita mahu agent memahami peraturan berikut:

Jangan mengubah fail sensitif tanpa kebenaran.
Periksa struktur projek sebelum membuat perubahan.
Gunakan Form Request untuk pengesahan input Laravel.
Jangan membuat deployment tanpa kelulusan.
Sahkan hasil perubahan sebelum menyatakan kerja selesai.

Arahan seperti ini sesuai diletakkan dalam fail arahan projek.

Apa yang patut ada dalam AGENTS.md?

Dalam workflow aku, kandungannya merangkumi beberapa perkara.

Bahagian	Maksud
Global Principles	Prinsip asas seperti keselamatan dan backup
Workspace & Project Boundaries	Had kawasan kerja agent
Workflow Preferences	Cara kerja yang disukai, termasuk Laravel, Go dan Git
State & Memory	Arahan tentang cara membaca dan mengemas kini konteks kerja
Approval Gates	Tindakan yang memerlukan kelulusan
Verification	Keperluan mengesahkan hasil sebelum melaporkan kejayaan

Ini ialah susunan yang aku gunakan untuk mengurus workflow sendiri, bukan format wajib bagi semua coding agent.

Kenapa nama fail penting?

Agent tidak semestinya membaca semua fail Markdown dalam direktori projek.

Ia biasanya mempunyai mekanisme tertentu untuk mencari fail arahan yang dikenali. PiG mempunyai aturan pemuatan konteks tersendiri, manakala KiloCode juga mempunyai mekanisme arahan dan konfigurasi sendiri.

Oleh itu, jangan menganggap fail bernama Agent.md, AGENTS.md atau CLAUDE.md akan diproses dengan cara yang sama oleh semua agent.

Jika kita mahu menggunakan fail arahan tertentu, semak dokumentasi agent yang digunakan dan pastikan fail itu benar-benar dimuatkan.

Kenapa AGENTS.md perlu ringkas?

Arahan yang sentiasa dimasukkan ke dalam konteks agent menggunakan sebahagian daripada token yang tersedia.

Sebab itu, aku lebih suka meletakkan peraturan umum yang penting dalam fail arahan utama. Panduan terperinci untuk tugas tertentu boleh disimpan dalam skills atau dokumen rujukan berasingan.

Ringkasan: AGENTS.md ialah tempat untuk meletakkan arahan dan batas kerja agent. Pastikan kandungannya jelas, relevan dan benar-benar dibaca oleh agent yang digunakan.

3. brain/ — Buku Ingatan Kerja

Masalah yang cuba diselesaikan

Apabila sesi perbualan tamat, agent mungkin tidak lagi mempunyai keseluruhan konteks kerja yang diperlukan dalam sesi seterusnya.

Bayangkan kita sedang membangunkan sistem Laravel. Kita sudah memeriksa database, mengubah beberapa fail dan mengenal pasti satu masalah. Esok, kita membuka sesi baru.

Kalau konteks tidak disimpan, kita mungkin terpaksa mengulangi pemeriksaan yang sama.

Di sinilah konsep brain/ berguna.

Dalam workflow aku, brain/ ialah direktori untuk menyimpan catatan kerja yang boleh dibaca semula oleh agent pada sesi berikutnya.

Ia bukan bermaksud model AI tiba-tiba mempunyai ingatan kekal. Maklumat itu kekal kerana kita menyimpannya dalam fail dan mengarahkan agent supaya merujuknya semula.

Analogi buku log jurutera

Buku log seorang jurutera biasanya merekodkan:

Apa yang sudah dilakukan.
Masalah yang ditemui.
Keputusan yang dibuat.
Perkara yang masih belum selesai.
Langkah seterusnya.

Konsep yang sama digunakan dalam brain/.

Contoh struktur brain/

Berikut ialah contoh struktur yang aku gunakan sebagai konvensyen kerja:

brain/
├── task.md
├── walkthrough.md
├── architecture.md
├── ai_guidelines.md
├── gaya-penulisan.md
└── decisions/
    ├── 001-database.md
    └── 002-authentication.md

Fungsi setiap fail:

Fail	Kegunaan
`task.md`	Status tugas, masalah semasa dan langkah seterusnya
`walkthrough.md`	Rekod perjalanan sesi kerja
`architecture.md`	Gambaran struktur dan hubungan komponen sistem
`decisions/`	Rekod keputusan teknikal dan sebab pemilihannya
`ai_guidelines.md`	Prinsip kerja dan pendekatan pembangunan
`gaya-penulisan.md`	Panduan gaya penulisan

Struktur ini bukan struktur wajib PiG atau KiloCode. Ia ialah reka bentuk dokumentasi yang boleh disesuaikan mengikut projek.

Mental Anchor — Penanda untuk sambung kerja

Satu idea yang aku gunakan ialah Mental Anchor.

Pada akhir catatan sesi, agent perlu menyatakan lokasi sebenar untuk menyambung kerja.

Contoh:

## Status Semasa

- Migration telah diperiksa.
- Form Request telah dikemas kini.
- Feature test masih gagal pada kes authorization.

**Mental Anchor:**
Sambung dengan menyiasat kegagalan authorization
dalam feature test sebelum mengubah kod production.

Mental Anchor membantu agent mengetahui titik permulaan yang sesuai untuk sesi seterusnya.

Namun, catatan ini masih perlu disahkan dengan keadaan sebenar repository. Fail boleh berubah selepas catatan ditulis.

Dua jenis brain dalam workflow aku

Aku membezakan catatan global dengan catatan khusus projek.

Jenis	Contoh lokasi	Tujuan
Global	`~/.config/kilo/brain/`	Prinsip dan catatan umum workflow
Projek	`<projek>/.agents/brain/`	Konteks dan status projek tertentu

Lokasi ini ialah konvensyen peribadi aku, bukannya lokasi standard yang dijamin dibaca secara automatik oleh PiG atau KiloCode.

Agent perlu diarahkan untuk membaca lokasi yang betul. Jika ada catatan global dan projek, aturan keutamaan juga perlu ditetapkan supaya konteks tidak bercanggah.

Peraturan penting

Jangan simpan password, API token atau rahsia lain dalam fail brain.
Catat perkara yang benar-benar berlaku, bukan perkara yang diandaikan.
Nyatakan masalah yang belum selesai dengan jelas.
Rekodkan keputusan penting dan sebabnya.
Gunakan Git untuk mengesan perubahan pada fail dokumentasi apabila sesuai.

Ringkasan: brain/ ialah sistem catatan kerja yang membantu mengekalkan konteks antara sesi, dengan syarat agent membaca dan mengemas kini catatan tersebut dengan betul.

4. ai_guidelines.md — Falsafah Kerja dan Cara Berfikir

Kalau AGENTS.md menerangkan arahan dan batas kerja, ai_guidelines.md pula menerangkan prinsip yang menjadi panduan kepada cara kerja aku.

Ia bukan fail konfigurasi ajaib. Ia ialah dokumen yang mengandungi prinsip yang mahu aku kekalkan dalam pembangunan perisian dengan bantuan AI.

Analogi mudah

AGENTS.md: Jangan langgar lampu merah.
ai_guidelines.md: Aku percaya keselamatan lebih penting daripada sampai cepat.

Yang pertama menetapkan arahan. Yang kedua menerangkan prinsip di sebalik cara kita bekerja.

Prinsip utama

Dalam workflow aku, antara prinsip yang penting ialah:

1. Manusia memahami dan bertanggungjawab

AI membantu menyediakan penyelesaian, tetapi aku perlu memahami, mengesahkan dan bertanggungjawab terhadap keputusan akhir.

2. Kod mudah mengatasi kod yang terlalu clever

Penyelesaian yang mudah dibaca dan diselenggara biasanya lebih sesuai daripada kod yang kelihatan hebat tetapi sukar difahami.

3. Keselamatan bermula sejak reka bentuk

Security bukan kerja tambahan selepas sistem siap. Ia perlu dipertimbangkan sejak awal pembangunan.

4. Periksa sebelum mengubah

Agent perlu memahami keadaan sebenar projek sebelum membuat perubahan. Jangan mengandaikan struktur, dependency atau konfigurasi tanpa pemeriksaan.

5. Git dan deployment kekal di bawah kawalan manusia

Agent boleh menyediakan perubahan, menjalankan ujian dan melaporkan hasil. Dalam workflow aku, keputusan untuk commit, push dan deploy kekal di tangan manusia.

6. Terus terang apabila tidak pasti

Jika sesuatu arahan gagal, agent perlu melaporkan kegagalan tersebut dan bukannya mendakwa kerja sudah selesai.

Prinsip utama aku

AI assists. Hardy understands, verifies, and owns the final decision.

AI membantu. Aku memahami, mengesahkan dan bertanggungjawab terhadap keputusan akhir.

Dokumen ini boleh dirujuk apabila agent perlu memahami pendekatan pembangunan yang aku utamakan. Untuk memastikan ia benar-benar digunakan, arahan utama perlu memberitahu agent bila dan bagaimana hendak membaca fail tersebut.

Ringkasan: ai_guidelines.md ialah rujukan kepada prinsip dan pendekatan kerja yang aku mahu kekalkan dalam pembangunan perisian dengan bantuan AI.

5. soul.md — Tujuan dan Falsafah Mendalam Agent

Kalau ai_guidelines.md memberikan ringkasan prinsip kerja, soul.md pula digunakan dalam workflow aku untuk menghuraikan prinsip tersebut dengan lebih mendalam.

Nama soul.md bukan bermaksud agent mempunyai jiwa atau kesedaran seperti manusia. Ia ialah nama fail yang aku pilih untuk menyimpan falsafah dan tujuan reka bentuk agent.

Perbezaan antara tiga fail

Fail	Soalan utama
`AGENTS.md`	Apakah arahan dan batas kerja aku?
`ai_guidelines.md`	Apakah prinsip kerja yang perlu aku ikuti?
`soul.md`	Mengapa prinsip tersebut penting?

Analogi mudah:

AGENTS.md ialah buku peraturan.
ai_guidelines.md ialah nota ringkas di atas meja.
soul.md ialah dokumen yang menerangkan sebab di sebalik prinsip tersebut.

Apa yang terkandung dalam soul.md?

Dalam reka bentuk aku, dokumen ini merangkumi prinsip seperti:

Security First: Keselamatan dipertimbangkan sejak awal.
Human Judgment First: Manusia kekal bertanggungjawab terhadap keputusan.
Verify, Don't Assume: Pengesahan lebih penting daripada andaian.
Production-Ready: Perubahan dibuat dengan mengambil kira kebolehselenggaraan dan pemulihan.
Self-Hosted Pragmatism: Mengutamakan penyelesaian open-source dan self-hosted apabila sesuai.
Learn Fundamentals: Memahami asas Linux, rangkaian, SQL dan pembangunan perisian.
CLI Transparency: Menunjukkan arahan dan hasil sebenar supaya kerja boleh difahami.
Backup & Rollback: Merancang pemulihan sebelum perubahan berisiko.
Documentation: Dokumentasi ialah sebahagian daripada kerja.
Preserve Context: Menyimpan maklumat penting untuk sesi seterusnya.
Bounded Steps: Membuat perubahan secara terkawal dan berperingkat.
Agent Boundaries: Tidak mereka hasil, menyembunyikan ralat atau mendakwa kejayaan tanpa bukti.

Prinsip ini membentuk identiti workflow yang aku mahu bina, bukannya keupayaan yang terjamin tersedia secara automatik dalam sesuatu model.

Mental Anchor — Kitaran kerja utama

Dalam workflow aku, kerja agent mengikuti kitaran berikut:

Understand
    ↓
Inspect
    ↓
Plan
    ↓
Change
    ↓
Verify
    ↓
Document
    ↓
Next Task

Maksudnya:

Understand: Fahami permintaan dan masalah.
Inspect: Periksa keadaan sebenar sistem.
Plan: Tentukan perubahan yang diperlukan.
Change: Laksanakan perubahan secara terkawal.
Verify: Jalankan ujian atau pemeriksaan yang sesuai.
Document: Catat perubahan dan hasil pengesahan.
Next Task: Tentukan langkah seterusnya.

Kitaran ini membantu mengelakkan agent daripada terus mengubah kod sebelum memahami masalah.

Satu prinsip yang aku pegang

Do the work, verify the work, and leave enough evidence for the next person—or the next session—to understand the work.

Buat kerja, sahkan hasilnya dan tinggalkan bukti yang mencukupi supaya orang lain atau sesi seterusnya boleh memahami apa yang telah dilakukan.

Ringkasan: soul.md ialah dokumen falsafah mendalam yang menerangkan tujuan, prinsip dan pendekatan yang aku mahu jadikan panduan kepada workflow coding agent.

6. Gambaran Besar — Lima Lapisan Workflow

Selepas memahami setiap komponen, kita boleh melihat bagaimana semuanya saling melengkapi.

soul.md
   ↓
Falsafah dan tujuan kerja

ai_guidelines.md
   ↓
Prinsip dan pendekatan pembangunan

AGENTS.md
   ↓
Arahan dan batas kerja

brain/
   ↓
Konteks dan catatan antara sesi

skills/
   ↓
Panduan bagi tugas khusus

Setiap komponen menjawab soalan yang berbeza.

Komponen	Soalan yang dijawab	Peranan
`soul.md`	Mengapa prinsip ini penting?	Falsafah mendalam
`ai_guidelines.md`	Bagaimana aku mahu bekerja?	Prinsip kerja
`AGENTS.md`	Apakah arahan dan batas kerja?	Arahan agent
`brain/`	Apa yang telah berlaku dan apa seterusnya?	Catatan kerja
`skills/`	Bagaimana tugas tertentu patut dilakukan?	Panduan khusus

Walaupun kelima-lima komponen ini berbeza, semuanya boleh membantu membina workflow yang lebih konsisten.

Namun, keberkesanannya bergantung pada cara agent dikonfigurasikan, fail yang benar-benar dibaca dan ketepatan maklumat yang disimpan.

7. Kesimpulan

Bagi aku, penggunaan coding agent bukan sekadar memberikan prompt dan menunggu kod siap.

Aku mahu agent memahami batas kerjanya, mengikuti panduan projek, mengekalkan konteks dan mengesahkan hasil perubahan. Pada masa yang sama, aku mahu proses kerja kekal telus supaya aku boleh belajar daripada setiap perubahan yang dibuat.

Lima komponen ini membantu memisahkan tanggungjawab tersebut:

Skills: Panduan untuk tugas tertentu.
AGENTS.md: Arahan dan batas kerja.
brain/: Catatan dan konteks kerja.
ai_guidelines.md: Prinsip pembangunan.
soul.md: Falsafah yang mendasari workflow.

Tidak semua projek memerlukan kelima-lima komponen. Projek kecil mungkin memadai dengan arahan ringkas dan beberapa skills. Projek yang lebih kompleks mungkin memerlukan rekod keputusan, dokumentasi seni bina dan catatan sesi yang lebih tersusun.

Yang penting, jangan membina terlalu banyak lapisan semata-mata kerana ia kelihatan menarik. Gunakan apa yang benar-benar membantu kerja.

Bagi aku, prinsip akhirnya mudah:

Handle the routine. — Urus kerja rutin.

Surface the overlooked. — Bangkitkan perkara yang mungkin terlepas pandang.

Explain the complicated. — Terangkan perkara yang rumit.

Verify the important. — Sahkan perkara yang penting.

Preserve what was learned. — Simpan apa yang telah dipelajari.

Leave the human in control. — Manusia kekal mengawal keputusan akhir.

Itulah asas workflow coding agent yang aku mahu bina: AI membantu melakukan kerja, tetapi manusia tetap memahami sistem, mengesahkan hasil dan bertanggungjawab terhadap keputusan.

Artikel ini ditulis dengan bantuan AI.

Benchmarking Gemma 4 E2B on CPU with llama.cpp: A Practical Local AI Experiment

hardyweb — Fri, 09 Oct 2026 00:02:22 +0000

1. Why This Experiment?

I want to run a local language model for everyday office work without depending entirely on a cloud-based AI service.

My intended use cases include:

A local chatbot for general questions.
Drafting Malay and English letters, memoranda, and emails.
Preparing technical documentation.
Basic spreadsheet analysis involving hundreds of rows, rather than thousands or millions.
Learning how to deploy and tune local AI models on different computers.

The challenge is that not every computer has the same CPU. Some machines have older processors with only a few cores, while others have newer CPUs with more cores and threads.

Instead of assuming that one configuration works everywhere, I want to establish a baseline and use the same benchmarking method across different machines.

This article records my initial experiments with Gemma 4 E2B using llama-server from llama.cpp.

2. Test Environment

The initial experiment was performed on a resource-constrained machine.

Component	Specification
CPU	AMD Athlon 3000G
CPU architecture	2 physical cores, 4 logical threads
Graphics	Radeon Vega Graphics
Runtime environment	WSL
WSL memory limit	5 GB
Inference backend	llama.cpp `llama-server`
Inference mode	CPU-only
Parallel slots	1

The main model file was:

gemma-4-E2B-it-qat-UD-Q4_K_XL.gguf

The model is an instruction-tuned Gemma 4 E2B GGUF using the QAT Q4_K_XL quantization variant.

The objective is not to establish a universal performance figure for this model. It is to understand how configuration choices affect inference on this particular machine.

Note: The exact llama.cpp version/build identifier was not recorded in this initial benchmark. Future tests should record it because performance and available options can change between builds.

3. Establishing a Baseline

I started with a conservative configuration:

llama-server \
  -m ./gemma-4-E2B-it-qat-UD-Q4_K_XL.gguf \
  -t 2 \
  -tb 2 \
  -c 2048 \
  -b 64 \
  -ub 16 \
  --host 127.0.0.1 \
  --port 5001

The initial reported average generation speed was approximately 4.6 tokens per second.

I then tested different thread counts and batch sizes. The following table records the results observed during the experiments.

Test	Main configuration change	Reported speed
A	`-t 2 -tb 2 -c 2048 -b 64 -ub 16`	4.6 t/s
B	`-t 3 -tb 4 -c 2048 -b 64 -ub 16`	5.9 t/s
B, repeat	Same thread configuration	6.1 t/s
C	`-b 32 -ub 8`, with `-t 3 -tb 4`	6.0 t/s
D	`-t 4 -tb 4`, with the original batch sizes	5.8 t/s

These results suggested that using three generation threads and four batch-processing threads was worth investigating further on this CPU.

Increasing the thread count did not automatically improve performance. The four-thread test was slower than the three-thread result in these particular trials.

However, these were exploratory measurements rather than a controlled benchmark. They should not be interpreted as proof that three threads will always be optimal.

4. Testing Additional Server Parameters

Next, I added several parameters:

-np 1
-ngl 0
--temp 0.7
--top-p 0.8
--top-k 20
--metrics
--jinja
--cache-type-k q8_0
--cache-type-v q8_0
--reasoning-format none

The reported speed was approximately 6.4 tokens per second.

Because several options were added together, this result does not tell us which individual parameter, if any, improved generation speed.

I then tested Flash Attention explicitly:

-fa on

The reported speed for that trial was approximately 6.2 tokens per second.

This trial did not demonstrate an improvement, so I left Flash Attention out of the preferred configuration for now. A more controlled test would be needed to establish whether it helps on another CPU or build.

What these parameters are for

-np 1: Configures one parallel sequence slot for this single-user experiment.
-ngl 0: Keeps model inference on the CPU rather than offloading model layers to a GPU.
--cache-type-k q8_0 and --cache-type-v q8_0: Select quantized data types for the key and value caches.
--metrics: Enables the server's metrics endpoint.
--jinja: Enables the relevant Jinja chat-template handling.
--temp, --top-p, and --top-k: Control sampling behaviour, not a guaranteed performance improvement.
--reasoning-format none: Configures reasoning-format handling for the server.

The available options and their precise behaviour should be checked against the official llama.cpp server documentation.

5. Best Reported Configuration So Far

The strongest reported result from the exploratory trials was approximately 6.6 tokens per second.

The configuration was:

llama-server \
  -m ./gemma-4-E2B-it-qat-UD-Q4_K_XL.gguf \
  -t 3 \
  -tb 4 \
  -c 2048 \
  -b 128 \
  -ub 32 \
  -np 1 \
  -ngl 0 \
  --temp 0.7 \
  --top-p 0.8 \
  --top-k 20 \
  --metrics \
  --jinja \
  --cache-type-k q8_0 \
  --cache-type-v q8_0 \
  --reasoning-format none \
  --host 127.0.0.1 \
  --port 5001

This is my provisional baseline, not a claim that the configuration is universally optimal.

The larger batch settings were present in the best reported trial. More repeatable testing is required to establish whether they improve performance consistently, particularly because batch settings can affect prompt processing differently from token generation.

The --no-mmap option has not been benchmarked in this experiment and should not be considered part of the tested configuration.

6. A Real Office-Work Test

A later trial used a Malay prompt requesting a formal memorandum about periodic maintenance for internally developed systems using Laravel and Debian Linux.

The generated memorandum covered:

Security patching.
Package updates.
Log and performance monitoring.
Risks associated with inadequate maintenance.
A recommendation to include maintenance in the department's operational plan.

The reported statistics were:

Metric	Result
Prompt tokens	126
Generated tokens	391
Reported average generation speed	6.0 t/s
Approximate generation time from token count and speed	65 seconds

The time is an estimate calculated from the reported token count and speed. It is not a direct end-to-end timing measurement.

Observations about output quality

The memorandum had a recognisable formal structure and its recommendations were generally relevant to the requested topic.

However, it also generated a specific date, 26 May 2024, even though the prompt did not provide that date. This is an important reminder that local language models can introduce unsupported details.

For actual office use, the application should provide authoritative information such as dates, recipient details, reference numbers, and departmental names. Generated letters and technical recommendations should still be reviewed before they are issued or acted upon.

The experiment therefore evaluates two separate dimensions:

Performance: How quickly the model generates output.
Quality: Whether the generated output is accurate, relevant, appropriately formatted, and safe to use.

A higher tokens-per-second figure does not necessarily mean a better office assistant.

6.1 Testing Document Understanding and Structured Data Analysis

After testing the model's ability to draft an office memorandum, I moved on to two additional tasks using plain-text (.txt) documents.

The objective was to evaluate whether Gemma 4 E2B could extract facts from a document, follow instructions, identify missing information, and analyse a small dataset without inventing values.

Test 1 — Document Understanding

The first test used a simulated internal system maintenance procedure. The document covered maintenance schedules, change-management requirements, database backups, restore testing, and incident records.

I asked the model nine questions, including which details were explicitly documented and which were missing.

Metric	Result
Prompt tokens evaluated	1,051
Generated tokens	638
Reported average generation speed	5.0 t/s
Questions answered	9
Overall observation	Satisfactory for this test

The model answered all nine questions correctly in this trial. It produced a structured frequency table, identified the required change-record fields, explained why a successful backup job does not guarantee that restoration will work, and avoided inventing details that were absent from the source document.

This was an encouraging result for document-grounded question answering. However, it was a single qualitative test rather than a statistically validated accuracy benchmark.

Test 2 — ICT Asset Data Analysis

The second test used a simulated ICT asset inventory containing eight records, including desktops, laptops, monitors, printers, and a scanner. Each record included a quantity, unit cost where available, and status.

The model was asked to calculate the total number of units, calculate record-level costs, identify missing prices, summarise assets requiring inspection, and prepare a short management summary.

I first ran the test with a context size of 2,048 tokens.

Metric	Result
Prompt tokens evaluated	1,462
Generated tokens	585
Reported average generation speed	5.0 t/s
Output completion	Incomplete

The response stopped before all questions were answered. The reported context usage reached approximately 2,048 tokens, suggesting that the context limit may have contributed to the incomplete response. This is an observation from the reported run, not proof that context capacity was the only cause.

I then repeated the test with a context size of 4,096 tokens.

Metric	Result
Prompt tokens evaluated	1,098
Generated tokens	1,696
Reported average generation speed	5.3 t/s
Output completion	All 10 questions answered

With the larger context, the model completed the requested analysis. It correctly identified 22 total units, calculated the individual costs for records with known prices, and identified two records marked Perlu diperiksa, covering four units in total. It also correctly noted that this status alone does not prove that an asset is broken.

However, the final cost calculation was incorrect. The model reported RM33,850, whereas the correct sum of the seven calculable record costs is RM33,050. The individual record-level calculations were correct, but the final addition was not.

The record with a missing unit cost was correctly excluded from the total.

What These Tests Tell Me

These experiments highlight three practical findings:

Document understanding looks promising. In the first trial, the model extracted facts and respected missing information in a simulated maintenance procedure.
Context capacity matters for longer tasks. The 2,048-token run produced an incomplete response, while the 4,096-token run completed the task. The tests were not identical in token usage, so this should be treated as an initial observation rather than a controlled performance comparison.
Correct-looking calculations still need verification. The asset-analysis test contained correct individual calculations but an incorrect final sum. A fluent explanation and a completed response do not guarantee numerical accuracy.

For practical office applications, I would use the language model to interpret documents, explain results, and prepare summaries. For financial totals and other exact calculations, I would rely on deterministic tools such as PHP, SQL, or spreadsheet formulas, then provide the verified results to the model for explanation.

For now, a context size of 4,096 tokens is a more useful working configuration for this type of longer document task on my test machine. I still need to monitor memory usage and repeat the tests before drawing broader conclusions about performance or reliability.

7. Why the Results Are Still Preliminary

The measurements above were collected during interactive experiments. The prompts and output lengths were not identical in every trial, and some trials changed several parameters at once.

Consequently, the results are useful for narrowing down configurations, but not for drawing definitive conclusions about individual options.

A more reliable benchmark should:

Use the same prompt for every comparison.
Set the same maximum output-token limit.
Allow the model and system to reach a comparable starting state.
Repeat each configuration at least three times.
Record the median and average generation speed.
Record prompt-processing speed separately from generation speed where possible.
Monitor RAM usage, CPU utilisation, thermal behaviour, and swapping.
Check output quality using the same practical tasks.

The llama.cpp server supports a Prometheus-compatible metrics endpoint when --metrics is enabled. Its reported metrics can help distinguish prompt-processing throughput from generation throughput. See the server metrics documentation.

8. A Repeatable Benchmark Plan for Other PCs

The long-term objective is to repeat this experiment across computers with different CPU generations, core counts, and memory limits.

For each machine, I will record:

Field	What to record
Machine ID	A simple label, such as `PC-01`
CPU	Exact processor model
CPU topology	Physical cores and logical threads
Memory	Installed RAM and the actual limit available to the inference environment
Operating environment	Linux, WSL, or another supported environment
llama.cpp build	Version, build details, and relevant compilation options
Model	Exact model filename and quantization
Context size	Value of `-c`
Threads	Values of `-t` and `-tb`
Batch settings	Values of `-b` and `-ub`
Cache settings	K and V cache types
Prompt and output	Prompt tokens and generated tokens
Performance	Generation tokens/s and prompt tokens/s, when available
Resource use	Peak RAM, CPU utilisation, swapping, and temperature where available
Quality	Accuracy, language quality, formatting, and unsupported claims

Recommended test sequence

Start with the provisional baseline and change one variable at a time.

Stage 1 — Thread configuration

Compare suitable values for -t and -tb based on the CPU's topology. For a CPU with two physical cores and four logical threads, for example, test a small range of thread settings instead of assuming that all logical threads will always help.

Stage 2 — Context size

Compare -c 1024 with -c 2048 while keeping other parameters constant. A smaller context may reduce memory requirements, but it also limits how much conversation or source material can fit into the context.

The -c 1024 configuration is a proposed future test, not a completed measurement in this experiment.

Stage 3 — Batch sizes

Test -b and -ub independently where practical. Record prompt-processing throughput as well as generation speed, because the effect may differ between these workloads.

Stage 4 — KV cache

Only after establishing a stable baseline, consider comparing q8_0 with other supported cache types, such as q4_0. Measure memory use, speed, stability, and output quality. Do not assume that a smaller cache will necessarily make inference faster.

Stage 5 — Practical workload

Run the same set of tasks on each machine:

A short chatbot question.
A formal Malay letter or memorandum.
An English email.
A structured technical document.
A small spreadsheet-analysis task.

This will help determine which configurations are suitable for actual use rather than merely optimising a single benchmark prompt.

9. Practical Lessons So Far

The initial experiment suggests several useful lessons:

A local model can produce a structured Malay office memorandum on a CPU-only machine.
The best reported speed so far was 6.6 tokens per second, but the benchmark needs more controlled repetitions.
More CPU threads do not guarantee better generation speed.
Sampling parameters should be chosen for the desired response behaviour, not treated as performance switches.
Context size, batch configuration, and cache types should be tested separately.
RAM usage and thermal stability matter, particularly on older or resource-constrained computers.
Output accuracy must be evaluated separately from generation speed.
For spreadsheet tasks, an application can process the actual spreadsheet with a suitable data library and pass relevant results to the model instead of sending an entire workbook into the prompt.

10. Conclusion

This experiment establishes a starting point for running Gemma 4 E2B with llama.cpp on modest CPU hardware.

The current provisional configuration uses three generation threads, four batch threads, a context size of 2048, and batch settings of 128 and 32. It achieved a reported best speed of approximately 6.6 tokens per second in the exploratory trials.

The next goal is not simply to make one computer faster. It is to build a repeatable method for finding practical configurations across several computers, including older CPUs and newer machines with more cores.

The long-term measure of success is a useful local assistant for everyday office work: responsive enough for conversation, capable of producing good first drafts, and reliable enough to support documentation and basic data analysis with appropriate human review.

Benchmark status: Initial exploratory phase completed. Further parameter testing is paused until a new machine or a controlled test session is selected.

This article was created with the help of AI

Turn Your Windows PC into a Linux & FreeBSD Learning Lab with WSL2 and Incus

hardyweb — Sat, 03 Oct 2026 12:13:58 +0000

If you're using Windows 11 and want to learn Linux, you don't necessarily need to dual-boot your computer, install several heavyweight virtual machines, or buy another machine just for a learning lab.

You can build a surprisingly capable Linux and Unix learning environment using something you may already have:

A Windows PC.

The idea behind this project is simple:

Use Windows as the host, WSL2 as the foundation, and Incus as the laboratory.

From there, you can create Linux containers, experiment with networking and services, and even run a FreeBSD virtual machine.

The result is the Incus WSL Learning Laboratory — a structured, hands-on environment designed for students and beginners who want to learn Linux by actually using it.

Why Build a Linux Lab on Windows?

Learning Linux from a book or watching tutorials is useful, but eventually you need somewhere to experiment.

You want to be able to:

create users
install packages
break configurations
configure networking
run web servers
experiment with DNS
manage services
create multiple machines
destroy them
start again

Doing these experiments directly on your main computer isn't always a good idea.

Dual-booting introduces another layer of complexity.

Traditional virtual machines work, but managing multiple VMs can become cumbersome, especially on a modest laptop.

This is where WSL2 + Incus becomes interesting.

The Architecture

The laboratory uses several layers:

Windows 11
    │
    └── WSL2
          │
          └── Debian
                │
                └── Incus
                      │
                      ├── Linux Containers
                      │     ├── Debian
                      │     ├── Ubuntu
                      │     └── Alpine
                      │
                      └── Virtual Machines
                            └── FreeBSD

The important thing here is that each layer has a different purpose.

Windows 11 is your everyday operating system.

WSL2 provides the Linux environment running alongside Windows.

Debian becomes the Linux environment where Incus is installed.

Incus becomes the laboratory manager.

Once Incus is running, you can create isolated Linux containers and virtual machines for your experiments.

Why Incus?

You may already know tools such as Docker, VirtualBox, or VMware.

Incus solves a slightly different problem.

It is designed to manage system containers and virtual machines.

Instead of thinking only in terms of application containers, you can think in terms of small Linux systems.

For example:

incus launch images:debian/13 debian01

Now you have a Debian system.

You can enter it:

incus exec debian01 -- bash

And start working with it like a small Linux machine.

You can create another one:

incus launch images:ubuntu/24.04 ubuntu01

And perhaps an Alpine system:

incus launch images:alpine/3.22 alpine01

Now your Windows PC has several Linux environments running side by side.

That's already a useful learning laboratory.

From One Linux Machine to a Small Network

This is where things become more interesting.

Instead of learning Linux on one machine, you can create several machines and make them communicate with each other.

For example:

                 Incus
                   │
          ┌────────┼────────┐
          │        │        │
       Debian   Ubuntu    Alpine
       10.10.   10.10.    10.10.
       10.101   10.102    10.103
          │        │        │
          └────────┼────────┘
                   │
                Network

You can then start experimenting with concepts such as:

IP addressing
routing
DNS
SSH
HTTP/HTTPS
firewalls
service discovery
network troubleshooting

Commands such as:

ping
ip
ss
curl
dig
nslookup
traceroute

become practical tools instead of commands you only read about.

This changes the learning experience significantly.

You're no longer asking:

"What does DNS do?"

You're asking:

"Why can't this container resolve that hostname?"

That's a much better question to learn from.

Linux Distributions Become Your Playground

One of the advantages of using Incus is that you don't have to commit to a single Linux distribution.

You can have:

Debian
Ubuntu
Alpine

running simultaneously.

This makes it easy to compare how different distributions approach similar tasks.

For example:

Debian

apt install nginx

Ubuntu

apt install nginx

Alpine

apk add nginx

The commands are different, the package management is different, and the base systems are different.

That difference is useful.

It encourages you to learn Linux concepts, rather than memorizing commands for one particular distribution.

And Then There Is FreeBSD

The laboratory isn't limited to Linux.

One of the things I wanted to explore was FreeBSD.

FreeBSD isn't Linux.

It has its own kernel, userland, tooling, filesystem concepts, service management, networking tools, and system administration philosophy.

That's exactly why it makes a useful addition to a Linux learning environment.

With Incus virtual machines, you can create a FreeBSD VM and start exploring another Unix-like operating system:

Windows 11
    │
    └── WSL2
          │
          └── Debian
                │
                └── Incus
                      │
                      ├── Debian container
                      ├── Ubuntu container
                      ├── Alpine container
                      │
                      └── FreeBSD VM

This gives students an opportunity to ask interesting questions:

How is FreeBSD different from Linux?
How does service management work?
How does networking differ?
What is a BSD jail?
How does a BSD system organize its base system?
What happens when you leave the Linux ecosystem?

The goal isn't to make FreeBSD behave like Linux.

The goal is to learn another Unix-like operating system on its own terms.

Breaking Things Is Part of the Curriculum

One of the best things about a laboratory environment is that you are allowed to make mistakes.

You can experiment with things like:

rm
chmod
chown
systemctl
ip
iptables
nft

You might break a service.

You might misconfigure networking.

You might lock yourself out of something.

That's okay.

You can delete the container and create another one.

incus delete debian01

Then:

incus launch images:debian/13 debian01

You're back to a clean environment.

This is one of the reasons I prefer learning through an isolated lab.

Failure becomes part of the learning process.

Snapshots: Your Save Point

Incus also provides snapshots.

Before making a major change, you can create a snapshot:

incus snapshot create debian01 before-change

After experimenting, you can restore it if necessary.

Conceptually:

Working system
      │
      ▼
   Snapshot
      │
      ▼
Experiment
      │
      ├── Works
      │
      └── Broken
           │
           ▼
        Restore

Think of it as a save point for your laboratory.

This is particularly useful when learning system administration because you're encouraged to experiment instead of being afraid of making mistakes.

What You'll Learn

The laboratory is organized as a progression rather than simply being a collection of commands.

Level 1 — Windows, WSL2 and Debian

Start from the Windows environment.

You'll learn:

Windows Terminal
WSL2
Linux filesystem basics
Debian
shell commands
users and permissions
packages

The objective is to become comfortable inside a Linux terminal.

Level 2 — Introduction to Incus

Once Debian becomes familiar, Incus is introduced.

You'll learn:

installing Incus
creating containers
starting and stopping containers
entering containers
managing images
viewing resources
snapshots

At this point, your single Linux environment becomes a small laboratory.

Level 3 — Networking and Services

Now the machines start communicating.

You'll explore:

Incus bridges
IP addresses
DNS
SSH
HTTP
service ports
network troubleshooting

For example:

             Incus Network
                   │
        ┌──────────┼──────────┐
        │          │          │
     web01       dns01      client01
        │          │          │
       Nginx      DNS        curl

Instead of simply reading about networking, you can build a small network and troubleshoot it yourself.

Level 4 — Programming and FreeBSD

Once the basic system concepts are understood, the laboratory can become a programming environment.

You can start building services with:

PHP
Laravel
Python
Go
shell scripting

And then introduce FreeBSD as a separate virtual machine.

This creates an interesting bridge between:

Programming → Linux → Networking → Systems

Level 5 — Projects

The final stage is intentionally open-ended.

Students can build their own projects.

For example:

a small web server
a DNS server
a monitoring system
a reverse proxy
a multi-container application
a network troubleshooting lab
a basic security monitoring environment
a self-hosted service

At this point, the laboratory stops being a tutorial and becomes a playground.

What Makes This Different from a Typical Linux Tutorial?

A lot of beginner Linux tutorials follow this pattern:

Read
 ↓
Copy command
 ↓
See output
 ↓
Next command

That can teach syntax, but it doesn't necessarily teach systems thinking.

This project tries to follow a different approach:

Concept
   ↓
Build
   ↓
Experiment
   ↓
Break
   ↓
Troubleshoot
   ↓
Understand

For example, instead of simply explaining what DNS is, you can create a small environment where one machine provides DNS and another machine consumes it.

Instead of explaining HTTP theoretically, you can deploy Nginx and connect to it from another container.

Instead of explaining SSH, you can actually log into another machine.

The computer becomes the classroom.

Prerequisites

You don't need an expensive server.

The basic requirements are:

64-bit Windows 11
WSL2 support
Internet connection
Administrator access for initial setup
Approximately 20 GB of available storage

More RAM and CPU will obviously make the laboratory more comfortable, especially when running several environments simultaneously.

You don't need a dedicated server.

You don't need dual-boot.

You don't need a cloud VPS.

Your existing Windows PC can become the lab.

Suggested Learning Path

A possible progression looks like this:

Stage	Topic	Suggested Time
1	Windows, WSL2 & Debian	1–2 hours
2	Linux fundamentals	2–3 hours
3	Incus & first container	1–2 hours
4	Multiple distributions	2–3 hours
5	Networking & services	2–3 hours
6	Programming laboratory	2–3 hours
7	FreeBSD introduction	2–4 hours
8	Student projects	Ongoing

These aren't strict course durations.

The idea is to give learners a direction rather than a deadline.

Where Can You Go After This?

Once you understand the basics, the same laboratory can grow with you.

Linux Administration

Move into:

users and groups
permissions
filesystems
storage
processes
services
system logs
systemd

Networking

Explore:

TCP/IP
DNS
routing
firewalls
reverse proxies
VLAN concepts
network troubleshooting

Web Development

Build environments containing:

Nginx
PHP
Laravel
MariaDB/PostgreSQL
Redis

You can turn Incus into a local development laboratory.

DevOps

Continue with:

Git
CI/CD
automation
configuration management
service deployment
monitoring

Cybersecurity

Once the fundamentals are understood, you can build controlled security labs for:

system hardening
log monitoring
network monitoring
vulnerability testing
incident response exercises

The important part is that these advanced topics are built on top of the fundamentals.

The Bigger Idea

The project is not really about Incus.

It is about creating a place where you can learn by doing.

A Windows laptop can become:

             Your Windows PC
                    │
                  WSL2
                    │
                 Debian
                    │
                  Incus
          ┌─────────┴─────────┐
          │                   │
     Containers               VMs
          │                   │
    ┌─────┼─────┐          FreeBSD
    │     │     │
 Debian Ubuntu Alpine

And from there, the possibilities expand.

You can learn Linux.

Then networking.

Then programming.

Then system administration.

Then DevOps.

Then security.

You don't need to start with a rack full of servers.

You need a computer, some curiosity, and a safe place to experiment.

Final Thoughts

I built the Incus WSL Learning Laboratory around a simple idea:

Don't just read about Linux. Build a Linux environment and use it.

WSL2 makes Linux accessible from Windows.

Incus turns that Linux environment into a laboratory where you can create and destroy systems, experiment with networking, run services, and explore different operating systems.

And because the environment is reproducible, breaking something isn't the end of the world.

It is often the beginning of the lesson.

If you're a student, teacher, developer, or simply someone curious about Linux, this can be a practical starting point for building your own systems laboratory without needing another computer.

Start the Lab

The complete learning material, setup instructions, exercises, and documentation are available here:

GitHub: https://github.com/hardyweb/Incus-WSL-Learning-Laboratory

The project is open source and released under the MIT License.

So, if you're sitting in front of a Windows PC right now, maybe you already have everything you need to start learning Linux.

You don't need big tech to build big things.

You just need a place to experiment, the willingness to break things, and enough curiosity to figure out how to fix them.

Learning Distributed Object Storage with Incus and PGSTY SILO

hardyweb — Fri, 02 Oct 2026 12:42:20 +0000

Aku buat R&D homelab untuk memahami konsep distributed storage, khususnya bagaimana object storage seperti MinIO/SILO menggunakan beberapa storage drives dan nodes untuk menyediakan redundancy dan survive daripada kegagalan storage.

Untuk lab ini, aku gunakan:

Windows + WSL2
Debian
Incus
Debian VM
PGSTY SILO
MinIO Client (mc)
ext4 filesystem

Tujuan utama bukan untuk membina production storage cluster, tetapi untuk memahami apa yang berlaku apabila storage drive atau node gagal.

PGSTY SILO ialah fork daripada MinIO yang mengekalkan compatibility dengan S3 dan MinIO tooling. (github.com)

1. Apa yang aku cuba faham?

Istilah seperti:

distributed storage
object storage
erasure coding
quorum
storage node
storage drive
drive failure
node failure
healing

nampak macam konsep yang berasingan.

Jadi aku nak buat experiment yang mudah:

Kalau satu storage drive mati, adakah object masih boleh dibaca?

Kemudian:

Apa pula yang berlaku kalau satu server/node mati?

Daripada sini kita boleh faham konsep distributed storage melalui experiment sebenar.

2. Kenapa guna Incus?

Aku tidak mempunyai beberapa physical server untuk dijadikan storage nodes.

Jadi Incus digunakan untuk simulate beberapa server.

Topology:

WSL2
 │
 └── Incus
      │
      ├── debian-vm
      │    ├── sdb → storage drive 1
      │    └── sdc → storage drive 2
      │
      └── debian-vm2
           ├── sdb → storage drive 3
           └── sdc → storage drive 4

VM bukan distributed storage itu sendiri.

VM hanya digunakan sebagai simulation of storage nodes.

Distributed storage berlaku pada layer SILO.

3. Kenapa guna VM, bukan container?

Pada awalnya aku cuba menggunakan Incus container. Incus Container menggunakan root block sebagai virtual hdd. cara lain adalah menggunakan real block device seperti:

/dev/sdb
/dev/sdc

ia diperlukan agar dapat simulate storage drive sebenar.

Incus custom block volumes boleh digunakan pada VM dan disk devices VM menyokong hotplug. (linuxcontainers.org)

Jadi architecture akhirnya:

Incus
 │
 ├── debian-vm
 │    ├── /dev/sdb
 │    └── /dev/sdc
 │
 └── debian-vm2
      ├── /dev/sdb
      └── /dev/sdc

4. Membina storage drives

Untuk setiap VM, aku create dua Incus block volumes.

Contohnya:

incus storage volume create default silo1 size=5GiB --type block
incus storage volume create default silo1-extra size=5GiB --type block

Kemudian attach kepada VM:

incus config device add debian-vm silo-disk \
    disk pool=default source=silo1

incus config device add debian-vm silo-disk2 \
    disk pool=default source=silo1-extra

Hasilnya:

debian-vm

sda  30G   OS
sdb   5G   storage
sdc   5G   storage

Perkara yang sama dibuat pada debian-vm2.

Akhirnya:

2 nodes × 2 drives = 4 storage endpoints

5. Format dan mount storage

Setiap block device diformat sebagai ext4:

sudo mkfs.ext4 /dev/sdb
sudo mkfs.ext4 /dev/sdc

Kemudian:

sudo mkdir -p /mnt/export1
sudo mkdir -p /mnt/export2

sudo mount /dev/sdb /mnt/export1
sudo mount /dev/sdc /mnt/export2

Jadi setiap node mempunyai:

/mnt/export1
/mnt/export2

yang masing-masing berada pada storage drive berbeza.

Untuk lab ini, mount dilakukan secara manual. fstab belum digunakan kerana fokusnya adalah experiment storage failure.

6. Network antara nodes

SILO memerlukan nodes berkomunikasi antara satu sama lain.

Incus menyediakan network dan DNS antara instances.

Contohnya:

ping debian-vm2

berjaya dari debian-vm.

Jadi SILO boleh menggunakan hostname:

debian-vm
debian-vm2

sebagai storage endpoints.

7. Setup SILO authentication

Sebelum menjalankan SILO, kita set credential untuk S3/API.

Untuk lab, kita gunakan environment variables:

export SILO_ROOT_USER="siloadmin"
export SILO_ROOT_PASSWORD="change-this-password"

Jangan gunakan password contoh ini untuk production.

Password perlu cukup kuat dan sebaiknya disimpan melalui secret-management mechanism apabila deployment sudah menjadi production.

Kemudian jalankan SILO dengan storage endpoints:

silo server \
    http://debian-vm/mnt/export1 \
    http://debian-vm/mnt/export2 \
    http://debian-vm2/mnt/export1 \
    http://debian-vm2/mnt/export2

Nama environment variable dan authentication mechanism perlu disesuaikan dengan versi SILO yang digunakan. Semak silo server --help atau dokumentasi versi yang dipasang sebelum production deployment.

8. Connect menggunakan `mc`

Selepas SILO berjalan, mc digunakan sebagai S3 client.

Contohnya:

mc alias set silo \
    http://debian-vm:9000 \
    siloadmin \
    change-this-password

Kemudian check:

mc alias list

dan:

mc admin info silo

mc sekarang boleh digunakan untuk:

create bucket
upload object
download object
inspect server
inspect storage status

Contoh:

mc mb silo/test

Kemudian upload:

echo "distributed storage test" > test.txt

mc cp test.txt silo/test/

Dan verify:

mc ls silo/test/

9. Membina distributed SILO pool

SILO dijalankan menggunakan keempat-empat storage endpoints:

silo server \
    http://debian-vm/mnt/export1 \
    http://debian-vm/mnt/export2 \
    http://debian-vm2/mnt/export1 \
    http://debian-vm2/mnt/export2

Sekarang SILO tidak lagi melihat storage sebagai empat directory yang tidak berkaitan.

Ia melihatnya sebagai satu distributed storage pool.

Topology:

                    SILO
                     │
              Distributed Pool
                     │
        ┌────────────┴────────────┐
        │                         │
   debian-vm                 debian-vm2
        │                         │
    ┌───┴───┐                 ┌───┴───┐
    │       │                 │       │
   sdb     sdc               sdb     sdc
    │       │                 │       │
   D1      D2                D3      D4

Dalam experiment ini, mc admin info menunjukkan:

Pool: 1

Drives: 2/2 OK

dan:

Pool | Drives Usage | Erasure stripe size | Erasure sets
1st  | 0.0%         | 4                   | 1

Jadi empat storage endpoints tersebut membentuk:

1 pool
1 erasure set
4 drives

10. Distributed storage bukan sekadar "copy file"

Salah satu perkara penting yang aku mula faham:

4 drives ≠ semestinya 4 copies

Distributed object storage menggunakan mekanisme seperti erasure coding untuk menyediakan redundancy.

Secara konsep:

             Object
                │
          Erasure Coding
                │
       ┌────────┼────────┐
       │        │        │
      D1       D2       D3 ... Dn

Data object dipecahkan kepada beberapa shards dan sebahagian shard digunakan sebagai parity.

SILO menggunakan storage class dengan konfigurasi parity seperti EC:n. Konfigurasi sebenar perlu disemak daripada cluster configuration dan mc admin info, bukan diandaikan hanya berdasarkan jumlah drive. (github.com)

11. Drive failure experiment

Ini experiment yang paling menarik.

Aku mahu simulate:

Satu physical drive rosak tetapi server masih hidup.

Kita tidak shutdown VM.

Contohnya:

debian-vm

sdb → /mnt/export1
sdc → /mnt/export2
              ↑
           FAILURE

Pertama, filesystem di-unmount:

sudo umount /mnt/export2

Tetapi:

umount sahaja bukan bermaksud drive rosak.

Ia cuma unmount filesystem.

Untuk simulate drive benar-benar hilang daripada VM, kita remove Incus disk device:

incus config device remove debian-vm silo-disk2

Kemudian:

incus exec debian-vm -- lsblk

/dev/sdc sudah tidak kelihatan.

Sekarang simulation menjadi:

debian-vm
 │
 ├── sdb  ONLINE
 │
 └── sdc  OFFLINE

tetapi:

debian-vm = RUNNING

Jadi kita sedang menguji drive failure, bukan node failure.

12. Apa yang berlaku kepada object?

Sebelum melakukan failure test, upload satu object:

mc cp test.txt silo/test/

Kemudian pastikan object boleh dibaca:

mc cat silo/test/test.txt

Selepas satu drive ditarik keluar, cuba lagi:

mc cat silo/test/test.txt

Inilah experiment sebenar yang kita mahu lihat.

Jika cluster masih mempunyai quorum yang diperlukan untuk operasi tersebut, object boleh terus diakses walaupun satu storage endpoint offline.

Ini bergantung kepada erasure-set dan storage-class configuration.

13. Memasukkan drive kembali

Selepas experiment selesai, drive boleh attach kembali.

incus config device add debian-vm silo-disk2 \
    disk pool=default source=silo1-extra

Check:

incus exec debian-vm -- lsblk

Kita mahu lihat:

sda
sdb
sdc

Kemudian mount kembali:

incus exec debian-vm -- sudo mount /dev/sdc /mnt/export2

Verify:

incus exec debian-vm -- df -hT /mnt/export2

Kemudian:

mc admin info silo

untuk melihat status drive dan cluster.

Jangan jalankan mkfs pada drive yang sama.

Kita mahu preserve filesystem dan storage data yang sedia ada.

14. Drive failure vs Node failure

Ini satu lagi konsep penting.

Drive failure

debian-vm
 │
 ├── drive 1  ONLINE
 └── drive 2  OFFLINE

Server masih hidup.

SILO masih boleh berkomunikasi dengan node tersebut.

Node failure

Sekarang kita shutdown keseluruhan VM:

debian-vm          OFFLINE
 │
 ├── drive 1
 └── drive 2

debian-vm2         ONLINE
 ├── drive 3
 └── drive 4

Dalam keadaan ini dua storage endpoints hilang serentak.

Jadi:

1 drive failure ≠ 1 node failure

Ini adalah sebab penting kenapa distributed storage perlu dilihat berdasarkan failure domain, bukan sekadar jumlah drives.

15. Current lab topology

Topology semasa:

                     WSL2
                       │
                     Incus
                       │
          ┌────────────┴────────────┐
          │                         │
     debian-vm                 debian-vm2
          │                         │
     ┌────┴────┐               ┌────┴────┐
     │         │               │         │
    sdb       sdc             sdb       sdc
     │         │               │         │
   5 GiB     5 GiB            5 GiB     5 GiB
     │         │               │         │
 export1    export2          export1    export2
     └─────────┴───────────────┴─────────┘
                       │
                      SILO
                       │
                    Pool 1
                 1 erasure set
                    4 drives

Authentication:

S3/API user:
siloadmin

Password:
set melalui SILO environment variable

Client:

mc
 │
 └── silo alias
       │
       └── http://debian-vm:9000

16. Apa yang aku belajar

Lab ini bermula dengan soalan:

"Macam mana distributed storage sebenarnya bekerja?"

Sekarang konsepnya lebih jelas:

Node
 │
 ├── Drive
 ├── Drive
 │
 └── SILO
       │
       ├── Erasure Set
       ├── Erasure Coding
       ├── Quorum
       ├── Failure Detection
       └── Recovery / Healing

Incus pula digunakan untuk simulate infrastructure:

Incus
  ↓
Virtual Machines
  ↓
Block Devices
  ↓
Filesystems
  ↓
SILO
  ↓
Distributed Object Storage
  ↓
S3 Client (mc)

17. Next experiment

Selepas berjaya memahami single-drive failure, experiment seterusnya:

Experiment 1 — Node failure

Shutdown:

debian-vm

Kemudian lihat behaviour cluster.

Experiment 2 — Node recovery

Start semula:

debian-vm

Kemudian observe status drives.

Experiment 3 — Healing

Perhatikan sama ada cluster melakukan recovery/healing selepas storage kembali.

Experiment 4 — Load balancer

Selepas memahami storage layer, baru tambah Nginx sebagai client-facing endpoint:

                 Client
                    │
                  Nginx
                    │
          ┌─────────┴─────────┐
          │                   │
      debian-vm           debian-vm2
          │                   │
       D1   D2              D3   D4
          \                   /
           \────── SILO ─────/

Ini memisahkan dua konsep:

SILO
→ distributed storage / data resilience

Nginx
→ client traffic / endpoint failover

Conclusion

Apa yang menarik tentang lab ini ialah kita tidak hanya menjalankan MinIO/SILO.

Kita cuba merosakkan storage secara sengaja.

Mula dengan:

4 drives
2 nodes
1 erasure set

Kemudian:

pull 1 drive
        ↓
observe
        ↓
attach kembali
        ↓
observe recovery

Daripada experiment ini, konsep distributed storage menjadi lebih mudah difahami kerana kita boleh melihat sendiri hubungan antara:

Node
+
Drive
+
Erasure Coding
+
Erasure Set
+
Quorum
+
Failure
+
Recovery

Seterusnya kita akan cuba matikan satu node, bukan sekadar satu drive.

Itulah beza antara:

"satu disk rosak"

dan

"satu server storage hilang."

Stop AI From Writing Sloppy Laravel Code: My Kilo Code + AGENTS.md Workflow

hardyweb — Fri, 25 Sep 2026 12:41:29 +0000

AI coding assistants are getting very good at generating Laravel code.

Give an AI a feature request and it can probably create:

migrations
models
controllers
Form Requests
Blade views
routes
tests
JavaScript
CSS

The problem is not whether the code works.

The problem is whether the code belongs in the project.

AI can easily generate Laravel code that works today but becomes a maintenance problem tomorrow:

fat controllers
duplicated business logic
unnecessary service/repository layers
$request->all()
N+1 queries
database queries inside Blade
huge inline <style> blocks
huge inline <script> blocks
introducing another frontend framework
ignoring existing components
rewriting parts of the starter kit
unrelated refactoring
debug code left behind
tests that were never actually executed

For me, the solution is not to tell the AI to "write better code".

The better approach is to define the engineering rules and make the AI work inside the existing project architecture.

My current workflow is built around:

Laravel Project
      │
      ├── AGENTS.md
      │      └── Engineering rules
      │
      ├── skills.md
      │      └── Knowledge / examples / procedures
      │
      └── Kilo Code
             └── Implement within those rules

And for longer-running projects, there is another layer that can work alongside them:

DSOM Brain
└── Project state, decisions, continuity and context

I'll come back to that near the end.

1. First Rule: Inspect Before You Code

Before asking an AI coding agent to implement anything, I want it to understand the project that already exists.

This is probably the most important rule in my workflow.

Don't start with:

"Build a user management system."

Start with:

"Inspect the existing project first."

The AI should inspect things such as:

Laravel version
composer.json
existing application structure
authentication system
authorization approach
existing routes
controllers
models
Form Requests
policies
migrations
tests
frontend architecture
starter kit
CSS framework
JavaScript/TypeScript structure
existing components
project conventions

The reason is simple.

The existing project is already an architecture.

If the application already uses Livewire, don't suddenly introduce Inertia and React just because the AI knows how to generate them.

If the application already uses React + Inertia, don't create a random Blade-based application UI.

If the application uses Tailwind, don't introduce Bootstrap.

If the project already has reusable components, don't create another component that does the same thing.

AI should extend the project, not accidentally redesign it.

2. Why AI-Generated Laravel Code Can Become Sloppy

AI optimizes heavily for producing a plausible solution.

That doesn't necessarily mean it optimizes for:

consistency
simplicity
maintainability
project conventions
long-term architecture
minimal changes

For example, imagine this request:

Add an endpoint to update a user's profile.

A simplistic AI implementation might put everything inside the controller:

public function update(Request $request, User $user)
{
    $user->update($request->all());

    // validation
    // authorization
    // business logic
    // logging
    // notifications
    // other operations...

    return redirect()->back();
}

It might work.

But the better Laravel implementation should consider:

Form Request validation
authorization
mass-assignment rules
route model binding
business logic placement
transactions if required
testing
security implications

The goal isn't to make the code more complicated.

The goal is to put each responsibility where it belongs.

This Concept Is Not Kilo Code Specific

Although this workflow was developed and tested with Kilo Code, the underlying idea is not tied to Kilo Code.

The important part is not the tool name. The important part is giving an AI coding agent a clear set of engineering rules, project knowledge, and working context before asking it to write code.

If you use other coding agents such as OpenCode, Codex, or Claude Code, you can apply the same concept.

The exact mechanism may be different:

the instruction file may have a different name,
the location may be different,
the way instructions are loaded may be different,
and each tool may have its own instruction hierarchy or configuration.

But the architecture can remain the same:

                AI Coding Agent
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
    Engineering     Project      Working
       Rules       Knowledge      Context
          │            │            │
          └────────────┼────────────┘
                       ▼
                Laravel Project

For example, the same principles can be adapted to:

Kilo Code → AGENTS.md + skills
OpenCode → project instructions / AGENTS.md
Codex → project instructions / AGENTS.md
Claude Code → project instructions / CLAUDE.md

The exact filenames and supported features should be checked against the documentation for the coding agent you are using.

The key idea

Don't think:

"I need to use Kilo Code because this workflow uses AGENTS.md."

Think instead:

"I need to give my coding agent an engineering contract."

That contract should tell the agent things such as:

how the project is structured,
which Laravel conventions to follow,
how authorization should be handled,
where validation belongs,
how database access should be designed,
what security practices are required,
how tests should be written,
what the agent must inspect before changing code,
and what it should not change unnecessarily.

So if you move from Kilo Code to OpenCode, Codex, or Claude Code, you don't have to throw away the workflow.

You adapt the instruction layer, while keeping the underlying engineering principles.

This makes the workflow tool-agnostic, even though my current implementation and examples are based on Kilo Code.

3. `AGENTS.md` as the Project Engineering Contract

This is where AGENTS.md becomes useful.

Instead of repeating the same instructions every time I ask the AI to implement something, I keep the important engineering rules inside the repository.

For example:

my-laravel-app/
├── AGENTS.md
├── skills.md
├── composer.json
├── artisan
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
├── resources/
├── routes/
├── storage/
└── tests/

The important idea is that AGENTS.md is not documentation for humans only.

It becomes a working contract between the project and the AI coding agent.

For example:

# Laravel Engineering Rules

- Follow the existing project architecture.
- Inspect existing code before implementation.
- Keep controllers thin.
- Use Form Requests for validation.
- Use policies for authorization.
- Prefer Eloquent over unnecessary repository abstractions.
- Do not put business logic in Blade.
- Avoid N+1 queries.
- Use migrations for database changes.
- Write tests for application behaviour.
- Do not introduce another frontend framework without a clear requirement.
- Reuse existing components.
- Do not add unnecessary abstractions.
- Do not refactor unrelated code.

Now the AI has something concrete to follow.

4. Follow the Existing Laravel Starter Kit

Laravel applications don't all have the same frontend architecture.

A project may use:

Livewire
React + Inertia
Vue + Inertia
Blade
Tailwind
another existing frontend setup

Laravel's current starter kits also provide different application stacks, so the starter kit already present in a project should be treated as part of that project's architecture.

My rule is:

Inspect the starter kit before creating new UI.

If the project already has a component system, use it.

If the project already has layouts, use them.

If the project already has navigation components, don't create another navigation implementation.

The starter kit is a starting architecture, not something the AI should casually replace.

5. Don't Introduce Another Frontend Stack

This is one of the easiest ways for AI-generated code to become messy.

Imagine an existing Laravel project using:

Blade + Alpine + Tailwind

Then an AI decides to add:

React + Vite + another component library

Now the project has two frontend architectures.

That might be justified in some applications.

But it should never happen simply because the AI generated a React solution faster.

The rule should be:

Follow the frontend architecture already used by the project unless there is an explicit reason to change it.

6. Reuse Existing Components

Before creating a new component, look for an existing one.

For example:

resources/views/components/

might already contain:

button.blade.php
input.blade.php
modal.blade.php
alert.blade.php
table.blade.php

If the application already has a button component, don't generate another button implementation.

The AI should inspect first.

This simple rule prevents a lot of duplication.

7. Don't Put Raw CSS Inside Blade

Another common AI-generated pattern is:

<style>
    .some-big-component {
        ...
    }

    .another-component {
        ...
    }

    /* 200 more lines */
</style>

This may work, but it can quickly become difficult to maintain.

If the project uses Tailwind, use Tailwind.

If the project uses Bootstrap, use Bootstrap.

If custom CSS is genuinely required, put it into the project's existing CSS structure.

For example:

resources/
└── css/
    ├── app.css
    └── components/
        └── editor.css

The exact structure depends on the project.

The important rule is:

Follow the project's existing CSS architecture instead of dumping large amounts of CSS into Blade.

The same principle applies to JavaScript.

Don't create a huge:

<script>
    // 300 lines of application logic
</script>

inside a Blade view if the project already has a proper JavaScript/TypeScript structure.

8. My Basic Laravel Architecture Rules

These are the rules I want an AI coding agent to understand before it starts changing my Laravel application.

Thin Controllers

Controllers should coordinate the request.

They shouldn't become the entire application.

Bad:

public function store(Request $request)
{
    // validation

    // authorization

    // database queries

    // business rules

    // notifications

    // logging

    // calculations

    // 100 more lines
}

Better:

public function store(StoreOrderRequest $request)
{
    $this->authorize('create', Order::class);

    $order = $this->orderService->create(
        $request->validated()
    );

    return redirect()->route('orders.show', $order);
}

The exact architecture depends on the project.

The important part is keeping responsibilities separated.

9. Form Requests Instead of `$request->all()`

I don't want AI-generated Laravel code to casually do this:

$data = $request->all();

Especially when the data is going into a model.

Use a Form Request when validation and authorization belong there:

$data = $request->validated();

Or:

$data = $request->safe()->only([
    'name',
    'email',
]);

This makes the input boundary explicit.

It also reduces the chance of accidentally passing unexpected fields into application logic.

10. Authorization Is Not Authentication

Another common mistake is confusing:

Who are you?

with:

Are you allowed to do this?

Authentication identifies the user.

Authorization determines whether that user can perform the operation.

Laravel provides policies and gates for this.

For example:

$this->authorize('update', $post);

The AI should not assume that:

auth()->check()

means the user is allowed to modify the resource.

11. Eloquent First

Laravel already provides a powerful ORM.

I don't want an AI to create:

Repository
    ↓
Interface
    ↓
Repository Implementation
    ↓
Manager
    ↓
Service
    ↓
Model

for a simple CRUD operation.

If Eloquent is enough:

$user = User::findOrFail($id);

use Eloquent.

Repositories can be useful in the right context.

But abstraction should solve a problem, not create one.

12. Check for N+1 Queries

AI-generated Laravel code can easily create N+1 queries.

For example:

$posts = Post::all();

foreach ($posts as $post) {
    echo $post->author->name;
}

The correct implementation may need:

$posts = Post::with('author')->get();

The AI should inspect relationships and query behaviour rather than assuming that syntactically valid Eloquent code is automatically efficient.

13. Don't Put Business Logic in Blade

Blade should primarily handle presentation.

I don't want this:

@php
    $orders = Order::where('user_id', auth()->id())->get();

    // business logic
    // calculations
    // database operations
@endphp

The view should receive the data it needs.

For example:

$orders = $user->orders()->latest()->get();

return view('orders.index', compact('orders'));

Then Blade renders it.

14. Services and Actions Only When Needed

I'm not against service classes.

I'm against creating them automatically.

A service or action can make sense when there is:

complex business logic
reusable application behaviour
multiple steps
transaction boundaries
difficult-to-test logic
meaningful separation of responsibilities

But this:

CreateUserService

for a three-line CRUD operation may simply add another layer.

The rule is:

Introduce abstractions because the problem requires them, not because AI likes generating classes.

15. Database Changes Through Migrations

Don't manually modify production database structures.

Use migrations.

For example:

php artisan make:migration add_status_to_orders_table

Then define the change.

Database design should also consider:

foreign keys
indexes
unique constraints
nullable columns
data types
relationships

AI should inspect the existing schema before creating another migration.

16. Transactions When Atomicity Matters

If an operation modifies several related records and they must succeed or fail together, consider a transaction.

For example:

DB::transaction(function () {
    // create order

    // create order items

    // update inventory
});

But again, don't wrap every single database query inside a transaction just because the AI knows the API exists.

Use transactions when atomicity matters.

17. Security Is Part of the Coding Standard

Security shouldn't be an afterthought.

For Laravel development, I want the AI to consider:

authentication
authorization
validation
mass assignment
CSRF
XSS
SQL injection
file uploads
path traversal
rate limiting
secrets
logging
access control

For example:

Log::info('User updated profile', [
    'user_id' => $user->id,
]);

is useful.

But:

Log::info($request->all());

could expose sensitive information.

The AI should understand that logging itself can become a security problem.

18. Testing Is Part of the Workflow

I don't want AI to say:

Tests should be added later.

If a feature changes application behaviour, testing should be part of the implementation.

For example:

Feature
├── implementation
├── validation
├── authorization
└── tests

Feature tests are useful for application behaviour.

Unit tests are useful for isolated logic.

And one important rule:

Never claim that tests passed unless they were actually executed.

An AI saying:

All tests pass.

without running them is not useful.

19. The "No Sloppy AI Code" Checklist

Before accepting AI-generated code, I can ask:

- Did you inspect the existing architecture first?
- Did you follow the existing starter kit?
- Did you reuse existing components?
- Did you follow the existing CSS/JS structure?
- Are controllers still thin?
- Is validation handled properly?
- Is authorization handled separately?
- Did you use Eloquent before introducing abstractions?
- Did you check for N+1 queries?
- Is business logic outside Blade?
- Are services/actions actually justified?
- Are database changes done through migrations?
- Are transactions used only where needed?
- Did you consider security?
- Did you add appropriate tests?
- Did you avoid unrelated refactoring?
- Did you remove debug code?

This checklist is often more valuable than telling an AI:

"Write clean code."

Because "clean" is subjective.

Rules are more explicit.

20. `skills.md` Is Different From `AGENTS.md`

I also like separating rules from knowledge.

AGENTS.md answers:

How should the AI work on this project?

While skills.md can contain:

useful procedures
project-specific knowledge
examples
commands
troubleshooting
reusable implementation patterns

For example:

AGENTS.md
└── Rules

skills.md
└── Knowledge / procedures / examples

This keeps the main engineering contract focused.

The AI doesn't need every piece of project knowledge to become a hard rule.

21. Why I Use Kilo Code

My current workflow uses Kilo Code as the coding agent.

I don't need to run four different coding agents for every Laravel project.

The important part isn't how many AI tools are involved.

The important part is whether the AI is working inside a clear engineering environment.

My basic setup is:

Kilo Code
    │
    ├── Inspect project
    │
    ├── Read AGENTS.md
    │
    ├── Load relevant skills
    │
    ├── Plan
    │
    ├── Implement
    │
    ├── Test
    │
    └── Review changes

Another developer may prefer another coding agent.

That's fine.

The principles remain the same.

22. Windows, Linux and WSL

My development environment is not necessarily a traditional Linux workstation.

I work across:

Windows
   │
   └── WSL2
          │
          ├── Linux
          ├── Laravel
          ├── Git
          └── Kilo Code

This is another reason why project-local instructions are useful.

The AI shouldn't assume a generic environment.

If the project has specific commands, paths, services or development procedures, document them.

23. Don't Put Secrets in `AGENTS.md`

AGENTS.md belongs in the project.

That means it may eventually be committed to Git.

Therefore:

Don't put secrets inside it.

Never store:

API keys
passwords
tokens
private credentials
production secrets

Instead document the expected configuration:

MAIL_USERNAME=<configured through environment>
MAIL_PASSWORD=<configured through environment>

The actual secret belongs in the appropriate secret/configuration mechanism.

24. A Practical Project Structure

A simple Laravel project can look like:

my-laravel-app/
├── AGENTS.md
├── skills.md
├── composer.json
├── artisan
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
├── resources/
├── routes/
├── storage/
└── tests/

The important part isn't the number of files.

It is that the project contains a small, visible place where the AI can learn:

Rules
Knowledge
Code
Tests

25. A Real Example: My Kilo Code Configuration

The examples above describe the workflow conceptually.

If you want to see how I actually structure these files in a working repository, I keep a practical example here:

GitHub:
https://github.com/hardyweb/kilo

The repository contains the project-level instructions and skills I use with Kilo Code.

The important part is not to copy the repository blindly.

Instead, look at how the responsibilities are separated:

kilo/
├── AGENTS.md
│
└── skills/
    └── laravel/
        └── SKILL.md

The idea is simple:

AGENTS.md
    │
    └── Project-wide engineering rules
             │
             ▼
skills/
    │
    └── Domain-specific knowledge
             │
             ▼
       Coding Agent
             │
             ▼
       Laravel Project

For example, AGENTS.md can define rules such as:

inspect before changing code
follow the existing architecture
keep controllers thin
use Form Requests for validation
use policies for authorization
avoid unnecessary abstractions
reuse existing components
test behaviour
don't claim tests passed unless they were actually run

The Laravel skill can then contain more detailed Laravel-specific knowledge, procedures, conventions and implementation guidance.

This separation is useful because not everything needs to become a global rule.

26. What If You Want More Than Coding Rules?

This is where another interesting layer comes in.

AGENTS.md is useful for defining how the AI should work.

skills.md is useful for giving the AI knowledge, procedures and examples.

But long-running projects can have another problem:

What does the AI need to remember about the project over time?

Architecture decisions.

Previous work.

Current project state.

Session handovers.

Decisions that were already made.

Things that should not be repeated.

This is a different problem from coding rules.

One project I came across is Deep State of Mind (DSOM), which approaches this problem as a persistent AI context and governance layer. Its DSOM architecture includes persistent project state, decision/context artifacts, session continuity and a Git-oriented workflow.

Conceptually, I see the layers like this:

                    AI Coding Workflow
                           │
          ┌────────────────┼────────────────┐
          │                │                │
          ▼                ▼                ▼
     AGENTS.md         skills.md        DSOM Brain
          │                │                │
       Rules          Knowledge       Project State
     & standards       & examples     & continuity
          │                │                │
          └────────────────┼────────────────┘
                           │
                           ▼
                       Kilo Code
                           │
                           ▼
                    Laravel Project

The distinction is important:

AGENTS.md
"What rules should the AI follow?"

skills.md
"What knowledge/procedures can help the AI?"

DSOM Brain
"What does the AI need to remember about this project?"

I don't see DSOM Brain as something that replaces AGENTS.md or skills.md.

Instead, it can run alongside them.

For a small Laravel project, AGENTS.md and a small set of skills may already be enough.

For a long-running project, however, persistent project state and context can become useful.

That's where DSOM Brain becomes interesting.

I'm keeping the DSOM Brain implementation out of this article because it deserves its own discussion.

I'll cover that separately in another article.

For reference:

Deep State of Mind (DSOM) For My AI

27. The Real Goal

The goal isn't to make AI write more code.

The goal is to make AI work inside an engineering system.

My current thinking is:

AGENTS.md
    │
    └── Engineering rules

skills.md
    │
    └── Knowledge and procedures

DSOM Brain
    │
    └── Persistent project context

Kilo Code
    │
    └── Implementation

Git
    │
    └── History and audit trail

Laravel
    │
    └── The actual application

This changes the relationship with an AI coding agent.

Instead of:

"AI, build this feature."

The workflow becomes:

"Here is the project. Inspect it first. Here are the engineering rules. Here are the relevant skills. Here is the project context. Now implement the feature within the existing architecture."

That is a much more useful way for me to think about AI-assisted Laravel development.

Don't try to teach the AI everything. Define the rules that matter, inspect the existing project first, keep those rules close to the project, and make the AI work within the architecture that already exists.

Testing Laravel 13 dengan PHP 8.5 dan PHP 8.6 Menggunakan Incus

hardyweb — Mon, 21 Sep 2026 20:43:44 +0000

Dalam proses pembangunan sistem yang mengikuti kitaran SDLC, seperti KRISA, pengujian bukan hanya dilakukan pada penghujung pembangunan. Pengujian perlu dilaksanakan secara berterusan bagi memastikan sistem yang dibangunkan kekal serasi dengan perubahan pada persekitaran teknikalnya.

Salah satu perkara yang boleh diuji ialah keserasian antara interpreter atau runtime yang digunakan dengan software framework yang dibangunkan. Dalam konteks aplikasi Laravel, contohnya, kita boleh menguji aplikasi yang sama menggunakan versi PHP yang lebih baharu untuk melihat sama ada terdapat perubahan pada dependency, extension, API atau tingkah laku runtime yang memberi kesan kepada sistem.

Pendekatan ini membolehkan kita mengesan isu keserasian lebih awal dalam kitaran pembangunan, bukannya hanya selepas sesuatu versi PHP mula digunakan di production.

Dalam nota ini, Incus digunakan untuk menyediakan environment PHP yang berbeza supaya aplikasi Laravel yang sama boleh diuji secara berulang terhadap beberapa versi PHP.

WSL
└── Incus
    ├── laravel13-php85
    │   └── PHP 8.5
    │
    └── laravel13-php86
        └── PHP 8.6

Tujuannya bukan untuk menjalankan dua project yang berbeza, tetapi untuk menguji codebase dan dependency yang sama pada runtime PHP yang berbeza.

Prinsip penting: gunakan `composer.lock` yang sama

Untuk compatibility testing, kita mahu kedua-dua environment menggunakan dependency yang sama.

Jadi jangan terus buat:

composer update

dalam setiap container.

Sebaliknya gunakan:

composer install

composer install akan menggunakan composer.lock yang sedia ada.

Contohnya:

                composer.lock
                     │
             ┌───────┴───────┐
             ▼               ▼
          PHP 8.5          PHP 8.6
             │               │
          test #1          test #2

Dengan cara ini, perbezaan yang kita lihat lebih tertumpu kepada PHP runtime, bukan kerana Composer memilih versi dependency yang berbeza.

Flow 1 — Bind Mount

Ini ialah flow yang paling mudah untuk development dan testing harian.

Source code kekal di WSL:

/home/hardy/projects/laravel13

Kemudian directory tersebut di-mount ke kedua-dua container.

Contoh:

incus config device add laravel13-php85 app disk \
    source=/home/hardy/projects/laravel13 \
    path=/var/www/html

Dan:

incus config device add laravel13-php86 app disk \
    source=/home/hardy/projects/laravel13 \
    path=/var/www/html

Sekarang kedua-dua container melihat source code yang sama.

WSL
└── projects/
    └── laravel13/
        ├── app/
        ├── config/
        ├── routes/
        ├── composer.json
        └── composer.lock
             │
             ├──────────────► PHP 8.5 container
             │
             └──────────────► PHP 8.6 container

Install dependency

Masuk ke container PHP 8.5:

incus exec laravel13-php85 -- bash

Kemudian:

cd /var/www/html

php -v
composer install
composer check-platform-reqs

Run test:

php artisan test

Kemudian ulangi pada PHP 8.6:

incus exec laravel13-php86 -- bash

cd /var/www/html

php -v
composer install
composer check-platform-reqs
php artisan test

Perkara yang perlu diperhatikan dengan bind mount

Bind mount sangat convenient, tetapi filesystem host dan container menjadi agak coupled.

Antara masalah yang mungkin muncul ialah UID/GID dan permission.

Dalam sesetengah setup Incus, kita mungkin menggunakan:

shift=true

pada disk device.

Contohnya:

incus config device set laravel13-php85 app shift=true

Tetapi ini bukan sesuatu yang perlu dijadikan default untuk flow kita.

shift=true boleh mempengaruhi bagaimana ownership file dipersembahkan antara host dan container. Untuk development workflow, kita lebih baik kekalkan setup mount yang simple dan hanya tackle UID/GID apabila memang diperlukan.

Jika selesai testing dan sebelum kembali kepada workflow biasa, kita boleh set:

incus config device set laravel13-php85 app shift=false
incus config device set laravel13-php86 app shift=false

Flow 2 — Rsync atau Git

Untuk environment yang lebih clean, kita boleh elakkan bind mount.

Sebaliknya, source code disalin ke dalam filesystem container.

Contohnya menggunakan rsync:

WSL source
    │
    │ rsync
    ▼
Incus container
    │
    └── /var/www/html

Contoh:

rsync -a --delete \
    --exclude vendor \
    --exclude node_modules \
    ./ /path/to/container/

Atau kita boleh gunakan Git:

git clone <repository> /var/www/html

Kemudian:

cd /var/www/html
composer install

Penting: `composer.lock` masih digunakan

Rsync atau Git tidak bermaksud Composer akan ignore composer.lock.

Selagi file ini ada:

composer.json
composer.lock

dan kita menjalankan:

composer install

Composer akan menggunakan composer.lock.

Apa yang fresh ialah directory:

vendor/

Contohnya:

Source repository
│
├── composer.json
├── composer.lock
├── app/
├── routes/
└── ...
        │
        │ rsync / git
        ▼
Container
│
├── composer.json
├── composer.lock
├── app/
├── routes/
└── ...
        │
        │ composer install
        ▼
    vendor/

Jadi kita masih mendapat dependency versions yang sama.

Kenapa Flow 2 lebih clean?

Dengan Git atau rsync, container mempunyai filesystem sendiri.

Contohnya:

laravel13-php85
└── /var/www/html
    ├── app
    ├── config
    ├── composer.json
    ├── composer.lock
    └── vendor

laravel13-php86
└── /var/www/html
    ├── app
    ├── config
    ├── composer.json
    ├── composer.lock
    └── vendor

Setiap environment mempunyai vendor/ sendiri.

Ini lebih dekat dengan situasi:

CI/CD
staging
deployment
production build
compatibility testing yang isolated

Cuma workflow menjadi sedikit lebih lambat kerana setiap perubahan source perlu di-sync atau checkout semula.

Mana satu digunakan?

Untuk kerja harian, saya akan gunakan Flow 1 — bind mount.

Sebabnya mudah:

Edit code
   ↓
WSL
   ↓
Container nampak perubahan terus
   ↓
Run test

Ia sangat sesuai untuk exploratory testing.

Manakala Flow 2 lebih sesuai apabila kita mahu memastikan environment betul-betul isolated:

Git/Rsync
   ↓
Container
   ↓
composer install
   ↓
Test

Checklist compatibility test

Untuk setiap versi PHP:

php -v

Kemudian:

composer install

Semak platform requirements:

composer check-platform-reqs

Run Laravel test:

php artisan test

Jika mahu periksa dependency yang menghalang PHP tertentu:

composer why-not php 8.6

Untuk melihat apa yang akan berubah tanpa benar-benar update:

composer update --dry-run

Tetapi command ini digunakan untuk mengkaji dependency resolution, bukan baseline compatibility test.

Contoh workflow

Katakan kita sedang berada pada PHP 8.5.

incus exec laravel13-php85 -- bash

cd /var/www/html

php -v
composer install
composer check-platform-reqs
php artisan test

Kemudian test PHP 8.6:

incus exec laravel13-php86 -- bash

cd /var/www/html

php -v
composer install
composer check-platform-reqs
php artisan test

Hasilnya boleh dibandingkan:

Laravel 13
│
├── PHP 8.5
│   ├── composer install    ✓
│   ├── platform reqs       ✓
│   └── tests               ✓
│
└── PHP 8.6
    ├── composer install    ✓
    ├── platform reqs       ✓
    └── tests               ✓

Jika PHP 8.6 gagal, kita boleh isolate puncanya:

PHP runtime?
    │
    ├── Extension missing?
    │
    ├── Platform requirement?
    │
    ├── Composer dependency?
    │
    └── Application/test failure?

Contohnya, error:

Class "Normalizer" not found

boleh menunjukkan PHP intl extension belum tersedia.

Check:

php -m | grep -i intl

Dan:

php -r 'var_dump(class_exists("Normalizer"));'

Kesimpulan

Incus sesuai digunakan untuk membuat compatibility matrix yang kecil tanpa perlu Docker atau VM penuh.

Untuk development/testing cepat:

Bind mount
    ↓
PHP 8.5 / PHP 8.6
    ↓
composer install
    ↓
composer check-platform-reqs
    ↓
php artisan test

Untuk environment yang lebih isolated:

Git / rsync
    ↓
Container filesystem
    ↓
composer install
    ↓
php artisan test

Perkara paling penting ialah jangan ubah dependency set ketika membandingkan PHP versions.

Gunakan:

composer install

dengan composer.lock yang sama.

Dengan itu kita boleh membezakan dengan lebih jelas sama ada sesuatu masalah datang daripada PHP version, PHP extension, dependency, atau memang daripada application code itu sendiri.

Incus Lab: Belajar Rangkaian Dengan Cara Mencuba

hardyweb — Fri, 18 Sep 2026 13:30:59 +0000

Belajar tentang rangkaian kadang-kadang agak sukar apabila semuanya hanya diterangkan melalui rajah, nota dan teori.

Apa sebenarnya berlaku apabila kita melakukan ping?

Kenapa satu port boleh dibuka tetapi port yang lain tidak?

Bagaimana nmap mengenal pasti perkhidmatan yang sedang berjalan? Dan apabila kita menggunakan dig, dari mana sebenarnya maklumat DNS itu datang?

Incus Lab dibangunkan sebagai satu ruang kecil untuk pelajar mencuba dan melihat sendiri perkara-perkara tersebut.

Incus Lab menggunakan Incus, iaitu platform untuk menjalankan system container dan virtual machine. Dalam projek ini, beberapa container Linux digunakan sebagai persekitaran latihan rangkaian.

Konsepnya mudah.

Pelajar tidak perlu membayangkan bahawa terdapat sebuah server di sebelah sana atau sebuah network di belakang sesuatu rajah. Sebaliknya, mereka boleh melihat dan berinteraksi dengan persekitaran tersebut secara langsung.

Dalam Incus Lab terdapat container seperti lab-scanner dan lab-target. Daripada persekitaran ini, pelajar boleh mencuba beberapa perkara asas seperti:

ping dan pemeriksaan connectivity
ip addr, ip route dan ip neigh
nmap untuk melihat port dan service
ss, nc dan curl
dig dan nslookup untuk memahami DNS
kemudian berkembang kepada traceroute, packet inspection dan troubleshooting

Setiap percubaan boleh menjadi satu soalan kecil.

"Apa yang berlaku kalau port ini ditutup?"

"Kenapa ping berjaya tetapi sambungan ke port tertentu gagal?"

"Apa yang sebenarnya berlaku apabila kita membuat DNS lookup?"

Daripada situ, pelajar boleh melihat hubungan antara arahan yang mereka jalankan dengan keadaan sebenar dalam network.

Satu lagi perkara yang cuba diketengahkan ialah command yang sebenar. Incus Lab bukan sekadar memaparkan keputusan akhir. Command yang dijalankan turut boleh dilihat melalui command log, supaya pelajar boleh menghubungkan apa yang mereka klik pada antaramuka dengan arahan Linux yang berlaku di belakangnya.

Pendekatan ini diharapkan dapat menjadikan pembelajaran lebih dekat dengan pengalaman sebenar seorang system atau network engineer.

Tidak perlu bermula dengan memahami semuanya.

Cuba satu command.

Lihat hasilnya.

Buat perubahan kecil.

Cuba lagi.

Kemudian mula bertanya "kenapa?"

Itulah idea ringkas di sebalik Incus Lab — menyediakan ruang yang selamat untuk belajar network melalui percubaan, pemerhatian dan sedikit rasa ingin tahu.

Projek ini masih berkembang. Beberapa topik seperti routing, packet inspection dan troubleshooting dirancang untuk ditambah secara berperingkat.

Jika anda seorang pelajar IT dan ingin mencuba, projek ini boleh dilihat di GitHub:

github.com/hardyweb/incus-lab

Mungkin daripada satu ping yang ringkas, kita mula nampak bahawa network sebenarnya mempunyai banyak cerita di sebaliknya.

Nginx Load Balancing with DNS-Based Service Discovery on Incus

hardyweb — Sun, 30 Aug 2026 06:31:30 +0000

Nginx Load Balancing with DNS-Based Service Discovery on Incus

Hari ini saya buat satu practical lab untuk memahami Nginx Load Balancing, DNS-based Service Discovery, dan operational logging dalam persekitaran self-hosted menggunakan Incus.

Lab ini bermula dengan architecture yang simple:

Client
   │
   ▼
Nginx LB
   │
   ├──► web01
   └──► web02

Kemudian saya tambah satu DNS server supaya backend tidak perlu bergantung sepenuhnya kepada hard-coded IP address.

1. Architecture

Final architecture:

                         DNS
                    dns / dnsmasq
                    10.107.109.18
                         ▲
                         │
                  DNS lookup:
                   web.incus
                         │
                         │
                    Nginx LB
                   10.107.109.69
                         │
                  Load Balancing
              ┌──────────┼──────────┐
              ▼          ▼          ▼
            web01      web02      web03
            .100        .253        .xxx

Ada dua jenis communication flow dalam architecture ini.

DNS resolution

Nginx LB ──────► DNS
                  │
                  └── web.incus
                       ↓
                  .100, .253, .xxx

DNS hanya digunakan untuk mengetahui IP address backend.

HTTP traffic

Client
  │
  ▼
Nginx LB
  │
  ├────► web01
  ├────► web02
  └────► web03

DNS tidak membawa HTTP traffic.

DNS hanya menjawab:

Where is web.incus?

Nginx kemudian menggunakan IP yang diperoleh daripada DNS untuk melakukan load balancing.

2. Static / Hard-Coded Upstream

Cara paling mudah untuk configure Nginx Load Balancer ialah dengan meletakkan IP backend secara terus.

Contoh:

upstream backend {
    server 10.107.109.100;
    server 10.107.109.253;
}

Architecture:

Nginx LB
   │
   ├──► 10.107.109.100
   │
   └──► 10.107.109.253

Kelebihan

Simple
Mudah difahami
Predictable
Sesuai untuk environment kecil
Tidak memerlukan DNS service discovery

Kekurangan

Kalau tambah web03:

web01
web02
web03

Nginx configuration perlu diubah:

upstream backend {
    server 10.107.109.100;
    server 10.107.109.253;
    server 10.107.109.xxx;
}

Kemudian configuration perlu divalidasi dan biasanya Nginx perlu di-reload.

3. DNS-Based Service Discovery

Pendekatan kedua ialah menggunakan hostname sebagai service identity.

Contohnya:

web.incus

DNS:

web.incus
 ├── 10.107.109.100
 ├── 10.107.109.253
 └── 10.107.109.xxx

Nginx tidak perlu mengetahui backend IP secara hard-coded.

Contoh:

resolver 10.107.109.18 valid=5s;

upstream backend {
    zone backend 64k;
    server web.incus resolve;
}

Konsepnya:

             DNS
              │
              │ web.incus
              ▼
         ┌─────────────┐
         │  Nginx LB   │
         └──────┬──────┘
                │
       ┌────────┼────────┐
       ▼        ▼        ▼
     web01    web02    web03

4. Why Use DNS?

DNS memberikan abstraction layer antara Load Balancer dan backend server.

Tanpa DNS:

Nginx
  │
  ├── 10.107.109.100
  ├── 10.107.109.253
  └── 10.107.109.xxx

Dengan DNS:

Nginx
  │
  └── web.incus
         │
         ├── .100
         ├── .253
         └── .xxx

Ini bermaksud service identity dipisahkan daripada server identity.

Contohnya, kalau web01 mendapat IP baru:

web.incus
    ↓
10.107.109.200

Nginx tidak perlu mempunyai IP tersebut secara hard-coded.

DNS menjadi source of information mengenai lokasi service.

5. dnsmasq

Dalam lab ini saya menggunakan dnsmasq sebagai DNS service.

DNS server:

10.107.109.18

Nginx LB menggunakan DNS tersebut:

resolver 10.107.109.18 valid=5s;

Test DNS:

dig @10.107.109.18 web.incus

Contoh result:

web.incus.    0    IN    A    10.107.109.100
web.incus.    0    IN    A    10.107.109.253

Apabila web03 ditambah:

web.incus.    0    IN    A    10.107.109.100
web.incus.    0    IN    A    10.107.109.253
web.incus.    0    IN    A    10.107.109.xxx

6. Dynamic DNS Resolution in Nginx

Bahagian penting dalam configuration ialah:

resolver 10.107.109.18 valid=5s;

dan:

server web.incus resolve;

resolver memberitahu Nginx DNS server yang perlu digunakan.

valid=5s menentukan tempoh DNS result dianggap valid oleh Nginx.

resolve membolehkan Nginx resolve hostname backend secara dynamic.

Konsep:

DNS changes
     │
     ▼
web.incus
     │
     ▼
Nginx re-resolves
     │
     ▼
Backend pool updated

Ini lebih flexible berbanding hard-coded IP.

7. Adding a New Backend

Salah satu test penting ialah menambah web03.

Sebelum:

web.incus
 ├── web01
 └── web02

Selepas:

web.incus
 ├── web01
 ├── web02
 └── web03

Yang menarik ialah Nginx configuration tidak perlu ditukar untuk menambah backend baru.

DNS yang berubah.

Kemudian Nginx akan mendapatkan DNS information yang baru berdasarkan konfigurasi resolver.

Ini menunjukkan salah satu kelebihan utama DNS-based service discovery.

8. Important Lesson: DNS Discovery Is Not Health Checking

Satu perkara yang saya belajar ialah:

DNS Service Discovery ≠ Health Checking

DNS memberitahu:

web.incus
    ↓
IP addresses

Tetapi DNS tidak semestinya tahu sama ada HTTP service pada IP tersebut sedang berfungsi.

Contohnya:

web.incus
 ├── web01 ✅
 ├── web02 ❌
 └── web03 ✅

DNS mungkin masih return:

.100
.253
.xxx

walaupun web02 tidak boleh menerima HTTP connection.

Oleh itu, production architecture mungkin memerlukan additional health-checking atau failure-handling mechanism.

9. Load Balancing vs High Availability

Saya juga belajar bahawa Load Balancing dan High Availability bukan perkara yang sama.

Load Balancing

Tujuan:

Client
  │
  ▼
Nginx LB
 ├──► web01
 ├──► web02
 └──► web03

Ia mengagihkan traffic.

High Availability

Tujuan:

           LB / HA
          /       \
       LB01      LB02

Ia memastikan service masih tersedia jika salah satu infrastructure component gagal.

Contohnya, Keepalived boleh digunakan untuk menyediakan virtual IP dan failover antara Load Balancer.

Jadi:

Load Balancing
    ≠
High Availability

Tetapi kedua-duanya boleh digunakan bersama.

10. Nginx Operational Logging

Selepas Load Balancing berfungsi, saya tambah logging untuk melihat backend mana yang menerima request.

Contoh log format:

log_format lb '$remote_addr - $host [$time_local] '
              '"$request" $status $body_bytes_sent '
              'upstream=$upstream_addr '
              'upstream_status=$upstream_status '
              'request_time=$request_time '
              'upstream_response_time=$upstream_response_time';

Kemudian:

access_log /var/log/nginx/lb_access.log lb;

Log boleh mengandungi:

upstream=10.107.109.100:80

atau:

upstream=10.107.109.253:80

atau:

upstream=10.107.109.xxx:80

Ini memberikan visibility kepada Load Balancer behaviour.

11. Testing

Test DNS

dig @10.107.109.18 web.incus

Test backend

curl --noproxy '*' http://10.107.109.100/
curl --noproxy '*' http://10.107.109.253/
curl --noproxy '*' http://10.107.109.xxx/

Test Nginx configuration

nginx -t

Inspect effective configuration

nginx -T

Test Load Balancer

curl --noproxy '*' http://10.107.109.69/

Watch Load Balancer logs

tail -f /var/log/nginx/lb_access.log

12. Troubleshooting Lesson

Satu masalah yang berlaku dalam lab ialah default Nginx configuration masih aktif.

Contohnya:

/etc/nginx/conf.d/default.conf

Configuration tersebut menyebabkan Nginx default welcome page dipaparkan.

Walaupun Load Balancer configuration telah dibuat dengan betul, request masih boleh masuk ke default server.

Penyelesaian ialah memastikan hanya configuration yang diperlukan digunakan.

Ini mengajar satu perkara penting:

Jangan hanya melihat configuration file yang kita edit. Periksa effective configuration yang sebenarnya digunakan oleh Nginx.

Command yang berguna:

nginx -T

Kemudian:

nginx -t

sebelum reload.

13. Configuration Validation Workflow

Workflow yang saya gunakan:

Edit Configuration
       │
       ▼
    nginx -t
       │
       ▼
   Configuration OK?
      /       \
    NO         YES
    │           │
    ▼           ▼
 Fix config   Reload
                │
                ▼
             Test
                │
                ▼
              Logs
                │
                ▼
            Verify

Ini lebih baik daripada terus restart service setiap kali membuat perubahan.

14. Security Perspective

Walaupun lab ini fokus kepada Load Balancing, terdapat beberapa security principles yang boleh dipelajari.

Configuration Management

Configuration perlu:

dikenal pasti
diubah secara terkawal
divalidasi
diuji
didokumentasikan

Network Security

Perlu memahami:

Client
  ↓
Load Balancer
  ↓
Backend network

dan service mana yang boleh berkomunikasi antara satu sama lain.

Logging

Load Balancer logs membantu:

troubleshooting
monitoring
incident investigation
performance analysis
verification

Availability

Multiple backend servers boleh mengurangkan dependency kepada single server.

15. ISO/IEC 27001 Perspective

Lab ini bukan implementation penuh ISO/IEC 27001.

Sebaliknya, ISO/IEC 27001 digunakan sebagai reference framework untuk memahami bagaimana technical infrastructure berkait dengan information security.

Beberapa control yang relevan untuk pembelajaran:

Control	Relevance
A.8.9 Configuration Management	Nginx, DNS dan network configuration
A.8.15 Logging	Nginx Load Balancer logs
A.8.16 Monitoring Activities	Monitoring behaviour dan troubleshooting
A.8.20 Networks Security	Network architecture dan communication
A.8.21 Security of Network Services	DNS, HTTP dan Load Balancing services
A.8.32 Change Management	Controlled configuration changes
A.5.30 ICT Readiness for Business Continuity	Redundancy dan availability concepts

Penting untuk difahami bahawa control mapping sahaja tidak bermaksud sesuatu environment itu compliant.

Dalam audit sebenar, auditor masih memerlukan:

Risk
 ↓
Control
 ↓
Implementation
 ↓
Evidence
 ↓
Monitoring
 ↓
Review
 ↓
Improvement

16. Key Lessons

Antara perkara utama yang saya pelajari:

Load Balancing dan High Availability adalah dua fungsi yang berbeza.
Nginx boleh digunakan sebagai HTTP Load Balancer.
Backend boleh dirujuk menggunakan IP secara static.
Backend juga boleh ditemui menggunakan DNS-based service discovery.
DNS memberikan abstraction layer antara service dan server IP.
resolver dan resolve membolehkan Nginx menggunakan dynamic DNS resolution.
DNS discovery tidak sama dengan health checking.
Logging penting untuk visibility dan troubleshooting.
nginx -T sangat berguna untuk melihat effective configuration.
Configuration changes perlu divalidasi sebelum reload.
Redundancy pada backend membantu meningkatkan availability.
Technical implementation boleh dianalisis menggunakan perspektif ISO/IEC 27001 tanpa mendakwa bahawa lab tersebut sendiri merupakan ISMS.

17. Final Architecture

                         DNS
                    dns / dnsmasq
                    10.107.109.18
                         ▲
                         │
                  DNS lookup
                   web.incus
                         │
                         │
                    Nginx LB
                   10.107.109.69
                         │
                  Load Balancing
              ┌──────────┼──────────┐
              ▼          ▼          ▼
            web01      web02      web03
            .100        .253        .xxx

The key concept is:

DNS = Service Discovery

Nginx = Load Balancer

Web01/Web02/Web03 = Backend Services

Nginx Logs = Operational Visibility

Conclusion

The practical exercise demonstrated two fundamental approaches to Nginx Load Balancing.

The first approach uses static IP addresses, which is simple and suitable for small, stable environments.

The second approach uses DNS-based service discovery, where Nginx resolves a service name such as web.incus to determine the backend servers.

The second approach introduces additional flexibility but also introduces dependencies on DNS availability, DNS caching, TTL behaviour and backend health handling.

The most important lesson is that infrastructure components should not be viewed independently. DNS, Load Balancing, networking, configuration management, logging, availability and security all interact with each other.

From an ISO/IEC 27001 perspective, the exercise demonstrates how technical controls can be understood through the broader cycle of risk, control, implementation, evidence, monitoring and continual improvement.

Building a PDF from Markdown with Pandoc: Images, Code Blocks, TOC and Mermaid

hardyweb — Wed, 19 Aug 2026 05:45:12 +0000

Pandoc is one of those tools that looks simple at first:

pandoc input.md -o output.pdf

But when Markdown becomes a real document, things become more interesting.

Images may disappear, long shell commands can overflow the page, Mermaid diagrams need additional processing, and the generated table of contents may contain sections that we do not want.

This note documents the practical techniques for building a clean PDF from Markdown using Pandoc.

1. Example Project Structure

Let's use a fictional project called Internal API Deployment Guide.

The directory structure is:

docs/
├── assets/
│   ├── architecture.png
│   └── logo.png
├── chapters/
│   ├── introduction.md
│   ├── installation.md
│   └── deployment.md
└── main.md

The important point is that image paths are relative to the Markdown file or the working directory used by Pandoc.

For example:

![System Architecture](assets/architecture.png)

If the image is located elsewhere:

docs/
├── assets/
│   └── architecture.png
└── chapters/
    └── deployment.md

then the path from deployment.md would be:

![System Architecture](../assets/architecture.png)

2. Cover Image

A cover image can simply be inserted using Markdown:

![Cover](assets/logo.png)

However, if the intention is to create a proper PDF title page, it is often cleaner to use YAML metadata and a dedicated LaTeX template.

For example:

---
title: "Internal API Deployment Guide"
author: "Example Engineering Team"
date: "2026"
---

Then:

pandoc main.md \
  --pdf-engine=xelatex \
  -o deployment-guide.pdf

The important lesson is:

Pandoc does not treat a Markdown image as a special "cover page". It is simply an image in the document flow.

If you need a dedicated cover page, control the layout using LaTeX/template mechanisms.

3. Image Paths

One common problem is:

Image not found

or the image simply does not appear in the PDF.

Consider:

project/
├── main.md
└── assets/
    └── architecture.png

The Markdown should use:

![Architecture](assets/architecture.png)

Then run Pandoc from the project directory:

pandoc main.md -o output.pdf

A useful debugging technique is to verify the file first:

ls -lh assets/architecture.png

Then test Pandoc:

pandoc main.md -o test.pdf

If the image still does not appear, check the actual working directory:

pwd

Relative paths are one of the easiest things to overlook when working with Pandoc.

4. Table of Contents

Pandoc can automatically generate a table of contents:

pandoc main.md \
  --toc \
  -o output.pdf

The heading levels included in the TOC can be controlled:

pandoc main.md \
  --toc \
  --toc-depth=2 \
  -o output.pdf

With:

# Deployment Guide

## Installing Dependencies

### Installing PHP

### Installing Composer

## Configuring Nginx

Using:

--toc-depth=2

the TOC will contain:

Deployment Guide
  Installing Dependencies
  Configuring Nginx

but not:

Installing PHP
Installing Composer

This is useful for keeping a technical PDF readable.

5. Removing Unwanted Sections from the TOC

Sometimes the document contains front matter:

# Front Matter

## Title Page

## Copyright

## Disclaimer

# Chapter 1

## Installation

You may not want every front-matter section appearing in the TOC.

One approach is to control the heading hierarchy carefully.

For example, instead of:

# Front Matter

## Title Page

use a custom LaTeX structure or unnumbered headings:

# Title Page {.unnumbered}

or:

# Copyright {.unnumbered}

Depending on the output format and template, this can prevent unwanted numbering and help keep the document structure clean.

6. Code Blocks

Pandoc handles fenced code blocks naturally:

```bash
sudo systemctl restart nginx
```

For example:

sudo systemctl restart nginx

Language identifiers are useful:

```php
Route::get('/health', function () {
    return ['status' => 'ok'];
});
```

Pandoc can then pass the code through syntax highlighting when configured.

For example:

pandoc main.md \
  --highlight-style=tango \
  -o output.pdf

7. The Long Bash Command Problem

Technical documentation often contains commands such as:

docker run --name production-api --restart unless-stopped -p 8080:8080 -v /opt/application/config:/app/config:ro -e APP_ENV=production example/api-server:latest

The problem is that this line may be wider than the printable area of an A4 page.

LaTeX may produce an overfull line.

A better solution is to format the command over multiple lines:

docker run \
  --name production-api \
  --restart unless-stopped \
  -p 8080:8080 \
  -v /opt/application/config:/app/config:ro \
  -e APP_ENV=production \
  example/api-server:latest

This is not only better for PDF generation.

It is also easier for humans to read.

8. Long Inline Commands

Inline code can also cause problems:

Run `docker run --name production-api --restart unless-stopped -p 8080:8080 example/api-server:latest`.

For short commands this is fine.

For long commands, use a fenced block instead:

```bash
docker run \
  --name production-api \
  --restart unless-stopped \
  -p 8080:8080 \
  example/api-server:latest
```

A useful documentation rule is:

If a command is difficult to read in Markdown, it will probably be even worse in PDF.

9. Mermaid Diagrams

Pandoc does not natively turn every Mermaid code block into a rendered diagram.

For example:

```mermaid
flowchart TB
    Client --> API
    API --> Database
```

The Markdown parser can understand the fenced block, but a PDF engine such as XeLaTeX does not automatically know how to render Mermaid.

A common solution is to convert Mermaid separately.

Create:

architecture.mmd

with:

flowchart TB
    Client --> API
    API --> Database

Then generate an image:

mmdc \
  -i architecture.mmd \
  -o architecture.png

Now include the generated image:

![System Architecture](assets/architecture.png)

This separates diagram generation from PDF generation.

10. Mermaid Workflow

A practical workflow is:

Mermaid source
      |
      v
   mmdc
      |
      v
 PNG / SVG
      |
      v
   Markdown
      |
      v
   Pandoc
      |
      v
    PDF

For example:

mmdc \
  -i assets/architecture.mmd \
  -o assets/architecture.png

Then:

pandoc main.md \
  --toc \
  --pdf-engine=xelatex \
  -o output.pdf

This approach is easier to troubleshoot than trying to make every component work inside one command.

11. PNG vs SVG

Mermaid can generate both PNG and SVG.

PNG:

mmdc \
  -i architecture.mmd \
  -o architecture.png

SVG:

mmdc \
  -i architecture.mmd \
  -o architecture.svg

SVG is useful because it is vector-based.

However, the complete toolchain matters.

If SVG rendering causes problems in the LaTeX/PDF pipeline, PNG is often the simpler solution.

For technical documentation, a good starting point is:

Mermaid → PNG → Pandoc → XeLaTeX → PDF

Once the pipeline is stable, SVG can be introduced if higher-quality vector diagrams are required.

12. Using XeLaTeX

For modern technical documents, XeLaTeX is a useful PDF engine.

Example:

pandoc main.md \
  --pdf-engine=xelatex \
  -o output.pdf

It provides better control over fonts and Unicode than some older LaTeX workflows.

You can specify a main font:

pandoc main.md \
  --pdf-engine=xelatex \
  -V mainfont="DejaVu Serif" \
  -o output.pdf

For code:

-V monofont="DejaVu Sans Mono"

13. Unicode Problems

Technical documentation often contains symbols such as:

✓
→
⚠
✅

If the selected font does not contain these glyphs, XeLaTeX may display warnings such as:

Missing character

For example:

[WARNING] Missing character: There is no ✅

The problem is usually not Pandoc itself.

It is a font coverage problem.

One solution is to use a font with better Unicode coverage.

Another is to avoid unnecessary emoji in PDF source documents.

For technical books, simple ASCII characters are often safer:

[OK]
[WARNING]
[ERROR]

instead of:

✅
⚠️
❌

14. A Simple Build Command

Once the document is ready, a simple build command might be:

pandoc main.md \
  --toc \
  --toc-depth=2 \
  --pdf-engine=xelatex \
  --highlight-style=tango \
  -o output.pdf

This gives us:

Markdown input
automatic TOC
maximum TOC depth of 2
XeLaTeX PDF generation
syntax-highlighted code
PDF output

15. Separate the Build Process

Instead of remembering a long command, create a script:

#!/usr/bin/env bash

set -e

pandoc main.md \
  --toc \
  --toc-depth=2 \
  --pdf-engine=xelatex \
  --highlight-style=tango \
  -o output.pdf

echo "PDF generated: output.pdf"

Save it as:

build.sh

Then:

chmod +x build.sh

Run:

./build.sh

This makes the document reproducible.

16. A Better Project Layout

For a larger documentation project, a structure like this works well:

documentation/
├── assets/
│   ├── architecture.png
│   ├── database.png
│   └── logo.png
├── diagrams/
│   ├── architecture.mmd
│   └── database.mmd
├── chapters/
│   ├── introduction.md
│   ├── installation.md
│   └── deployment.md
├── main.md
├── build.sh
└── output/
    └── documentation.pdf

The responsibilities are clear:

chapters/   → Markdown content
diagrams/   → Mermaid source
assets/     → generated/static images
main.md     → document entry point
build.sh    → reproducible build
output/     → generated PDF

17. The Important Lesson

Pandoc itself is only one part of the pipeline.

A real Markdown-to-PDF workflow can look like this:

Markdown
   |
   +---- Images
   |
   +---- Code
   |
   +---- Mermaid
   |
   v
Pandoc
   |
   v
XeLaTeX
   |
   v
PDF

When something goes wrong, debug the pipeline one component at a time.

For example:

Image missing
    ↓
Check Markdown path

Mermaid missing
    ↓
Check Mermaid conversion

Unicode warning
    ↓
Check font

Code overflowing page
    ↓
Reformat long command

TOC incorrect
    ↓
Check heading hierarchy

This mindset is much more useful than trying random Pandoc options.

Conclusion

Pandoc is powerful because Markdown can remain the source of truth while the final document can be generated in different formats.

For a reliable technical-documentation workflow, keep the pipeline simple:

Markdown
    ↓
Pandoc
    ↓
XeLaTeX
    ↓
PDF

And treat external content such as Mermaid diagrams as separate build inputs:

Mermaid
    ↓
PNG/SVG
    ↓
Markdown
    ↓
Pandoc
    ↓
PDF

The key is not finding one giant Pandoc command.

The key is building a reproducible document pipeline that is easy to debug.

Run Simple Web Server On The Spot

hardyweb — Sun, 02 Aug 2026 07:19:19 +0000

PHP php -S localhost:8000

PHP (public)    php -S localhost:8000 -t public

Python  python3 -m http.server 8000

Node    npx serve -p 8000

BusyBox busybox httpd -f -p 8000

Ruby    ruby -run -e httpd . -p 8000

Panduan Teknikal: Compile llama.cpp di Debian 12/13 dan Cross Compile ARM64

hardyweb — Tue, 14 Jul 2026 07:52:24 +0000

1. Pengenalan

llama.cpp ialah runtime inference LLM berasaskan C/C++ yang popular kerana ringan, pantas, dan sesuai untuk menjalankan model GGUF secara local. Ia boleh digunakan pada:

Server x86_64
Workstation Linux
Mini PC
Raspberry Pi
Orange Pi
SBC ARM64
Container Linux

Dalam deployment sebenar, terdapat dua pendekatan utama:

Native build
Compile terus pada mesin yang akan menjalankan llama.cpp.
Cross compile
Compile pada mesin lebih laju (contohnya PC x86_64), tetapi menghasilkan binary untuk platform lain (contohnya ARM64 Orange Pi).

Bahagian 1 — Persediaan Debian 12/13

1.1 Install dependency asas

sudo apt update

sudo apt install -y \
    git \
    build-essential \
    cmake \
    ninja-build \
    pkg-config

Komponen utama:

Package Fungsi
git Ambil source code
build-essential GCC, G++, make
cmake Build configuration
ninja-build Build engine lebih pantas
pkg-config Cari library dependency

Bahagian 2 — Clone llama.cpp

git clone https://github.com/ggml-org/llama.cpp.git

cd llama.cpp

Semak versi:

git log -1 --oneline

Bahagian 3 — Compile Native (Mesin Sama)

Contoh:

Debian 12/13 x86_64
Debian ARM64
Orange Pi
Raspberry Pi

3.1 Configure CMake

Build menggunakan Ninja:

cmake -B build \
    -G Ninja \
    -DCMAKE_BUILD_TYPE=Release
3.2 Compile
ninja -C build -j$(nproc)

atau:

cmake --build build

plaintext
3.3 Hasil build

Semak:

ls build/bin

plaintext
Contoh:

llama-cli
llama-server
llama-bench
llama-perplexity

shell

Bahagian 4 — Enable OpenBLAS (Pilihan)

OpenBLAS boleh membantu operasi matrix CPU.

Install:

sudo apt install libopenblas-dev

cmake
Build:

cmake -B build \
    -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DGGML_BLAS=ON \
    -DGGML_BLAS_VENDOR=OpenBLAS

shell
Kemudian:

ninja -C build

Nota Penting: CMake Cache

Jika pernah configure dengan:

-DGGML_BLAS=ON

kemudian buang option tersebut, CMake masih menyimpan konfigurasi lama.

Contoh masalah:

BLAS not found
missing: BLAS_LIBRARIES

Penyelesaian:

rm -rf build

Kemudian configure semula.

Sentiasa ingat:

CMakeCache.txt menyimpan konfigurasi lama.
Bahagian 5 — Cross Compile x86_64 → ARM64

Contoh:

PC Debian 12 x86_64
|
|
v
Orange Pi ARM64

Kelebihan:

Compile lebih cepat
Tidak membebankan SBC
Sesuai untuk production image

5.1 Install ARM64 cross compiler

sudo apt install -y \
    gcc-12-aarch64-linux--gnu\
    g++-12-aarch64-linux-gnu

sudo apt install -y \
    gcc-13-aarch64-linux--gnu\
    g++-13-aarch64-linux-gnu

Semak:

aarch64-linux-gnu-gcc --version

5.2 Configure cross build

Bersihkan dahulu:

rm -rf build-arm

Kemudian:

cmake -B build-arm \
    -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_SYSTEM_NAME=Linux \
    -DCMAKE_SYSTEM_PROCESSOR=aarch64 \
    -DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
    -DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++
5.3 Compile
ninja -C build-arm -j$(nproc)

Hasil:

ls build-arm/bin

Bahagian 6 — Semak Architecture Binary

Gunakan:

file build-arm/bin/llama-server

Contoh output berjaya:

ELF 64-bit LSB pie executable,
ARM aarch64,
dynamically linked

Maksud:

Output Maksud
ELF 64-bit Binary 64-bit
ARM aarch64 Untuk ARM64
dynamically linked Perlukan shared library
PIE executable Linux security hardening
Bahagian 7 — Semak Dependency .so
Jangan guna ldd untuk cross binary

Jika compile ARM64 tetapi check pada PC x86:

ldd llama-server

boleh gagal:

not a dynamic executable

Sebab:

PC:

x86_64 loader

Binary:

ARM64 loader
Gunakan readelf
aarch64-linux-gnu-readelf \
-d build-arm/bin/llama-server | grep NEEDED

Contoh:

Shared library: [libllama.so]
Shared library: [libggml.so]
Shared library: [libstdc++.so.6]

Cari semua .so

find build-arm -name "*.so"

Contoh:

libllama.so
libggml.so
libggml-base.so
libggml-cpu.so

Semak architecture:

file build-arm/bin/*.so

Output:

ARM aarch64
Bahagian 8 — Dynamic vs Static Binary

Semak:

file llama-server

Contoh dynamic:

dynamically linked

Perlu:

lib*.so

Contoh static:

statically linked

Tidak perlu .so.

Bahagian 9 — Installation ke Linux
Pilihan standard

Binary:

/usr/local/bin

Library:

/usr/local/lib

Contoh:

sudo cp llama-server /usr/local/bin/
sudo cp llama-cli /usr/local/bin/

sudo cp *.so /usr/local/lib/

sudo ldconfig

Pilihan appliance / embedded

Untuk SBC:

/opt/llama.cpp/

    llama-server
    llama-cli
    libllama.so
    libggml.so

Kemudian:

export LD_LIBRARY_PATH=/opt/llama.cpp

Sesuai untuk:

Orange Pi
kiosk AI
edge inference node

Bahagian 10 — Deploy ke Orange Pi

Copy:

scp build-arm/bin/llama-server \
orangepi:/usr/local/bin/

scp build-arm/bin/llama-cli \
orangepi:/usr/local/bin/

Jika perlu:

scp build-arm/bin/*.so \
orangepi:/usr/local/lib/

Pada Orange Pi:

sudo ldconfig

Semak:

uname -m

Expected:

aarch64

Bahagian 11 — Cadangan Production Architecture

Untuk sistem AI agent:

Kelebihan:

Go agent tidak perlu embed model
Model boleh tukar tanpa rebuild
llama.cpp boleh upgrade sendiri
Mudah scale ke banyak node
Kesimpulan

Workflow yang stabil:

Native
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release

ninja -C build
Cross Compile ARM64
sudo apt install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

rm -rf build-arm

cmake -B build-arm \
-G Ninja \
-DCMAKE_SYSTEM_NAME=Linux \
-DCMAKE_SYSTEM_PROCESSOR=aarch64 \
-DCMAKE_C_COMPILER=aarch64-linux-gnu-gcc \
-DCMAKE_CXX_COMPILER=aarch64-linux-gnu-g++

ninja -C build-arm
Verification
file llama-server

aarch64-linux-gnu-readelf -d llama-server | grep NEEDED

find . -name "*.so"

Dengan proses ini, satu mesin Debian 12/13 boleh menjadi build server untuk menghasilkan node AI ARM64 seperti Orange Pi, Raspberry Pi, atau edge inference appliance.

Kaedah Saliran Pasif Menggunakan Struktur Sumbu Kapilari Berasaskan Cable Tie

hardyweb — Tue, 23 Jun 2026 02:56:10 +0000

Abstrak

Dokumen ini membentangkan satu mekanisme saliran pasif berskala mikro menggunakan cable tie yang dibentuk sebagai struktur gelung (loop) untuk bertindak sebagai medium sumbu kapilari. Sistem ini membolehkan pemindahan air dari takungan ke saluran keluar melalui gabungan tindakan kapilari, adhesi, kohesi, serta graviti tanpa penggunaan tenaga luaran.

Kaedah ini sesuai untuk aplikasi DIY, pengurusan air bertakung kecil, serta demonstrasi pendidikan dalam bidang mekanik bendalir.

Latar Belakang Masalah

Dalam sistem saliran berskala kecil, kegagalan aliran sering berlaku walaupun terdapat perbezaan aras cecair yang sepatutnya mencukupi secara teori. Antara punca utama:

Pembentukan air lock dalam saluran kecil
Tegangan permukaan menghalang kemasukan awal bendalir
Ketiadaan medium “wetting path” awal untuk memulakan aliran
Ketidakstabilan aliran pada bukaan kecil (intermittent flow)

Fenomena ini menyebabkan sistem gagal “start flow” walaupun graviti tersedia.

Objektif Menyediakan mekanisme saliran pasif tanpa tenaga luaran Mengatasi masalah permulaan aliran (flow initiation problem) Mengurangkan kesan air lock dan tegangan permukaan Mewujudkan laluan basah berterusan sebagai pemangkin aliran
Prinsip Fizik Terlibat 4.1 Graviti

Mendorong aliran akhir dari kawasan berpotensi tinggi ke rendah.

4.2 Tekanan Hidrostatik
P=ρgh

Perbezaan aras cecair menghasilkan tekanan pendorong aliran.

4.3 Tegangan Permukaan

Menentang kemasukan air ke dalam bukaan kecil tanpa bantuan awal.

4.4 Tindakan Kapilari
h∝r1

Air merambat melalui permukaan kabel berdasarkan interaksi molekul.

4.5 Adhesi & Kohesi
Adhesi: air melekat pada permukaan cable tie
Kohesi: molekul air mengekalkan kesinambungan aliran
4.6 Interaksi Multi-Fasa

Peralihan daripada fasa “wetting initiation” → “continuous flow”

Reka Bentuk Sistem

Sistem terdiri daripada cable tie yang dibentuk menjadi gelung dan diposisikan merentasi lubang saliran.

Ciri reka bentuk:

Gelung separa terendam dalam takungan
Titik sentuhan di kawasan lubang bertindak sebagai “wick transfer point”
Kepala cable tie bertindak sebagai pengunci mekanikal
Skema Konsep

Mekanisme Operasi
Air bersentuhan dengan permukaan cable tie
Molekul air membentuk lapisan awal melalui adhesi
Laluan basah terbentuk sepanjang gelung (capillary propagation)
Air mencapai titik lubang saliran
Graviti mengambil alih dan mengekalkan aliran berterusan
Sistem mencapai keadaan steady-state micro flow
Ciri Sistem
Tanpa tenaga elektrik
Kos hampir sifar
Struktur mudah dan boleh diulang
Boleh dipasang tanpa modifikasi besar sistem asal
Sesuai untuk prototaip pantas (rapid prototyping)
Had Sistem
Aliran rendah (micro-scale throughput)
Sensitif kepada minyak, habuk, dan kontaminasi permukaan
Tidak sesuai untuk volum besar
Prestasi bergantung pada material (surface energy & roughness)
Aplikasi Potensi
Sistem saliran air hujan mikro
Sistem tanaman pasif (hybrid wicking-drainage)
Pengurusan kondensasi (AC / cooling drip control)
Demonstrasi fizik bendalir untuk pendidikan STEM
Prototaip sistem IoT pasif (no-power fluid indicator)
Kesimpulan

Kaedah ini menunjukkan bahawa sistem saliran mikro tidak bergantung sepenuhnya kepada graviti, tetapi kepada interaksi kompleks antara tegangan permukaan, kapilari, dan sifat bahan.

Struktur gelung cable tie bertindak sebagai “capillary bridge” yang menstabilkan permulaan aliran, sekaligus mengatasi masalah air lock dalam sistem bukaan kecil.