Skip to content

Commit 1d34e80

Browse files
codeboyzhoucodeboyzhou
authored
Merge pull request #18 from codeboyzhou/feat/ghcr-release-install
feat: GHCR release images and no-clone Docker install
2 parents 3edd9be + 7274925 commit 1d34e80

6 files changed

Lines changed: 480 additions & 46 deletions

File tree

‎.github/workflows/docker-publish.yml‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: Publish Docker images to GHCR
2+
3+
on:
4+
push:
5+
tags: ["v*"]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
packages: write
11+
12+
env:
13+
REGISTRY: ghcr.io
14+
15+
jobs:
16+
build-and-push:
17+
runs-on: ubuntu-latest
18+
strategy:
19+
fail-fast: false
20+
matrix:
21+
include:
22+
- context: backend
23+
dockerfile: Dockerfile
24+
image: video-driven-skill-backend
25+
- context: frontend
26+
dockerfile: Dockerfile
27+
image: video-driven-skill-frontend
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
32+
- name: Set up Docker Buildx
33+
uses: docker/setup-buildx-action@v3
34+
35+
- name: Log in to GHCR
36+
uses: docker/login-action@v3
37+
with:
38+
registry: ${{ env.REGISTRY }}
39+
username: ${{ github.actor }}
40+
password: ${{ secrets.GITHUB_TOKEN }}
41+
42+
- name: Extract metadata
43+
id: meta
44+
uses: docker/metadata-action@v5
45+
with:
46+
images: ${{ env.REGISTRY }}/${{ github.repository_owner }}/${{ matrix.image }}
47+
tags: |
48+
type=semver,pattern={{major}},prefix=v
49+
type=semver,pattern={{major}}.{{minor}},prefix=v
50+
type=semver,pattern={{version}},prefix=v
51+
type=ref,event=tag
52+
type=raw,value=latest
53+
54+
- name: Build and push
55+
uses: docker/build-push-action@v6
56+
with:
57+
context: ./${{ matrix.context }}
58+
file: ./${{ matrix.context }}/${{ matrix.dockerfile }}
59+
push: true
60+
tags: ${{ steps.meta.outputs.tags }}
61+
labels: ${{ steps.meta.outputs.labels }}
62+
cache-from: type=gha
63+
cache-to: type=gha,mode=max

‎README.md‎

Lines changed: 108 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -57,15 +57,109 @@ The project is designed for teams and individuals who want automation to start f
5757

5858
### Docker (recommended)
5959

60-
Install [Docker](https://docs.docker.com/get-docker/), then clone the repository:
60+
First, install [Docker](https://docs.docker.com/get-docker/).
61+
62+
Pick the path that matches your goal:
63+
64+
| I want to… | You need | Steps |
65+
|------------------------------------------------------------------|--------------------|----------------------------------------------------|
66+
| **Run the app quickly** — no Git, no local build | Docker only | [Pre-built images](#pre-built-images-end-users) |
67+
| **Hack on the code** — latest `main`, or China mirror for builds | Docker + Git clone | [Build from source](#build-from-source-developers) |
68+
69+
---
70+
71+
#### Pre-built images (end users)
72+
73+
**What this does:** Downloads `docker-compose.release.yml` and `.env` into a fixed folder, pulls **ready-made** images from GitHub Container Registry (GHCR), and starts the stack. You do **not** clone this repository.
74+
75+
**Install location**
76+
77+
| OS | Default directory |
78+
|---------------|------------------------------------|
79+
| macOS / Linux | `~/video-driven-skill` |
80+
| Windows | `%USERPROFILE%\video-driven-skill` |
81+
82+
**1. Install and start**
83+
84+
macOS / Linux:
85+
86+
```bash
87+
curl -fsSL https://raw.githubusercontent.com/ingorewho/video-driven-skill/main/scripts/install.sh | bash
88+
```
89+
90+
Windows (PowerShell):
91+
92+
```powershell
93+
irm https://raw.githubusercontent.com/ingorewho/video-driven-skill/main/scripts/install.ps1 | iex
94+
```
95+
96+
If you already cloned the repo, run `./scripts/install.sh` or `.\scripts\install.ps1` from the project instead.
97+
98+
The script pulls images, starts containers, and opens `http://localhost:3000` when the UI is ready.
99+
100+
**2. Configure AI (required for generation features)**
101+
102+
On first run, `.env` is created from `.env.example`. Edit it and set:
103+
104+
```env
105+
AI_API_KEY=your-key-here
106+
```
107+
108+
**3. Choose a version (optional)**
109+
110+
| Tag | When to use |
111+
|--------------------|--------------------------------------------------------------------------------------|
112+
| `latest` (default) | Track the newest [release](https://github.com/ingorewho/video-driven-skill/releases) |
113+
| `v1.0.0` (example) | Pin a specific release in production |
114+
115+
```bash
116+
./scripts/install.sh --tag v1.0.0
117+
```
118+
119+
Or set `VD_SKILL_IMAGE_TAG=v1.0.0` when running `docker compose -f docker-compose.release.yml …`.
120+
121+
**How images are published**
122+
123+
- Registry: `ghcr.io/ingorewho/video-driven-skill-backend` and `ghcr.io/ingorewho/video-driven-skill-frontend`
124+
- **A new image is built only when a version Git tag is pushed** (e.g. `v1.0.0`, `v1.2.3`). Pushes to `main` alone do **not** publish images.
125+
- Tag `latest` on GHCR always points to the **most recent** `v*` release.
126+
127+
> **First release not out yet?** GHCR will have no images until the project tags its first release (e.g. `v1.0.0`). Until then, use [build from source](#build-from-source-developers) below.
128+
129+
**Install script options**
130+
131+
| Option | Description | Default |
132+
|-------------|---------------------------------------------------|------------------------|
133+
| `--dir` | Install directory | `~/video-driven-skill` |
134+
| `--tag` | Image tag on GHCR (`latest` or `v1.0.0`, …) | `latest` |
135+
| `--port` | Web UI port | `3000` |
136+
| `--ref` | Git ref used to download compose / `.env.example` | `main` |
137+
| `--no-open` | Do not open the browser when ready | off |
138+
139+
**Manual install (no install script)**
140+
141+
```bash
142+
mkdir -p ~/video-driven-skill && cd ~/video-driven-skill
143+
curl -fsSL https://raw.githubusercontent.com/ingorewho/video-driven-skill/main/docker-compose.release.yml -o docker-compose.release.yml
144+
curl -fsSL https://raw.githubusercontent.com/ingorewho/video-driven-skill/main/.env.example -o .env
145+
# Edit .env — set AI_API_KEY
146+
docker compose -f docker-compose.release.yml pull
147+
docker compose -f docker-compose.release.yml up -d
148+
```
149+
150+
**Update to a newer release:** run the install script again, or `docker compose -f docker-compose.release.yml pull && docker compose -f docker-compose.release.yml up -d` with the desired `VD_SKILL_IMAGE_TAG`.
151+
152+
---
153+
154+
#### Build from source (developers)
155+
156+
**What this does:** Clones the repo and **builds** images locally with `docker-compose.yml`. Use this when you are developing, need unreleased `main`, or want the China mirror overlay for faster base-image pulls.
61157

62158
```bash
63159
git clone https://github.com/ingorewho/video-driven-skill.git
64160
cd video-driven-skill
65161
```
66162

67-
Run from the project root:
68-
69163
**Windows**
70164

71165
```bat
@@ -79,9 +173,9 @@ chmod +x scripts/run-in-docker.sh
79173
./scripts/run-in-docker.sh
80174
```
81175

82-
**Edit `.env` and set `AI_API_KEY` on first run.**
176+
On first run, `.env` is created from `.env.example` — set `AI_API_KEY` before using AI features.
83177

84-
**If you are in China, recommend using the fast mirror:**
178+
**China — faster local builds** (base images only; does not apply to the GHCR install path above):
85179

86180
```bat
87181
.\scripts\run-in-docker.cmd --cn
@@ -91,17 +185,7 @@ chmod +x scripts/run-in-docker.sh
91185
./scripts/run-in-docker.sh --cn
92186
```
93187

94-
Custom port: set `FRONTEND_PORT=3000` in `.env`.
95-
96-
Start without opening a browser:
97-
98-
```bat
99-
.\scripts\run-in-docker.cmd --no-open
100-
```
101-
102-
```bash
103-
./scripts/run-in-docker.sh --no-open
104-
```
188+
**Options:** `FRONTEND_PORT=3000` in `.env` to change the UI port; pass `--no-open` to skip opening the browser.
105189

106190
---
107191

@@ -125,14 +209,15 @@ Start without opening a browser:
125209
video-driven-skill/
126210
├── backend/ # Spring Boot — API, video processing, AI, skill runner
127211
├── frontend/ # React + Vite — studio UI
128-
├── docker-compose.yml # One-command Docker deployment
129-
├── docker-compose.cn.yml # Optional mirror overlay (slow Docker Hub)
130-
├── ARCHITECTURE.md # Architecture (English)
131-
├── ARCHITECTURE.zh-CN.md # Architecture (Chinese)
212+
├── docker-compose.yml # Docker deployment (build from source)
213+
├── docker-compose.release.yml # GHCR images (no clone)
214+
├── docker-compose.cn.yml # Optional mirror overlay (local build)
215+
├── ARCHITECTURE.md # Architecture (English)
216+
├── ARCHITECTURE.zh-CN.md # Architecture (Chinese)
132217
├── scripts/
133-
│ ├── run-in-docker.cmd # Docker start + open browser (Windows)
134-
│ ├── run-in-docker.sh # Docker start + open browser (Unix)
135-
│ └── kill-midscene.sh # Optional cleanup helper
218+
│ ├── install.sh / install.ps1 # Install from GHCR (no clone)
219+
│ ├── run-in-docker.cmd / .sh # Build & run from source
220+
│ └── kill-midscene.sh # Optional cleanup helper
136221
```
137222

138223
### Backend (Spring Boot / Java 17)

‎README.zh-CN.md‎

Lines changed: 108 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -57,15 +57,109 @@ Video Driven Skill 是一套开源的**自动化工作室**：把**屏幕录屏*
5757

5858
### Docker（推荐）
5959

60-
安装 [Docker](https://docs.docker.com/get-docker/)，克隆仓库：
60+
首先，安装 [Docker](https://docs.docker.com/get-docker/)。
61+
62+
根据你的目标选择安装方式：
63+
64+
| 我的需求 | 需要准备 | 对应章节 |
65+
|----------|----------|----------|
66+
| **尽快跑起来** — 不克隆仓库、不本地编译 | 仅需 Docker | [预构建镜像](#预构建镜像普通用户) |
67+
| **改代码或跟 main** — 需要最新未发版代码，或国内加速本地构建 | Docker + Git 克隆 | [从源码构建](#从源码构建开发者) |
68+
69+
---
70+
71+
#### 预构建镜像（普通用户）
72+
73+
**做什么：** 在固定目录下载 `docker-compose.release.yml` 与 `.env`，从 GitHub Container Registry（GHCR）拉取**已构建好的**镜像并启动。**无需**克隆本仓库。
74+
75+
**安装目录**
76+
77+
| 系统 | 默认路径 |
78+
|------|----------|
79+
| macOS / Linux | `~/video-driven-skill` |
80+
| Windows | `%USERPROFILE%\video-driven-skill` |
81+
82+
**1. 安装并启动**
83+
84+
macOS / Linux：
85+
86+
```bash
87+
curl -fsSL https://raw.githubusercontent.com/ingorewho/video-driven-skill/main/scripts/install.sh | bash
88+
```
89+
90+
Windows（PowerShell）：
91+
92+
```powershell
93+
irm https://raw.githubusercontent.com/ingorewho/video-driven-skill/main/scripts/install.ps1 | iex
94+
```
95+
96+
若已克隆仓库，可在项目根目录执行 `./scripts/install.sh` 或 `.\scripts\install.ps1`。
97+
98+
脚本会拉取镜像、启动容器，并在 UI 就绪后打开 `http://localhost:3000`。
99+
100+
**2. 配置 AI（使用生成功能前必填）**
101+
102+
首次运行会从 `.env.example` 生成 `.env`，编辑并填写：
103+
104+
```env
105+
AI_API_KEY=你的密钥
106+
```
107+
108+
**3. 选择版本（可选）**
109+
110+
| 镜像标签 | 适用场景 |
111+
|----------|----------|
112+
| `latest`（默认） | 始终使用最新 [Release](https://github.com/ingorewho/video-driven-skill/releases) |
113+
| `v1.0.0`（示例） | 生产环境固定某一发行版 |
114+
115+
```bash
116+
./scripts/install.sh --tag v1.0.0
117+
```
118+
119+
或在执行 `docker compose -f docker-compose.release.yml …` 时设置 `VD_SKILL_IMAGE_TAG=v1.0.0`。
120+
121+
**镜像如何发布**
122+
123+
- 镜像地址：`ghcr.io/ingorewho/video-driven-skill-backend`、`ghcr.io/ingorewho/video-driven-skill-frontend`
124+
- **仅在推送版本 Git 标签时构建**（如 `v1.0.0`、`v1.2.3`）。仅推送到 `main` **不会**产生新镜像。
125+
- GHCR 上的 `latest` 标签始终指向**最近一次** `v*` 发行版。
126+
127+
> **还没有任何 Release？** 在仓库打出第一个版本标签（如 `v1.0.0`）之前，GHCR 上没有可用镜像。请暂时使用下文 [从源码构建](#从源码构建开发者)。
128+
129+
**安装脚本参数**
130+
131+
| 参数 | 说明 | 默认值 |
132+
|------|------|--------|
133+
| `--dir` | 安装目录 | `~/video-driven-skill` |
134+
| `--tag` | GHCR 镜像标签（`latest` 或 `v1.0.0` 等） | `latest` |
135+
| `--port` | Web UI 端口 | `3000` |
136+
| `--ref` | 下载 compose / `.env.example` 时使用的 Git 引用 | `main` |
137+
| `--no-open` | 就绪后不自动打开浏览器 | 关闭 |
138+
139+
**手动安装（不用安装脚本）**
140+
141+
```bash
142+
mkdir -p ~/video-driven-skill && cd ~/video-driven-skill
143+
curl -fsSL https://raw.githubusercontent.com/ingorewho/video-driven-skill/main/docker-compose.release.yml -o docker-compose.release.yml
144+
curl -fsSL https://raw.githubusercontent.com/ingorewho/video-driven-skill/main/.env.example -o .env
145+
# 编辑 .env — 填写 AI_API_KEY
146+
docker compose -f docker-compose.release.yml pull
147+
docker compose -f docker-compose.release.yml up -d
148+
```
149+
150+
**升级到新版：** 再次运行安装脚本，或执行 `docker compose -f docker-compose.release.yml pull && docker compose -f docker-compose.release.yml up -d`，并指定目标 `VD_SKILL_IMAGE_TAG`。
151+
152+
---
153+
154+
#### 从源码构建（开发者）
155+
156+
**做什么：** 克隆仓库后使用 `docker-compose.yml` **本地构建**镜像。适合开发调试、需要未发版的 `main`，或使用国内镜像加速**本地构建**（与上方 GHCR 安装无关）。
61157

62158
```bash
63159
git clone https://github.com/ingorewho/video-driven-skill.git
64160
cd video-driven-skill
65161
```
66162

67-
在项目根目录执行：
68-
69163
**Windows**
70164

71165
```bat
@@ -79,9 +173,9 @@ chmod +x scripts/run-in-docker.sh
79173
./scripts/run-in-docker.sh
80174
```
81175

82-
**首次运行请编辑 `.env` 设置 `AI_API_KEY`。**
176+
首次运行会从 `.env.example` 生成 `.env` — 使用 AI 功能前请设置 `AI_API_KEY`。
83177

84-
**如果你在中国大陆，建议使用国内镜像加速：**
178+
**中国大陆 — 加速本地构建**（仅影响基础镜像拉取，不适用于上方 GHCR 预构建安装）：
85179

86180
```bat
87181
.\scripts\run-in-docker.cmd --cn
@@ -91,17 +185,7 @@ chmod +x scripts/run-in-docker.sh
91185
./scripts/run-in-docker.sh --cn
92186
```
93187

94-
改端口：在 `.env` 中设置 `FRONTEND_PORT=3000`。
95-
96-
不自动打开浏览器：
97-
98-
```bat
99-
.\scripts\run-in-docker.cmd --no-open
100-
```
101-
102-
```bash
103-
./scripts/run-in-docker.sh --no-open
104-
```
188+
**其他：** 在 `.env` 中设置 `FRONTEND_PORT=3000` 可改 UI 端口；加 `--no-open` 则不自动打开浏览器。
105189

106190
---
107191

@@ -125,14 +209,15 @@ chmod +x scripts/run-in-docker.sh
125209
video-driven-skill/
126210
├── backend/ # Spring Boot — API、视频处理、AI、技能运行器
127211
├── frontend/ # React + Vite — 工作室前端
128-
├── docker-compose.yml # 一键 Docker 部署
129-
├── docker-compose.cn.yml # 可选：国内镜像加速
130-
├── ARCHITECTURE.md # 架构说明（英文）
131-
├── ARCHITECTURE.zh-CN.md # 架构说明（中文）
212+
├── docker-compose.yml # Docker 部署（本地构建）
213+
├── docker-compose.release.yml # GHCR 预构建镜像（免克隆）
214+
├── docker-compose.cn.yml # 可选：国内基础镜像加速（本地构建）
215+
├── ARCHITECTURE.md # 架构说明（英文）
216+
├── ARCHITECTURE.zh-CN.md # 架构说明（中文）
132217
├── scripts/
133-
│ ├── run-in-docker.cmd # Docker 启动并打开浏览器（Windows）
134-
│ ├── run-in-docker.sh # Docker 启动并打开浏览器（Unix）
135-
│ └── kill-midscene.sh # 可选清理辅助脚本
218+
│ ├── install.sh / install.ps1 # 从 GHCR 安装（免克隆）
219+
│ ├── run-in-docker.cmd / .sh # 从源码构建并启动
220+
│ └── kill-midscene.sh # 可选清理辅助脚本
136221
```
137222

138223
### 后端（Spring Boot / Java 17）

0 commit comments

Comments
 (0)