# Docker Compose

使用官方控制器映像檔、搭配 TimescaleDB 的 PostgreSQL 與自動遷移功能安裝 Netstamp。

若要自行託管 Netstamp，建議先從程式碼儲存庫提供的標準 Compose 部署開始。它會執行三個服務：

| 服務       | 用途                                                        |
| ---------- | ----------------------------------------------------------- |
| `postgres` | PostgreSQL 16、TimescaleDB，以及保存資料的 named volume     |
| `migrate`  | 使用相同 Netstamp 映像檔版本執行一次性的資料庫遷移          |
| `netstamp` | 控制器、內嵌 React 應用程式、API，以及 Linux 探測器安裝資源 |

## 下載並設定

```bash
mkdir -p /opt/netstamp
cd /opt/netstamp
curl -fsSLO https://raw.githubusercontent.com/yorukot/netstamp/main/deployments/docker/compose.yaml
curl -fsSLO https://raw.githubusercontent.com/yorukot/netstamp/main/deployments/docker/example.env
cp example.env .env
chmod 600 .env
```

產生五組彼此獨立的密鑰：

```bash
openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32
```

將不同的隨機值分別填入 `.env` 下列欄位：

```dotenv
DATABASE_PASSWORD=<random value>
LOG_PSEUDONYM_KEY=<random value>
SYSTEM_SETTINGS_ENCRYPTION_KEY=<random value>
AUTH_SESSION_HASH_KEY=<random value>
AUTH_API_TOKEN_HASH_KEY=<random value>
```

重新啟動或升級時必須沿用這些值。變更 hash key 會讓對應憑證失效；變更系統設定加密金鑰，則可能導致已儲存的 SMTP 憑證無法解密。

## 啟動服務

```bash
docker compose pull
docker compose up -d
docker compose ps
docker compose logs migrate
```

正常狀態如下：

- `postgres` 顯示 healthy；
- `migrate` 以狀態碼 0 結束；
- `netstamp` 持續執行；
- 設定的連接埠可回應 `/healthz` 與 `/api/v1/healthz`。

```bash
curl --fail http://127.0.0.1:3000/healthz
curl --fail http://127.0.0.1:3000/api/v1/healthz
```

## 選擇映像檔與版本

預設值如下：

```dotenv
NETSTAMP_IMAGE=yorukot/netstamp
NETSTAMP_VERSION=latest
TIMESCALEDB_IMAGE=timescale/timescaledb:latest-pg16
NETSTAMP_PORT=3000
```

`latest` 適合試用。正式或受控環境應將 `NETSTAMP_VERSION` 與 `TIMESCALEDB_IMAGE` 固定在已測試、不可變動的 release tag 或 digest。遷移與應用程式服務必須使用相同的 Netstamp 版本。

## 持久化資料

資料庫存放在 Compose 中邏輯名稱為 `netstamp-postgres` 的 volume；Docker 通常會在實際名稱前加上 Compose project name。移除 container 不會刪除 volume。除非確定要銷毀所有專案、使用者、探測器、結果、事件與設定，否則不要執行 `docker compose down -v`。

列出並檢查 volume：

```bash
docker volume ls --filter name=netstamp-postgres
docker compose exec postgres psql -U netstamp -d netstamp -c 'select now();'
```

## 建置自訂映像檔

發布的映像檔包含控制器、遷移工具、網頁應用程式，以及 amd64/arm64 探測器執行檔。若要從 checkout 建置相同映像檔：

```bash
docker build -f deployments/docker/Dockerfile -t netstamp:local .
NETSTAMP_IMAGE=netstamp NETSTAMP_VERSION=local docker compose up -d
```

前端的 `VITE_NETSTAMP_*` 功能旗標會在建置時寫入。製作自訂映像檔時，請透過 Docker 建置參數修改；在已建置完成的容器中新增執行階段環境變數，不會改變前端內容。

## 接下來

將服務公開到網際網路之前，請完成[正式環境部署](/zh-TW/docs/install/production/)中的所有項目。