Skip to content

Commit 8afc1dd

Browse files
KuldeepGehlotkuldeep-capsitechcursoragent
authored
feat(docker): add official CLI image and GHCR publish workflow (#3654)
* feat(docker): add official CLI image and GHCR publish workflow Ship a minimal Node 22 Alpine image so projects on older Node LTS versions can run Orval at build time without upgrading Node. Includes multi-arch GHCR publishing on release tags and installation docs for Windows, macOS, and Linux including localhost via host.docker.internal. Co-authored-by: Cursor <cursoragent@cursor.com> * chore(docker): harden image and refine publish workflow docs Run the CLI image as a non-root user, disable checkout credential persistence in the publish workflow, and align README Windows examples with installation docs. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Kuldeep Gehlot <kuldeep.gehlot@capsitech.com> Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent bb79bf7 commit 8afc1dd

6 files changed

Lines changed: 378 additions & 0 deletions

File tree

‎.dockerignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
*
2+
!Dockerfile

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

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
name: Publish Docker Image
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
permissions:
9+
contents: read
10+
packages: write
11+
12+
jobs:
13+
docker:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- name: Checkout repository
17+
uses: actions/checkout@v7
18+
with:
19+
persist-credentials: false
20+
21+
- name: Extract version
22+
id: version
23+
run: echo "version=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_OUTPUT"
24+
25+
- name: Set up QEMU
26+
uses: docker/setup-qemu-action@v3
27+
28+
- name: Set up Docker Buildx
29+
uses: docker/setup-buildx-action@v3
30+
31+
- name: Log in to GitHub Container Registry
32+
uses: docker/login-action@v3
33+
with:
34+
registry: ghcr.io
35+
username: ${{ github.actor }}
36+
password: ${{ secrets.GITHUB_TOKEN }}
37+
38+
- name: Build and push
39+
uses: docker/build-push-action@v6
40+
with:
41+
context: .
42+
platforms: linux/amd64,linux/arm64
43+
push: true
44+
build-args: |
45+
ORVAL_VERSION=${{ steps.version.outputs.version }}
46+
tags: |
47+
ghcr.io/orval-labs/orval:${{ steps.version.outputs.version }}
48+
ghcr.io/orval-labs/orval:latest

‎Dockerfile‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
FROM node:22-alpine
2+
3+
ARG ORVAL_VERSION=latest
4+
5+
RUN npm install -g "orval@${ORVAL_VERSION}" \
6+
&& addgroup -g 1001 -S orval \
7+
&& adduser -S orval -u 1001 -G orval
8+
9+
ENV NODE_PATH=/usr/local/lib/node_modules
10+
11+
WORKDIR /app
12+
13+
RUN chown -R orval:orval /app
14+
15+
USER orval
16+
17+
ENTRYPOINT ["orval"]

‎README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,51 @@ You can find some samples below:
5858

5959
Try Orval out for yourself using our [Playground](https://orval.dev/playground) application!
6060

61+
### Docker
62+
63+
Orval 8+ requires Node.js 22.18 or newer. Projects on an older Node LTS can run code generation with the official Docker image.
64+
65+
**Basic usage**
66+
67+
```bash
68+
# macOS / Linux
69+
docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval
70+
71+
# Windows Git Bash
72+
MSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval
73+
74+
# Windows CMD
75+
cd /d "C:\path\to\your-project"
76+
docker run --rm -v "%cd%:/app" -w /app ghcr.io/orval-labs/orval
77+
78+
# Windows PowerShell
79+
cd "C:\path\to\your-project"
80+
docker run --rm -v "${PWD}:/app" -w /app ghcr.io/orval-labs/orval
81+
```
82+
83+
**Local API (`localhost` → `host.docker.internal`)**
84+
85+
```bash
86+
# macOS / Linux
87+
docker run --rm -v "$(pwd):/app" -w /app -e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" -e NODE_TLS_REJECT_UNAUTHORIZED=0 ghcr.io/orval-labs/orval --config ./orval.config.ts
88+
89+
# Linux (native Docker)
90+
docker run --rm --add-host=host.docker.internal:host-gateway -v "$(pwd):/app" -w /app -e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" -e NODE_TLS_REJECT_UNAUTHORIZED=0 ghcr.io/orval-labs/orval --config ./orval.config.ts
91+
92+
# Windows Git Bash
93+
MSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd):/app" -w /app -e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" -e NODE_TLS_REJECT_UNAUTHORIZED=0 ghcr.io/orval-labs/orval --config ./orval.config.ts
94+
95+
# Windows CMD
96+
cd /d "C:\path\to\your-project"
97+
docker run --rm -v "%cd%:/app" -w /app -e "ORVAL_SWAGGER_URL=https://host.docker.internal:7142/swagger/v1/swagger.json" -e "NODE_TLS_REJECT_UNAUTHORIZED=0" ghcr.io/orval-labs/orval --config ./orval.config.ts
98+
99+
# Windows PowerShell
100+
cd "C:\path\to\your-project"
101+
docker run --rm -v "${PWD}:/app" -w /app -e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" -e NODE_TLS_REJECT_UNAUTHORIZED=0 ghcr.io/orval-labs/orval --config ./orval.config.ts
102+
```
103+
104+
Replace `ghcr.io/orval-labs/orval` with `orval:local` when testing locally before the official image is published. See the [installation docs](https://orval.dev/docs/installation#docker) for details.
105+
61106
## A note about AI
62107

63108
First of all, we do not reject the use of AI agents outright. That said, please do not submit AI-generated output in a PR without reviewing it yourself. Every change must have a clear intent and purpose — do not submit changes you cannot explain in your own words. Making the effort to understand orval's codebase, TypeScript, and API clients beforehand, and reviewing what AI produces, is the contributor's responsibility, not the reviewer's. Finally, we will continue to welcome new contributors and actively support you through review and iteration.

‎docs/content/docs/installation.mdx‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,139 @@ pnpm add orval -D
3030
</Tab>
3131
</Tabs>
3232

33+
## Docker
34+
35+
Orval 8+ requires Node.js 22.18 or newer. If your project targets an older Node LTS version, you can run code generation with the official Docker image instead of installing Orval locally.
36+
37+
`/app` is only a path inside the container. Your project does not need an `app` folder — mount your project root to any container path and set `-w` to match.
38+
39+
### Basic usage
40+
41+
<Tabs items={["macOS / Linux", "Windows (Git Bash)", "Windows (CMD)", "Windows (PowerShell)"]}>
42+
<Tab value="macOS / Linux">
43+
```bash
44+
docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval
45+
```
46+
</Tab>
47+
<Tab value="Windows (Git Bash)">
48+
```bash
49+
MSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval
50+
```
51+
</Tab>
52+
<Tab value="Windows (CMD)">
53+
```bat
54+
docker run --rm -v "%cd%:/app" -w /app ghcr.io/orval-labs/orval
55+
```
56+
</Tab>
57+
<Tab value="Windows (PowerShell)">
58+
```powershell
59+
docker run --rm -v "${PWD}:/app" -w /app ghcr.io/orval-labs/orval
60+
```
61+
</Tab>
62+
</Tabs>
63+
64+
Pin a specific release with a version tag (for example `8.19.0`):
65+
66+
```bash
67+
ghcr.io/orval-labs/orval:8.19.0
68+
```
69+
70+
### With a config file
71+
72+
<Tabs items={["macOS / Linux", "Windows (Git Bash)", "Windows (CMD)", "Windows (PowerShell)"]}>
73+
<Tab value="macOS / Linux">
74+
```bash
75+
docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.ts
76+
```
77+
</Tab>
78+
<Tab value="Windows (Git Bash)">
79+
```bash
80+
MSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.ts
81+
```
82+
</Tab>
83+
<Tab value="Windows (CMD)">
84+
```bat
85+
docker run --rm -v "%cd%:/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.ts
86+
```
87+
</Tab>
88+
<Tab value="Windows (PowerShell)">
89+
```powershell
90+
docker run --rm -v "${PWD}:/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.ts
91+
```
92+
</Tab>
93+
</Tabs>
94+
95+
On Windows Git Bash, prefix commands with `MSYS_NO_PATHCONV=1` so Docker receives `/app` instead of `C:/Program Files/Git/app`.
96+
97+
### Fetching OpenAPI from localhost
98+
99+
Inside a container, `localhost` refers to the container itself, not your machine. If your `orval.config.ts` fetches a spec from a local API (for example `https://localhost:7142/swagger/v1/swagger.json`), replace `localhost` with `host.docker.internal` and pass the URL via an environment variable.
100+
101+
| Host OS | Use instead of `localhost` |
102+
| --- | --- |
103+
| Windows / macOS (Docker Desktop) | `host.docker.internal` |
104+
| Linux (Docker Desktop) | `host.docker.internal` |
105+
| Linux (native Docker) | `host.docker.internal` with `--add-host=host.docker.internal:host-gateway` |
106+
107+
Read the URL from an environment variable in your config:
108+
109+
```ts
110+
const inputTarget =
111+
process.env.ORVAL_SWAGGER_URL ?? 'https://localhost:7142/swagger/v1/swagger.json';
112+
```
113+
114+
Set `NODE_TLS_REJECT_UNAUTHORIZED=0` only when your local API uses a self-signed certificate. For CI or offline builds, point Orval at a committed file such as `./src/swagger.json` instead.
115+
116+
Replace `ghcr.io/orval-labs/orval` with `orval:local` when testing with a locally built image before the official image is published.
117+
118+
<Tabs items={["macOS / Linux", "Linux (native Docker)", "Windows (Git Bash)", "Windows (CMD)", "Windows (PowerShell)"]}>
119+
<Tab value="macOS / Linux">
120+
```bash
121+
docker run --rm \
122+
-v "$(pwd):/app" \
123+
-w /app \
124+
-e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" \
125+
-e NODE_TLS_REJECT_UNAUTHORIZED=0 \
126+
ghcr.io/orval-labs/orval \
127+
--config ./orval.config.ts
128+
```
129+
</Tab>
130+
<Tab value="Linux (native Docker)">
131+
```bash
132+
docker run --rm --add-host=host.docker.internal:host-gateway \
133+
-v "$(pwd):/app" \
134+
-w /app \
135+
-e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" \
136+
-e NODE_TLS_REJECT_UNAUTHORIZED=0 \
137+
ghcr.io/orval-labs/orval \
138+
--config ./orval.config.ts
139+
```
140+
</Tab>
141+
<Tab value="Windows (Git Bash)">
142+
```bash
143+
MSYS_NO_PATHCONV=1 docker run --rm \
144+
-v "$(pwd):/app" \
145+
-w /app \
146+
-e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" \
147+
-e NODE_TLS_REJECT_UNAUTHORIZED=0 \
148+
ghcr.io/orval-labs/orval \
149+
--config ./orval.config.ts
150+
```
151+
</Tab>
152+
<Tab value="Windows (CMD)">
153+
```bat
154+
cd /d "C:\path\to\your-project"
155+
docker run --rm -v "%cd%:/app" -w /app -e ORVAL_SWAGGER_URL=https://host.docker.internal:7142/swagger/v1/swagger.json -e NODE_TLS_REJECT_UNAUTHORIZED=0 ghcr.io/orval-labs/orval --config ./orval.config.ts
156+
```
157+
</Tab>
158+
<Tab value="Windows (PowerShell)">
159+
```powershell
160+
cd "C:\path\to\your-project"
161+
docker run --rm -v "${PWD}:/app" -w /app -e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" -e NODE_TLS_REJECT_UNAUTHORIZED=0 ghcr.io/orval-labs/orval --config ./orval.config.ts
162+
```
163+
</Tab>
164+
</Tabs>
165+
33166
## Global Installation
34167

35168
You can also install Orval globally:

0 commit comments

Comments
 (0)