# Hướng dẫn deploy EmDash trên Cloudflare Workers

Trong bài viết trước của **Cẩm nang NQDEV**, chúng ta đã phân tích vì sao EmDash là một CMS đáng chú ý trong kỷ nguyên mới.\
Bây giờ, hãy đi vào phần thực tế hơn: **deploy EmDash lên Cloudflare Workers** – nơi nó phát huy đúng sức mạnh kiến trúc.

Bài viết này sẽ giúp bạn:

* Hiểu rõ cách EmDash chạy trên Workers
* Triển khai từng bước từ local → production
* Tránh các lỗi phổ biến khi deploy

***

## 1. Tổng quan kiến trúc deploy EmDash

Trước khi bắt tay vào làm, cần hiểu một điểm quan trọng:

👉 EmDash không chạy như CMS truyền thống (PHP + server)

Thay vào đó:

* Build bằng **Astro**
* Deploy lên **Cloudflare Workers**
* Plugin chạy trong **Worker isolates (sandbox)**

#### Kiến trúc đơn giản:

```
User Request → Cloudflare Edge → Worker → Render (Astro) → Response
```

👉 Điều này giúp:

* Tốc độ cực nhanh (Edge)
* Scale gần như không giới hạn
* Bảo mật tốt hơn

***

## 2. Chuẩn bị môi trường

### 2.1. Yêu cầu cần có

* Node.js >= 18
* npm hoặc pnpm
* Tài khoản Cloudflare
* Wrangler CLI

***

### 2.2. Cài đặt Wrangler

```
npm install -g wrangler
```

Đăng nhập:

```
wrangler login
```

👉 Sau bước này, bạn đã sẵn sàng deploy lên Cloudflare.

***

## 3. Clone và chạy EmDash local

### 3.1. Clone source

```
git clone https://github.com/emdash-cms/emdash.git
cd emdash
```

### 3.2. Cài dependencies

```
npm install
```

### 3.3. Chạy local

```
npm run dev
```

👉 Truy cập:

```
http://localhost:4321
```

#### Kiểm tra:

* Admin dashboard hoạt động
* Tạo bài viết thử
* Navigation mượt

***

## 4. Build project cho Cloudflare Workers

### 4.1. Build production

```
npm run build
```

Sau khi build:

* Output nằm trong thư mục `dist/`
* Astro đã tối ưu cho production

***

### 4.2. Cấu hình adapter cho Workers

EmDash sử dụng Astro → cần adapter Cloudflare

Kiểm tra file:

```
astro.config.mjs
```

Đảm bảo có:

```
import cloudflare from '@astrojs/cloudflare';

export default {
  adapter: cloudflare()
};
```

👉 Đây là bước quan trọng để chạy trên Workers.

***

## 5. Cấu hình Wrangler

### 5.1. Tạo file cấu hình

```
wrangler init
```

Hoặc tạo nhanh `wrangler.toml`:

```
name = "emdash-app"
main = "./dist/_worker.js"
compatibility_date = "2024-01-01"

[assets]
directory = "./dist"
```

***

### 5.2. Cấu hình bindings (nếu có)

Nếu EmDash dùng:

* KV
* R2
* D1

Bạn cần khai báo:

```
[[kv_namespaces]]
binding = "CACHE"
id = "your-kv-id"
```

👉 Đây là nơi plugin sẽ truy cập tài nguyên theo permission.

***

## 6. Deploy lên Cloudflare Workers

### 6.1. Deploy

```
wrangler deploy
```

Sau khi chạy:

* Cloudflare sẽ build Worker
* Cấp URL dạng:

```
https://emdash-app.your-subdomain.workers.dev
```

***

### 6.2. Kiểm tra

* Truy cập URL
* Test:
  * Trang blog
  * Admin dashboard
  * Tạo / sửa bài viết

👉 Nếu mọi thứ hoạt động → deploy thành công 🎉

***

## 7. Custom domain (tuỳ chọn)

Bạn có thể gắn domain riêng:

```
wrangler publish --route yourdomain.com/*
```

Hoặc cấu hình trong Cloudflare Dashboard:

* Workers → Routes
* Add domain

***

## 8. Những lỗi thường gặp & cách xử lý

### ❌ Lỗi 404 sau deploy

👉 Nguyên nhân:

* Sai đường dẫn `_worker.js`

✔ Fix:

* Kiểm tra `main` trong `wrangler.toml`

***

### ❌ Plugin không hoạt động

👉 Nguyên nhân:

* Chưa khai báo bindings / capabilities

✔ Fix:

* Kiểm tra manifest plugin
* Đảm bảo đúng scope

***

### ❌ Lỗi environment variables

👉 Fix:

```
wrangler secret put API_KEY
```

***

### ❌ Build lỗi Astro

👉 Fix:

* Kiểm tra version Node
* Xoá `node_modules` và cài lại

***

## 9. Tối ưu khi chạy production

Để tận dụng tối đa EmDash:

#### ✅ Sử dụng KV cache

* Cache nội dung blog
* Giảm thời gian render

#### ✅ Dùng R2 cho media

* Lưu ảnh, file upload
* Giảm chi phí

#### ✅ Phân quyền plugin rõ ràng

* Không cấp quyền dư thừa
* Theo nguyên tắc least privilege

***

## 10. Kết luận – Deploy chỉ là bước đầu

Triển khai EmDash trên Cloudflare Workers không quá phức tạp, nhưng giá trị thật nằm ở:

👉 **kiến trúc Edge + sandbox plugin**

Đây là nền tảng để bạn:

* Xây CMS an toàn hơn
* Scale dễ dàng hơn
* Tối ưu trải nghiệm người dùng

***

### Góc nhìn từ Cẩm nang NQDEV

Tại **Cẩm nang NQDEV**, chúng tôi tin rằng:

> Deploy không chỉ là đưa code lên server, mà là lựa chọn kiến trúc phù hợp ngay từ đầu.

EmDash + Cloudflare Workers chính là một ví dụ rõ ràng cho hướng đi:

* Serverless-first
* Security-by-design
* Performance-native

Nếu bạn đang phát triển sản phẩm trên **NQDEV Platform**, hãy thử triển khai EmDash để cảm nhận sự khác biệt.

***

📚 Xem thêm các bài viết chuyên sâu tại:\
👉 <https://blogs.nhquydev.net/>