# Bắt đầu nhanh

Để agent lập trình giúp bạn đưa ứng dụng lên mạng. Mở project trong agent bạn đang dùng, rồi sao chép một prompt này:

```text
Hãy giúp tôi deploy ứng dụng trong project này bằng 2server. Đọc https://2found.dev/vi/docs/2server.md và tự tìm hiểu thêm tại https://github.com/2found/2server khi cần.
Kiểm tra project, chuẩn bị container image và cấu hình triển khai, rồi hướng dẫn tôi hoàn tất những phần còn thiếu.
Trước hết giúp tôi chọn: dùng VM sẵn có, hoặc để 2server chạy Terraform tạo VM trong tài khoản Google Cloud hay AWS của tôi. Nếu tôi chưa có cả hai, hướng dẫn tạo tài khoản, bật billing và đăng nhập. Giải thích tài nguyên và chi phí dự kiến trước khi tạo.
Tiếp theo giúp tôi đưa tên miền lên Cloudflare và tạo API Token giới hạn đúng quyền cần dùng. Hướng dẫn tôi lưu thông tin bí mật vào file cục bộ riêng tư; đừng yêu cầu dán secret vào chat.
Validate và lập kế hoạch triển khai, giải thích các thay đổi, rồi deploy trong phạm vi tôi cho phép. Kiểm tra ứng dụng sẵn sàng và HTTPS công khai. Báo URL đang hoạt động hoặc chính xác phần còn vướng, không hiển thị thông tin bí mật.
```

Bạn có thể bắt đầu ngay, không cần cài plugin agent trước. Agent đọc được docs và chạy được lệnh terminal có thể làm theo hướng dẫn này. [Plugin Claude và Codex](https://2found.dev/docs/2server/agent-plugins/) là lựa chọn bổ sung để có hướng dẫn vận hành dùng lại được.

## Bạn và agent cần chuẩn bị gì?

Với ứng dụng có tên miền công khai, có hai việc cần giải quyết: **một máy chủ để chạy app** và **quyền Cloudflare để nối tên miền**. Agent chuẩn bị cấu hình và lệnh. Bạn chọn tài khoản, duyệt chi phí cloud và hoàn tất đăng nhập trên trình duyệt hoặc tạo token.

Chuẩn bị project và chọn hostname muốn dùng. Nếu chưa có tên miền, hãy đăng ký trước; agent có thể giúp bạn thêm tên miền vào Cloudflare sau đó. Việc build container và thiết lập registry có thể thực hiện trong quá trình triển khai.

## 1. Chọn nơi chạy ứng dụng

Dùng thứ bạn đã có. Không cần cả Google Cloud lẫn AWS.

| Bạn đang có gì? | Bạn cung cấp | Agent giúp làm gì? |
| --- | --- | --- |
| VM sẵn có | SSH host, username và đường dẫn key cục bộ, hoặc thông tin kết nối GCP IAP | Kiểm tra quyền truy cập và yêu cầu máy chủ; kết nối VM đã được quản lý hoặc bootstrap VM mới |
| Tài khoản Google Cloud | Project, region và quyền tạo tài nguyên | Hướng dẫn đăng nhập, chuẩn bị đầu vào Terraform, xem kế hoạch và tạo VM qua 2server |
| Tài khoản AWS | Account/profile, region và quyền tạo tài nguyên | Hướng dẫn đăng nhập, chọn image phù hợp và thiết lập SSH, xem kế hoạch và tạo VM qua 2server |
| Chưa có VM hay tài khoản cloud | Lựa chọn Google Cloud hoặc AWS | Hướng dẫn tạo tài khoản, bật billing và đăng nhập cục bộ, rồi đi tiếp theo nhánh tương ứng |

### Dùng VM sẵn có

VM cần Debian 12/13 hoặc Ubuntu 22.04/24.04, Python 3, SSH bằng key với host key đã xác thực và sudo không hỏi mật khẩu. VM phải kéo được container image bằng tài khoản root. Chỉ cung cấp **đường dẫn key**, không gửi nội dung key. Agent cần kiểm tra máy chủ hiện có trước khi thay đổi.

Với VM đã được 2server quản lý:

```sh
2srv connect --ssh ubuntu@vm.example --identity ~/.ssh/server_key
```

Với máy chủ mới, agent sinh manifest rỗng và điền thông tin SSH trước khi bootstrap:

```sh
2srv init server my-server -o server.local.json
2srv server bootstrap -f server.local.json --env-file /private/cloudflare.env --apply
```

Giữ `server.local.json` và `.2server/` riêng tư, loại khỏi Git. Bootstrap dành cho manifest máy chủ rỗng và VM chưa có trạng thái 2server đã công bố; kết nối một deployment hiện có không cần bootstrap.

### Tạo VM qua Google Cloud hoặc AWS

Bạn hoàn tất billing và đăng nhập tương tác. Agent có thể giúp cài CLI của nhà cung cấp cùng Terraform, xác nhận account/project và chuẩn bị đầu vào riêng tư. Ưu tiên nhà cung cấp bạn đang dùng; nếu chọn mới, hãy so sánh chi phí VM, ổ đĩa và IP công khai trong kế hoạch. Nhà cung cấp cloud tính phí tài nguyên của bạn.

Trên Google Cloud, Terraform cục bộ dùng [Application Default Credentials](https://docs.cloud.google.com/docs/terraform/authentication), thường thiết lập bằng `gcloud auth application-default login`. GCP IAP còn cần đăng nhập `gcloud` của người vận hành và quyền OS Login/IAP. Trên AWS, dùng profile cục bộ hiện có hoặc [đăng nhập IAM Identity Center](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) của tổ chức. Agent sẽ giúp xác định quyền còn thiếu theo nhánh bạn chọn.

Agent đọc [hướng dẫn provisioning](https://2found.dev/docs/2server/operator-guide/#provisioning) và đầu vào Terraform trong repository. GCP cần project; AWS còn cần AMI Debian/Ubuntu amd64 đã xác minh, SSH public key và giới hạn dải IP được SSH. Không dán credential cloud vào chat.

Ví dụ sau khi chuẩn bị đầu vào GCP:

```sh
2srv provision gcp /absolute/private/server.tfvars --output server.local.json
2srv provision gcp /absolute/private/server.tfvars --output server.local.json --apply
```

Lệnh đầu xem trước tài nguyên. Lệnh sau tạo tài nguyên khi bạn đã duyệt mục tiêu và chi phí. AWS dùng `provision aws` với SSH user phù hợp AMI. File đầu ra là manifest bootstrap riêng tư, chưa phải app đã triển khai. Giữ nguyên đường dẫn tuyệt đối của đầu vào và sao lưu Terraform state được báo; sau đó bootstrap như trên.

## 2. Cấp quyền Cloudflare cho 2server

“CF key” cần dùng ở đây là **API Token** được giới hạn quyền, lưu trong `CLOUDFLARE_API_TOKEN`. Global API Key hoặc Origin CA key không dùng thay thế được.

1. Đăng nhập [Cloudflare dashboard](https://dash.cloudflare.com/), thêm tên miền nếu cần và cập nhật nameserver tại nơi mua tên miền. Chờ zone chuyển sang **Active**; zone còn pending chưa dùng được cho luồng triển khai này.
2. Mở [My Profile → API Tokens](https://dash.cloudflare.com/profile/api-tokens), chọn **Create Token → Create Custom Token**. Token thuộc account tại **Manage Account → API Tokens** cũng được hỗ trợ; xem [hướng dẫn token](https://2found.dev/docs/2server/cloudflare-tokens/) cho nhánh này.
3. Đặt tên token theo deployment, chọn nhóm **Zone** cho cả năm dòng bên dưới và giới hạn **Zone Resources** vào đúng tên miền muốn triển khai. Chỉ dùng template Edit zone DNS là chưa đủ.

| Nhóm | Quyền | Mức truy cập |
| --- | --- | --- |
| Zone | Zone | Read |
| Zone | DNS | Edit |
| Zone | Zone Settings | Edit |
| Zone | Cache Rules / Cache Settings | Edit / Write theo dashboard |
| Zone | SSL and Certificates | Edit |

4. Kiểm tra phạm vi rồi tạo token. Dùng editor lưu trực tiếp giá trị vào file dotenv cục bộ riêng tư. Token chỉ hiển thị một lần. Đặt `CLOUDFLARE_API_TOKEN=<token của bạn>` trong file, giới hạn quyền file thành `0600` và giữ ngoài Git. Chỉ cho agent biết **đường dẫn file**. Xem [hướng dẫn tạo token của Cloudflare](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/) nếu tên mục trên dashboard khác.
5. Với máy chủ mới, đưa file vào `--env-file` lúc bootstrap. Với máy chủ đã kết nối, lưu token lên VM bằng:

```sh
2srv server env --env-file /private/cloudflare.env --apply
```

Agent có thể tạo file với biến rỗng và chỉ bạn chỗ cần điền. Agent xác nhận credential đã có mà không in giá trị. Các lệnh đã kết nối đọc token từ VM; export token trong shell trên laptop không thay thế credential còn thiếu trên VM.

Với app nội bộ chưa có tên miền công khai, có thể để Cloudflare sau: bỏ mục `domains` mẫu trong App file. Thêm lại khi cần HTTPS công khai. Workers, email routing và WAF cần phạm vi riêng; chỉ bổ sung quyền cho tính năng đang dùng theo [tài liệu token đầy đủ](https://2found.dev/docs/2server/cloudflare-tokens/).

## Triển khai ứng dụng đầu tiên

Chạy từ repository của ứng dụng. CLI cần Bun ≥ 1.3 và Node ≥ 20. Build image cần Docker cục bộ; chỉ cần Terraform nếu tạo VM. Agent có thể kiểm tra và giúp cài các công cụ trong quá trình chuẩn bị.

```sh
npm install -g @2server/cli
2srv help
2srv init app api -o api/2server/deploy.yaml
```

Điền image thật, port, endpoint kiểm tra sẵn sàng và giới hạn tài nguyên. Điền tên miền cùng Cloudflare zone, hoặc bỏ tên miền mẫu với app nội bộ. Build và đẩy image lên registry mà VM truy cập được. Commit App file; giữ riêng secret và file kết nối. Đọc [tài liệu App file](https://2found.dev/docs/2server/source-config/) khi cấu hình secret hoặc migration.

```sh
2srv validate -f api/2server/deploy.yaml
2srv plan -f api/2server/deploy.yaml
2srv deploy -f api/2server/deploy.yaml --apply
2srv app api get
```

`validate` chạy offline. `plan` kiểm tra VM, registry và tên miền khai báo; có thể kéo image nhưng không triển khai app, chạy migration hay chứng minh quyền ghi. Thay đổi từ xa cần `--apply`.

Deployment chờ app sẵn sàng trước khi chuyển truy cập, sau đó đồng bộ tên miền và kiểm tra HTTPS công khai. Agent cần báo URL quan sát được, tình trạng app và phần chưa hoàn tất. Một VM vẫn là một điểm lỗi chung; rollback truy cập không hoàn tác migration cơ sở dữ liệu. Đọc [độ tin cậy và khôi phục](https://2found.dev/docs/2server/reliability/) khi chuẩn bị production.

## Nếu bị vướng khi thiết lập

| Vướng ở đâu? | Bước tiếp theo |
| --- | --- |
| Chưa có tài khoản cloud hoặc chưa bật billing | Hoàn tất tài khoản/billing trên trình duyệt của nhà cung cấp; agent có thể chuẩn bị App file trong lúc chờ |
| SSH bị từ chối hoặc thiếu quyền provisioning | Kiểm tra identity cục bộ, account/project, SSH user và quyền cần thiết trước khi thử lại |
| Cloudflare zone pending hoặc token trả 401/403 | Kiểm tra nameserver, loại token, hạn dùng, phạm vi zone và quyền được báo thiếu; không cấp toàn bộ quyền account |
| App không qua readiness | Xem `2srv app api logs` và đường dẫn kiểm tra sẵn sàng trước khi thử lại |
| App chạy tốt nhưng DNS/TLS thất bại | Đọc trạng thái app/domain được báo, sửa vấn đề Cloudflare rồi lập kế hoạch lại; không mặc định toàn bộ release đã thất bại |

## Đọc tiếp

- [Mục lục tài liệu](https://2found.dev/docs/2server/reference/) — chọn tham chiếu theo công việc.
- [Hướng dẫn vận hành](https://2found.dev/docs/2server/operator-guide/) — truy cập máy chủ, tạo VM và vận hành hằng ngày.
- [Cấu hình nguồn](https://2found.dev/docs/2server/source-config/) — đầy đủ các contract App, Domain và Zone.
- [GitHub](https://github.com/2found/2server) — source, ví dụ, Terraform và skills cho agent.
- [Mục lục Markdown](https://2found.dev/docs/2server/llms.txt) — URL `.md` trực tiếp cho agent.