Blog

在 Gitlab 平台簡單創建 GitBook 電子書的步驟

GitLab 提供了 gitbook儲庫 的範本,只要用戶 Fork 該專案,如此就可以建立屬於自己的 GitBook 文檔網站。不過這方式我不太喜歡,需要修改專案名稱等相關屬性,然後也要編輯「README.md」、「SUMMARY.md」內容,如此就會造成 commit 歷史紀錄一開始較為雜亂。 (雖然也可以清除,但又要額外的步驟。)

除了 Fork 的方式,其實也可以自己手動新增空白的專案,然後再針對 GitLab CI (Continuous Integration) 設定並加入執行的腳本內容即可。 (其實就是 gitbook 儲庫內的 .gitlab-ci.yml 內容)

整理下創建 GitBook 網站@GitLab 平台的步驟:

  1. 新增空白專案
    這應該不用說吧,與 GitHub 新增專案的方式幾乎是一樣。大概就是注意下儲庫的存取改為「Public」,然後預設新增一「README.md」檔案,該檔案也是 GitBook 所必要的檔案。

    新增 GitLab 空白專案

  2. 閱讀全文 »

關於 GitBook 平台的改版與 GitLab 替代的考量

GitBook 有兩種含意:一為 GitBook 文件平台;另一則為 採以 Node.js 所開發的命令列工具,用以製作基於 Git/Markdown 所產出精美的電子書文件。

就在今年四月底,Gitbook 平台 (Github 旗下之一),推出所謂的 V2 大改版,改版幅度之大,連帶影響到既有廣大的 V1 開源用戶,預計今年10月左右就要關閉 V1 的使用,強制改版至 V2。但更為難受的是它的 售價策略,Free 方案竟只縮減為只能創建一個「space」,也就是只能創建一本電子書;而付費方案最低則為每個月要支付 7美金 (5 user)!

這肯定會引發一大波開源用戶的出走潮!畢竟絕大多用戶都是基於開源分享的精神將自己的創作 (程式碼/文件) 置於 Github/GitBook 的。 (關於這次 GitBook 大改版,可參考對岸這篇:如何看待 GitBook 的改版?)

所以,要製作開源的電子書在 GitBook 平台短期內 (預期這風波會造成大量用戶的質疑抱怨)並非理想的方案。退而求其次,尋求替代可提供免費文件的平台,並基於 gitbook 工具所製作的電子書,那就非 GitLab 平台莫屬!

GitLab 也有兩種含意:一為 GitLab Inc. 所提供幾乎與 Github 一樣的介面與服務;另一則為該家公司所釋放出基於網路的Git倉庫管理工具,且具有wiki和issue跟蹤功能,可方便私人建構所屬的私有 Git 儲庫平台。

而且 GitLab Inc. 背後可是有強大的金主:Google!所以也不用擔心會有突然關閉或如 Github 那樣不可思議的收費方案。 (額,Github 被微軟收購的,這應該大家都知道吧~。)

要在 GitLab 平台發佈基於 gitbook 工具所製作的電子書並不困難,官方也提供了一個 gitbook 儲庫 (repository) 範本 (可參考它所產出的 靜態文件網頁),可依照該儲庫的 README 說明並 fork 該儲庫即可開始建構所屬自己的電子書。

嗯,其實我個人不太喜歡使用 Fork 的方式當成自己專案的起點,下一篇就來分享下如何在 GitLab 新增專案並配置成可被持續發佈的 GitBook 文件網站。 (其實步驟比想像得還簡單)

ArchLinux 跑 Virtualbox Seamless 無縫模式@Windows 10

原來以為透過 WSL 執行 ArchLinux 是在 Windows 10 系統內執行 Linux 相關應用程式會是理想的解決方案。但,當我在 WSL 要安裝 XFCE 桌面環境卻是問題多多 (Console 模式則很正常)。雖然仍可以啟動 XFCE 並跑應用程式,但我查看 Log 卻是錯誤訊息一堆,大都與 DBus、GTK 等相關的問題,查找 Google 卻是沒看出所以然。看來現階段在 WSL 跑 Linux 還不太完美 (另外還有效能的問題),所以只好先關閉 WSL,等待下一次 Windows 10 釋出較大改版再來試裝。

退而求其次,只好還是在虛擬機上執行 ArchLinux 了。這次我不使用 Vmware 了,占用系統資源太多 (雖然它執行虛擬系統效能會好上很多),改嘗試使用 Virtualbox 並透過它的 Seamless 無縫模式執行 Linux 應用程式。

這是我第一次使用 Virtualbox,不過安裝虛擬系統倒是很簡單,網路分享安裝文件很多。大概幾個選項,勾選 3D 加速、動態配置儲存空間 (最大空間設為 32Gb)、4GB RAM、切了單核2線程 (我的 Intel CPU 是 i7-7700hq 八核心),這樣就可以在虛擬機環境下安裝 ArchLinux 了。

閱讀全文 »

安裝 ArchLinux @Windows 10 子系統 (WSL)

其實 Windows 10 早在去年就已具有可以在 Windows 環境下執行 Ubuntu 的機制,但還很陽春,效能不佳,問題多多。但從 Windows 10 1803 版本釋出後,WSL (Windows Subsystem for Linux) 已修正諸多問題並大幅提昇執行效能,使其執行原生 Linux 系統於 Windows 10 環境下成為可便利運行的方案。

所以,WSL 到底是什麼?這篇 Arch Wiki 上說明得很清楚:

「Windows 10 包含一個模擬 Linux 內核的子系統,使得 windows 可以運行 Linux 原生應用程序。這個子系統有點像反過來的 Wine,但是它比 Wine 更加底層。默認情況下,此子系統使用 Ubuntu 用戶空間,但是它可以被替換成 Arch。你需要使用一個現有的 Arch 安裝去構建一些軟件包。」

我個人是相當偏好 ArchLinux,因為可以高度客製化。安裝 ArchLinux 於 WSL 下相當簡單,因為國外已經有大神整理成安裝執行包,詳見 Github-ArchWSL。安裝該執行包前,需要先啟動 WSL 功能,使用 Administrator 開啟 PowerShell 命令列視窗,執行下列指令:

> Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

重新啟動,然後下載上述 ArchWSL 安裝包,解壓縮並置於準備安裝的目錄下 (我是設定於 C:\Linux\ArchLinux 目錄下)。再來依照執行 ARCH.exe,靜待安裝過程 (非常快),然後完成。

閱讀全文 »

[實作筆記] ASP.NET Core Identity 2.1 – 安裝與設定(一)

主要是為了方便授課上講授 TDD.NET 如何應用 Mock 隔離測試的觀念,所以打算藉由 ASP.NET Core Identity 2.1 驗證與授權 (Authentication and Authorization)的機制併整合訂購系統 (核心邏輯/資料庫存取位於另一專案)的案例,來展示 單元測試 (Unit Test)搭配 Mock 隔離的程式碼範例。

另外為了測試資料庫方便可攜供學員可以直接使用,所以打算不再使用具名的 SQL Express 檔案 (連線字串問題,多個專案要指定絕對路徑,不方便複製),而只使用 SQL Express LocalDB (預設位於 C:\使用者\使用者帳號目錄內),然後再以 Code First Migration 方式與 Seed Data 方便初始建置資料庫表格與測試資料,這些留待後續系列文章再作說明。

本系列文章並非是完整的 Step by Step 教學文,而僅是一份實作筆記,主要記錄了實作過程中一些重點摘要。同時也提供了一份程式碼範本,供個人以及對相關議題有興趣的讀者參考。

程式碼範本以 Git 版控儲存於 Github 儲庫:kenming/aspdotnet-core-identyity-2dot1-practice-note
每一個階段會標注 Tag 標籤方便提取研究與切換版本。

先簡單說明下 ASP.NET Core Identity,它是微軟所提供被歸為 ASP.NET Web 端的一個「會員 (Membership)」系統,提供給應用系統開發人員方便具有登入 (Login)驗證名稱與密碼的機制。它很明顯是 Client/Server 的 2-tier 分層方式所開發的系統,但還好因為 Login 這類機制係屬於「非功能性 (Non Functional)」需求,所以也不至於會干涉到應用系統關於「功能性需求 (如處理訂購、追蹤訂購等系統功能)」的耦合 (coupling)。未來可以全部抽換掉 Identity 而不影響到應用系統的主結構 (當然還是要稍稍花一些整合設計的心思)。

個人仍覺得 ASP.NET Identity 即便到 2.1 版本,但安裝與設定程序仍嫌繁瑣,而且從 1.X、2.0 到 2.1,每一次的安裝與設定方式大都不一樣,預期後續版本仍會有持續的變動震盪。所以更顯然絕對不要撰寫與問題領域 (problem domain)相關的邏輯在該專案內,這點從個人後續提供的範例就可以看到如何避免。

本篇文章先著重在如何安裝 Core Identity 2.1,然後新增「Scaffold Identity Item」,並修改些預設的登入選項參數 (如密碼長度),然後執行預設的首頁 (index)並選擇註冊 (register)帳號並執行登入 (login)。

閱讀全文 »

闡述軟體架構師素養的絕佳古文-柳宗元「梓人傳」

軟體架構師 (Architect) 一詞,雖是源自於國外建築產業的關鍵術語,甚而建築業大師 Christopher Alexander 的著作:「The Timeless Way of Building」(國內翻譯書為「建築的永恆之道」」,更是被軟體業界奉為設計模式 (Design Pattern)之父。不過,關於軟體架構師應具有的素養,卻是更早可以從「古文觀止」其中一篇:柳宗元所著「梓人傳」,早已道盡成為軟體架構師所需的技能為何。

這裡節錄此篇古文,並引用國內 C++ 大師早已所翻譯部份文言為白話,可以確實好好品味欣賞、一讀再讀反覆玩味思考的。

裴封叔之第,在光德里。有梓人款其門,願傭隙宇而處焉。所職,尋、引、規、矩、繩、墨,家不居礱斲之器。問其能,曰:「吾善度材。視棟宇之制,高深圓方短長之宜,吾指使而群工役焉。舍我,眾莫能就一宇。故食於官府,吾受祿三倍;作於私家,吾收其宜大半焉。」

他日,入其室,其床闕足而不能理,曰:「將求他工。」餘甚笑之,謂其無能而貪祿嗜貨者。

其後,京兆尹將飾官署,餘往過焉。委群材,會群工,或執斧斤,或執刀鋸,皆環立向之。梓人左持引,右執杖,而中處焉。量棟宇之任,視木之能舉,揮其杖,曰:「斧!」彼執斧者奔而右;顧而指曰:「鋸!」彼執鋸者趨而左。俄而,斤者斲,刀者削,皆視其色,俟其言,莫敢自斷者。其不勝任者,怒而退之,亦莫敢慍焉。畫宮於堵,盈尺而曲盡其制,計其毫釐而構大廈,無進退焉。既成,書於上棟曰:「某年某月某日某建」。則其姓字也。凡執用之工不在列。餘圜視大駭,然後知其術之工大矣。

繼而嘆曰:彼將舍其手藝,專其心智,而能知體要者歟!吾聞勞心者役人,勞力者役於人。彼其勞心者歟!能者用而智者謀,彼其智者歟!是足為佐天子,相天下法矣。物莫近乎此也。彼為天下者本於人。其執役者為徒隸,為鄉師、裡胥;其上為下士;又其上為中士,為上士;又其上為大夫,為卿,為公。離而為六職,判而為百役。外薄四海,有方伯、連率。郡有守,邑有宰,皆有佐政;其下有胥吏,又其下皆有嗇夫、版尹以就役焉,猶眾工之各有執伎以食力也。

彼佐天子相天下者,舉而加焉,指而使焉,條其綱紀而盈縮焉,齊其法制而整頓焉;猶梓人之有規、矩、繩、墨以定制也。擇天下之士,使稱其職;居天下之人,使安其業。視都知野,視野知國,視國知天下,其遠邇細大,可手據其圖而究焉,猶梓人畫宮於堵,而績於成也。能者進而由之,使無所德;不能者退而休之,亦莫敢慍。不炫能,不矜名,不親小勞,不侵眾官,日與天下之英纔,討論其大經,猶梓人之善運眾工而不伐藝也。夫然後相道得而萬國理矣。

相道既得,萬國既理,天下舉首而望曰:「吾相之功也!」後之人循跡而慕曰:「彼相之纔也!」士或談殷、周之理者,曰:「伊、傅、周、召。」其百執事之勤勞,而不得紀焉;猶梓人自名其功,而執用者不列也。大哉相乎!通是道者,所謂相而已矣。其不知體要者反此;以恪勤為公,以簿書為尊,炫能矜名,親小勞,侵眾官,竊取六職、百役之事,聽聽於府庭,而遺其大者遠者焉,所謂不通是道者也。猶梓人而不知繩墨之曲直,規矩之方圓,尋引之短長,姑奪眾工之斧斤刀鋸以佐其藝,又不能備其工,以至敗績,用而無所成也,不亦謬歟!

或曰:「彼主為室者,儻或發其私智,牽制梓人之慮,奪其世守,而道謀是用。雖不能成功,豈其罪耶?亦在任之而已!」

餘曰:「不然!夫繩墨誠陳,規矩誠設,高者不可抑而下也,狹者不可張而廣也。由我則固,不由我則圮。彼將樂去固而就圮也,則卷其術,默其智,悠爾而去。不屈吾道,是誠良梓人耳!其或嗜其貨利,忍而不能舍也,喪其制量,屈而不能守也,棟橈屋壞,則曰:「『非我罪也』!可乎哉?可乎哉?」

餘謂梓人之道類於相,故書而藏之。梓人,蓋古之審曲面勢者,今謂之「都料匠」雲。餘所遇者,楊氏,潛其名。

閱讀全文 »

軟體思維顧問

專職軟體輔導與教育訓練的獨立顧問。輔導企業資訊單位如何有效組織系統開發與維護;輔導開發人員達成有效的專業分工。傳授如何把軟體作軟 (Keeping Software Soft)的技能,得以提昇系統的彈性/延展,並進而創造系統的再利用價值。

Personal