> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cystack.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Cài đặt Endpoint Server

> Cài đặt Endpoint trên máy chủ (Dành cho bản Self-hosted)

Doanh nghiệp có thể tự triển khai và quản lý phần mềm CyStack Endpoint trên máy chủ của Doanh nghiệp theo hướng dẫn dưới đây.

<Note>**Lưu ý**: Hiện tại Endpoint Server chỉ hỗ trợ máy chủ Linux.</Note>

***

## Yêu cầu hệ thống

<Note>
  **Lưu ý chung**:

  * Máy chủ cần có IP công khai (Public IP).
  * Người dùng không nên ấn Ctrl + C trong quá trình cài đặt.
  * Mở các port để kết nối đến API của CyStack: 80, 443, 9900.
</Note>

### Trường hợp quản lý ít hơn 100 thiết bị

Cài tất cả các dịch vụ phụ thuộc redis, mySQL trực tiếp trên Server thì cần Server đáp ứng tối thiểu những yêu cầu như sau:

| **Số máy chủ** | **CPU (core)** | **RAM** | **Ổ đĩa (SSD)** |
| -------------- | -------------- | ------- | --------------- |
| 1              | 2              | 4GB     | 75GB            |

### Trường hợp quản lý từ 100 - 1000 thiết bị

**Trường hợp 1**: Cài tất cả các dịch vụ phụ thuộc redis, mySQL trực tiếp trên Server thì cần Server đáp ứng tối thiểu những yêu cầu như sau:

| Số máy chủ | CPU (core) | RAM   | Ổ đĩa SSD    |
| ---------- | ---------- | ----- | ------------ |
| 1          | 16         | 18 GB | 200 – 300 GB |

**Trường hợp 2**: Đối với các dịch vụ phụ thuộc redis, mySQL mà triển khai trong các Container thì yêu cầu tối thiểu về cấu hình của Container như sau:

| Thành phần                | Số container | CPU/container | RAM/container | Ổ đĩa SSD |
| ------------------------- | ------------ | ------------- | ------------- | --------- |
| Fleet                     | 1            | 1             | 4 GB          | -         |
| Redis 6                   | 3            | 2             | 2 GB          | -         |
| MySQL 8.0 (Aurora 3.07.1) | 2            | 2             | 5 GB          | 10 GB     |

***

## Hướng dẫn cài đặt

Khách hàng có thể cài đặt tự động CyStack\_Endpoint sử dụng **endpointCtl** (một file Binary).

<Steps>
  <Step title="Tải công cụ cài đặt">
    ```bash theme={null}
    mkdir -p ~/endpoint && cd ~/endpoint
    wget https://d.cystack.net/endpointctl/endpointctl
    ls -l
    ```

    <img src="https://mintcdn.com/cystack/K6A69VSj8YCZpFKp/images/endpoint/install-server-1.png?fit=max&auto=format&n=K6A69VSj8YCZpFKp&q=85&s=4233af60868f5884ce8bbfd92732a130" alt="install-server-1" style={{display: 'block', margin: '0 auto', marginBottom: '1rem'}} width="1590" height="240" data-path="images/endpoint/install-server-1.png" />

    <img src="https://mintcdn.com/cystack/K6A69VSj8YCZpFKp/images/endpoint/install-server-2.png?fit=max&auto=format&n=K6A69VSj8YCZpFKp&q=85&s=c431f0f5c102c1e8cb942e6a7bae72d9" alt="install-server-2" style={{display: 'block', margin: '0 auto'}} width="994" height="68" data-path="images/endpoint/install-server-2.png" />
  </Step>

  <Step title="Cấp quyền thực thi">
    ```bash theme={null}
    chmod +x endpointctl
    ```
  </Step>

  <Step title="Cài đặt">
    ```bash theme={null}
    ./endpointctl start
    ```

    Khi được yêu cầu, nhập mật khẩu root. Quá trình cài đặt mất khoảng 1–3 phút.
  </Step>

  <Step title="Lựa chọn hình thức cài đặt">
    **Tùy chọn 1:** Sử dụng cấu hình mặc định

    * Hệ thống tự tạo cơ sở dữ liệu, người dùng không cần can thiệp.
    * Nhập 1 và nhấn Enter.

    <img src="https://mintcdn.com/cystack/K6A69VSj8YCZpFKp/images/endpoint/install-server-4.png?fit=max&auto=format&n=K6A69VSj8YCZpFKp&q=85&s=acb5257b70ee1767fda3078b3bada36f" alt="install-server-4" style={{display: 'block', margin: '0 auto'}} width="1293" height="260" data-path="images/endpoint/install-server-4.png" />

    **Tùy chọn 2:** Dùng <code>MySQL</code> có sẵn của doanh nghiệp

    * Nhập <code>2</code> và nhấn <code>Enter</code>.
    * Chuẩn bị sẵn thông tin sau:

    | Trường                                 | Ví dụ                                       |
    | -------------------------------------- | ------------------------------------------- |
    | MySQL Host                             | localhost                                   |
    | MySQL Port                             | 3306                                        |
    | Database/User/Password cho các dịch vụ | ces\_fleet / ces\_api / ces\_data\_labeling |
  </Step>

  <Step title="Nhập thông tin Workspace">
    Sau khi MySQL cấu hình xong, hệ thống yêu cầu nhập:

    ```
    Work Space ID
    Work Space Secret
    ```

    (CyStack sẽ cung cấp 2 giá trị này)

    Thời gian cài đặt: 3–10 phút (tùy cấu hình server).
    Khi hoàn tất, chương trình sẽ hiển thị danh sách dịch vụ đang chạy.

    <img src="https://mintcdn.com/cystack/K6A69VSj8YCZpFKp/images/endpoint/install-server-5.png?fit=max&auto=format&n=K6A69VSj8YCZpFKp&q=85&s=77ab222bb6b0642e490b2276649175f9" alt="install-server-5" style={{display: 'block', margin: '0 auto'}} width="1576" height="1026" data-path="images/endpoint/install-server-5.png" />
  </Step>

  <Step title="Sau khi cài đặt">
    ✅ Kiểm tra file agent

    Sau khi hoàn tất, file agent được tạo tự động:

    ```bash theme={null}
    cystack-endpoint_<phiên bản>_amd64.deb
    ```

    ✅ Tự động cập nhật định kỳ

    Chạy:

    ```
    nohup ./endpointctl update > endpoint_updater.log 2>&1 &
    ```
  </Step>
</Steps>

***

## Hướng dẫn sử dụng endpointctl

### Danh sách các tham số và cờ

| Lệnh                           | Mô tả                                                                                             |
| ------------------------------ | ------------------------------------------------------------------------------------------------- |
| `./endpointctl start`          | Cài đặt Endpoint. Có thể thêm `--config` (đường dẫn file cấu hình) hoặc `--re-config` để cài lại. |
| `./endpointctl stop`           | Dừng toàn bộ service.                                                                             |
| `./endpointctl status`         | Xem trạng thái các service.                                                                       |
| `./endpointctl backup`         | Tạo file `.zip` chứa bản sao cơ sở dữ liệu tại `~/.cystack/endpoint_server/backupdb/`.            |
| `./endpointctl restore <path>` | Phục hồi cơ sở dữ liệu từ file `.zip`.                                                            |
| `./endpointctl update`         | Cập nhật tự động hàng ngày. Có thể chạy nền bằng `nohup`.                                         |

### Một số trường hợp lỗi

#### ❌ Container báo “Unhealthy”

* Nguyên nhân: server yếu hoặc lỗi cấu hình database.
* Cách xử lý:
  * Kiểm tra log container:
    ```bash theme={null}
    docker logs -f ces_fleet_container
    ```

  * Nếu migrate xong {'\u2192'} chạy lại:
    ```bash theme={null}
    ./endpointctl start --re-config
    ```

  * Nếu lỗi database {'\u2192'} xóa config và cài lại từ đầu.

#### ⚠️ Lỗi thiếu config

{'\u2192'} Chạy `./endpointctl start` để tạo file config gốc, sau đó chỉnh sửa và dùng lại.

#### ⚙️ Backup lâu

{'\u2192'} Do cấu hình server yếu. Hãy kiên nhẫn chờ hoàn tất.

#### 🔑 Lỗi khi lấy Token

{'\u2192'} Liên hệ **CyStack Support**.

#### 🌐 Lỗi domain (Caddy)

* Kiểm tra log:
  ```bash theme={null}
  docker logs -f caddy_container
  ```

* Nếu:
  * Domain chưa trỏ đúng IP {'\u2192'} cập nhật DNS.
  * Domain bị giới hạn SSL {'\u2192'} đổi domain khác.