docs: improve README and updater guide

thachvd-tfo · thachvd-tfo · commit 6b5b68d70f1b · 2026-03-31T11:09:33.000+07:00
diff --git a/README.md b/README.md
@@ -1,7 +1,134 @@
-# Tauri + React + Typescript
+# DevStack
 
-This template should help get you started developing with Tauri, React and Typescript in Vite.
+<p align="center">
+  Desktop local development environment for Windows, built with Tauri v2 + React.
+</p>
 
-## Recommended IDE Setup
+<p align="center">
+  <a href="https://github.com/holdon1996/dev-stack/releases">
+    <img src="https://img.shields.io/github/v/release/holdon1996/dev-stack?display_name=tag&style=for-the-badge" alt="Release">
+  </a>
+  <a href="https://github.com/holdon1996/dev-stack/actions/workflows/release.yml">
+    <img src="https://img.shields.io/github/actions/workflow/status/holdon1996/dev-stack/release.yml?style=for-the-badge&label=release" alt="Release Workflow">
+  </a>
+  <a href="https://github.com/holdon1996/dev-stack/stargazers">
+    <img src="https://img.shields.io/github/stars/holdon1996/dev-stack?style=for-the-badge" alt="Stars">
+  </a>
+  <a href="https://github.com/holdon1996/dev-stack/network/members">
+    <img src="https://img.shields.io/github/forks/holdon1996/dev-stack?style=for-the-badge" alt="Forks">
+  </a>
+  <a href="https://github.com/holdon1996/dev-stack/issues">
+    <img src="https://img.shields.io/github/issues/holdon1996/dev-stack?style=for-the-badge" alt="Issues">
+  </a>
+</p>
 
-- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
+## Overview
+
+DevStack is a desktop tool for managing a local PHP / Apache / MySQL development stack on Windows with a fast native Rust backend.
+
+It focuses on:
+
+- managing Apache, MySQL, PHP, Redis, and project services in one UI
+- switching installed runtime versions without a heavy VM or container workflow
+- handling virtual hosts, local sites, ports, logs, and quick config from one app
+- shipping as a native Windows desktop app with tray support and auto-update support
+
+## Highlights
+
+- Native Tauri v2 desktop app
+- React + Zustand frontend
+- Rust backend for process management, file operations, downloads, and system integration
+- Apache version management
+- PHP version management and per-project switching
+- MySQL management and query execution
+- Virtual host setup with hosts file sync
+- Tunnel integrations page
+- Log viewer for Apache, MySQL, PHP, and Redis
+- Start with Windows support
+- Native updater support for packaged releases
+
+## Main Sections
+
+- `Services`: start, stop, monitor, and auto-start managed services
+- `Sites`: create and manage local virtual hosts and project folders
+- `Apache`: install and switch Apache builds
+- `Database`: manage MySQL versions and run quick queries
+- `PHP`: install, switch, and patch PHP runtimes
+- `Tunnels`: expose local services through supported tunnel providers
+- `Quick Config`: shortcut actions for common setup tasks
+- `Settings`: paths, ports, startup behavior, editor, and updates
+
+## Tech Stack
+
+- Tauri v2
+- React 19
+- Zustand
+- Tailwind CSS
+- Rust
+
+## Project Structure
+
+```text
+src/                 React UI, state slices, hooks
+src-tauri/           Rust commands, Tauri config, bundling
+src/store/           Zustand slices for app domains
+scripts/             Local helper scripts
+.github/workflows/   Release automation
+```
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20+
+- Rust stable
+- Windows
+
+### Development
+
+```powershell
+npm install
+npm run tauri dev
+```
+
+### Production Build
+
+```powershell
+npm run tauri build
+```
+
+## Releases And Auto Update
+
+Updater and release signing are already wired into the app and workflow.
+
+- Release workflow: [.github/workflows/release.yml](/f:/dev-stack/.github/workflows/release.yml)
+- Updater setup guide: [UPDATER_SETUP.md](/f:/dev-stack/UPDATER_SETUP.md)
+- Local env helper: [scripts/set-updater-env.ps1](/f:/dev-stack/scripts/set-updater-env.ps1)
+
+If the repository is private, GitHub-hosted updater assets will not be publicly downloadable by end users. For the current updater URL strategy, the repository should be public or served through a separate update endpoint.
+
+## Recommended Setup
+
+- VS Code
+- Tauri extension
+- rust-analyzer
+
+## Roadmap
+
+- Better release presentation and screenshots
+- More automated runtime discovery
+- Improved SSL and local certificate flow
+- Better onboarding for first-time setup
+
+## Star History
+
+<p align="center">
+  <a href="https://star-history.com/#holdon1996/dev-stack&Date">
+    <img src="https://api.star-history.com/svg?repos=holdon1996/dev-stack&type=Date" alt="Star History Chart">
+  </a>
+</p>
+
+## Support
+
+- Issues: https://github.com/holdon1996/dev-stack/issues
+- Releases: https://github.com/holdon1996/dev-stack/releases
diff --git a/UPDATER_SETUP.md b/UPDATER_SETUP.md
@@ -0,0 +1,260 @@
+# DevStack Updater Setup
+
+Tài liệu này ghi rõ cách tạo lại updater key, setup GitHub Secrets, build release, và cách updater native trong app đang được cấu hình.
+
+## Tổng quan
+
+App hiện đang có 2 chế độ:
+
+- Native auto-update của Tauri: chỉ hoạt động khi lúc build có `TAURI_UPDATER_PUBKEY` và `TAURI_UPDATER_ENDPOINT`.
+- Manual update fallback: nếu build không có 2 biến trên, app vẫn check GitHub Releases và mở trang tải bản mới.
+
+Code hiện đang đọc 2 biến này bằng `option_env!`, nên đây là compile-time env vars. Nghĩa là chúng phải có sẵn trong GitHub Actions trước khi chạy build.
+
+## 1. Tạo lại updater key
+
+Chỉ tạo lại key nếu bạn chưa phát hành updater cho người dùng, hoặc bạn chấp nhận rằng các bản đã cài bằng key cũ sẽ không nhận được native update nữa.
+
+### Xóa key cũ
+
+Chạy trên PowerShell:
+
+```powershell
+Remove-Item "$HOME\.tauri\devstack.key" -Force -ErrorAction SilentlyContinue
+Remove-Item "$HOME\.tauri\devstack.key.pub" -Force -ErrorAction SilentlyContinue
+```
+
+Nếu thư mục chưa tồn tại:
+
+```powershell
+New-Item -ItemType Directory -Force "$HOME\.tauri"
+```
+
+### Tạo key mới có password
+
+```powershell
+npm run tauri signer generate -- -w "$HOME\.tauri\devstack.key"
+```
+
+CLI sẽ hỏi:
+
+```text
+Please enter a password to protect the secret key.
+Password:
+Password (one more time):
+```
+
+Nhập password bạn muốn dùng để mã hóa private key.
+
+### Kiểm tra key đã tạo
+
+```powershell
+Get-ChildItem "$HOME\.tauri\devstack.key*"
+```
+
+Lấy public key:
+
+```powershell
+Get-Content "$HOME\.tauri\devstack.key.pub"
+```
+
+Lấy private key:
+
+```powershell
+Get-Content "$HOME\.tauri\devstack.key"
+```
+
+## 2. GitHub cần setup gì
+
+Vào repo GitHub:
+
+`Settings` -> `Secrets and variables` -> `Actions` -> `New repository secret`
+
+Tạo 3 secrets sau:
+
+### `TAURI_SIGNING_PRIVATE_KEY`
+
+Giá trị là nội dung file private key:
+
+```powershell
+Get-Content "$HOME\.tauri\devstack.key" -Raw
+```
+
+Copy toàn bộ nội dung đó vào secret.
+
+### `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`
+
+Giá trị là password bạn vừa nhập lúc generate key.
+
+### `TAURI_UPDATER_PUBKEY`
+
+Giá trị là nội dung file public key:
+
+```powershell
+Get-Content "$HOME\.tauri\devstack.key.pub" -Raw
+```
+
+Copy toàn bộ nội dung đó vào secret.
+
+## 3. `TAURI_UPDATER_ENDPOINT` là gì và setup thế nào
+
+Biến này là URL mà app sẽ dùng để check native updater.
+
+Trong workflow đã tạo sẵn, mình đặt:
+
+```text
+https://github.com/<owner>/<repo>/releases/latest/download/latest.json
+```
+
+Với repo này nó sẽ trở thành:
+
+```text
+https://github.com/holdon1996/dev-stack/releases/latest/download/latest.json
+```
+
+Bạn không cần tạo secret riêng cho biến này nếu giữ nguyên workflow hiện tại, vì workflow đã set trực tiếp trong `env`.
+
+Nếu sau này bạn muốn đổi sang CDN riêng hoặc update server riêng, sửa:
+
+[`release.yml`](/f:/dev-stack/.github/workflows/release.yml)
+
+dòng `TAURI_UPDATER_ENDPOINT`.
+
+## 3.1. Vì sao local build báo thiếu `pubkey`
+
+Tauri updater không chỉ đọc cấu hình ở runtime. Ngay lúc `tauri build`, bundler cũng sẽ parse:
+
+- `plugins.updater.pubkey`
+- `plugins.updater.endpoints`
+
+trong:
+
+[`tauri.conf.json`](/f:/dev-stack/src-tauri/tauri.conf.json)
+
+Nếu thiếu `pubkey`, build sẽ dừng với lỗi kiểu:
+
+```text
+failed to parse updater plugin configuration: missing field `pubkey`
+```
+
+Vì vậy file config phải luôn có 2 trường này.
+
+Hiện trong repo mình đã thêm sẵn:
+
+```json
+"updater": {
+  "pubkey": "PASTE_YOUR_TAURI_UPDATER_PUBLIC_KEY_HERE",
+  "endpoints": [
+    "https://github.com/holdon1996/dev-stack/releases/latest/download/latest.json"
+  ]
+}
+```
+
+Việc bạn cần làm là thay:
+
+`PASTE_YOUR_TAURI_UPDATER_PUBLIC_KEY_HERE`
+
+bằng đúng nội dung file:
+
+```powershell
+Get-Content "$HOME\.tauri\devstack.key.pub" -Raw
+```
+
+Lưu ý:
+
+- Đây là public key nên có thể commit vào repo.
+- Không dùng path file ở đây.
+- Phải là nội dung đầy đủ của public key trên một chuỗi string.
+
+## 4. Build release local để test
+
+Nếu muốn build local có updater native:
+
+```powershell
+$env:TAURI_SIGNING_PRIVATE_KEY = "$HOME\.tauri\devstack.key"
+$env:TAURI_SIGNING_PRIVATE_KEY_PASSWORD = "<password-của-bạn>"
+$env:TAURI_UPDATER_PUBKEY = Get-Content "$HOME\.tauri\devstack.key.pub" -Raw
+$env:TAURI_UPDATER_ENDPOINT = "https://github.com/holdon1996/dev-stack/releases/latest/download/latest.json"
+npm run tauri build
+```
+
+Hoặc dùng script đã tạo sẵn:
+
+[`set-updater-env.ps1`](/f:/dev-stack/scripts/set-updater-env.ps1)
+
+```powershell
+. .\scripts\set-updater-env.ps1
+npm run tauri build
+```
+
+Nếu muốn truyền password trực tiếp:
+
+```powershell
+. .\scripts\set-updater-env.ps1 -Password "<password-của-bạn>"
+npm run tauri build
+```
+
+Lưu ý:
+
+- `TAURI_SIGNING_PRIVATE_KEY` dùng path hoặc content đều được, theo docs Tauri.
+- `TAURI_UPDATER_PUBKEY` trong app hiện tại đang được nhúng vào lúc build, nên cần có trước `npm run tauri build`.
+- `.env` không được Tauri dùng cho signing key trong lúc build release.
+- Ngoài ra, trước khi build local bạn nên mở [`tauri.conf.json`](/f:/dev-stack/src-tauri/tauri.conf.json) và thay `pubkey` placeholder bằng public key thật.
+
+## 5. Release trên GitHub
+
+Workflow đã được tạo sẵn:
+
+[`release.yml`](/f:/dev-stack/.github/workflows/release.yml)
+
+Workflow này sẽ:
+
+- chạy khi push tag dạng `v*`
+- build bản Windows
+- ký updater artifacts
+- upload release assets lên GitHub Release
+- tạo `latest.json` để native updater dùng
+
+### Cách release
+
+Cập nhật version trước:
+
+- [`package.json`](/f:/dev-stack/package.json)
+- [`src-tauri/Cargo.toml`](/f:/dev-stack/src-tauri/Cargo.toml)
+- [`src-tauri/tauri.conf.json`](/f:/dev-stack/src-tauri/tauri.conf.json)
+
+Nên để cùng một version, ví dụ `1.0.1`.
+
+Sau đó tạo tag:
+
+```powershell
+git add .
+git commit -m "release: v1.0.1"
+git tag v1.0.1
+git push origin main
+git push origin v1.0.1
+```
+
+Khi workflow chạy xong, vào tab `Releases` trên GitHub để kiểm tra:
+
+- có file installer `.exe` và/hoặc `.msi`
+- có file `.sig`
+- có file `latest.json`
+
+## 6. App đang dùng updater như thế nào
+
+Nếu build có đầy đủ biến updater:
+
+- Settings sẽ hiện chế độ `Native auto-update`
+- app có thể check, download, install update ngay trong app
+
+Nếu build thiếu cấu hình updater:
+
+- Settings sẽ hiện `Manual download`
+- app vẫn check release mới nhất, nhưng sẽ mở trang tải về thay vì auto-install
+
+## 7. Nguồn tham khảo chính thức
+
+- Tauri updater guide: https://v2.tauri.app/plugin/updater/
+- Tauri updater JS API: https://v2.tauri.app/reference/javascript/updater/
+- tauri-plugin-updater README: https://docs.rs/crate/tauri-plugin-updater/latest/source/README.md
