# 快速開始

本頁帶你從編譯、設定到第一次用 `podrun up` 把 compose 專案部署到遠端 Podman。

## 前置需求

| 需求 | 位置 | 說明 |
|---|---|---|
| Go 1.25.1+ | 編譯端 | 版本取自 `go.mod` |
| C 編譯器（`CGO_ENABLED=1`） | 編譯端（API Server） | `github.com/mattn/go-sqlite3` 需要 cgo |
| `sshpass`、`rsync`、`ssh`、`curl`、`unzip` | 本地（CLI） | 缺少時 `CheckRelyPackages()` 會自動安裝 |
| macOS 或 Linux | 本地（CLI） | 其他作業系統在缺套件時直接中止 |
| SSH 密碼登入 | 遠端主機 | CLI 以 `sshpass` 帶密碼連線 |
| Podman + `podman compose` | 遠端主機 | 容器執行環境 |
| `/home/podrun` 寫入權限 | 遠端主機 | 遠端專案目錄固定建立於此 |

## 安裝

```bash
git clone https://github.com/pardnchiu/PodRun.git
cd PodRun
go build -o podrun ./cmd/cli
CGO_ENABLED=1 go build -o podrun-api ./cmd/api
```

只需要 CLI 時可用 `go install`，產出的執行檔名稱為 `cli`（取自套件目錄名）：

```bash
go install github.com/pardnchiu/PodRun/cmd/cli@latest
```

## 設定遠端連線

CLI 啟動時從當前工作目錄的 `.env` 讀取三個必填變數，缺任何一個都會中止：

```dotenv
PODRUN_SERVER=192.168.1.100
PODRUN_USERNAME=podrun
PODRUN_PASSWORD=yourpassword
```

完整變數見 [設定](/zh/configuration)。

## 啟動 API Server

API Server 以相對路徑讀取 `sql/create.sql` 建表，必須在 repo 根目錄執行；CLI 固定連往 `localhost:8080`，兩者要在同一台機器。

```bash
cd PodRun
./podrun-api
```

## 第一次部署

在含 `docker-compose.yml` 或 `docker-compose.yaml` 的專案目錄執行：

```bash
cd ~/projects/my-app
podrun up -d
```

`-d` 模式完成後會印出各容器的 Port 對應、Pod ID／名稱與本機 Hostname／IP。之後可用維運指令：

```bash
podrun ps
podrun logs -f
podrun down
podrun clear
```

## 下一步

- [核心概念](/zh/core-concepts)：UID 與遠端目錄如何決定
- [檔案同步](/zh/file-sync)：差異預覽與排除規則
- [命令列參考](/zh/cli-reference)：所有指令與旗標