Skip to content

Commit 7d3c174

Browse files
beezythebotbeezythebot
committed
Sync open source content 🐝 (from 10b257d89f734625d90cb7cf2fbb0f4d2c4695e6)
1 parent d3002c8 commit 7d3c174

File tree

2 files changed

+189
-0
lines changed

2 files changed

+189
-0
lines changed

‎_meta.global.tsx‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -786,6 +786,9 @@ const meta = {
786786
"getting-started": {
787787
title: "Getting Started",
788788
},
789+
docker: {
790+
title: "Using with Docker",
791+
},
789792
"mise-toolkit": {
790793
title: "Using with mise toolkit",
791794
},

‎docs/speakeasy-reference/cli/docker.mdx‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
description: "Use Speakeasy Docker images to generate SDKs and manage your API tooling in containerized environments. Includes all necessary build tools for supported languages."
3+
slug: /speakeasy-cli/docker/
4+
---
5+
6+
# Using Speakeasy with Docker
7+
8+
The Speakeasy Docker image provides a containerized environment for running Speakeasy CLI commands. The image includes all necessary build tools for all languages supported by Speakeasy, making it ideal for CI/CD pipelines and consistent development environments.
9+
10+
## Docker image
11+
12+
The official Speakeasy Docker image is available on GitHub Container Registry:
13+
14+
[ghcr.io/speakeasy-api/speakeasy](https://github.com/speakeasy-api/speakeasy/pkgs/container/speakeasy)
15+
16+
## Installation
17+
18+
Pull the latest Speakeasy Docker image:
19+
20+
```bash
21+
docker pull ghcr.io/speakeasy-api/speakeasy:latest
22+
```
23+
24+
You can also use specific version tags instead of `latest` for reproducible builds:
25+
26+
```bash
27+
docker pull ghcr.io/speakeasy-api/speakeasy:v1.234.0
28+
```
29+
30+
## Authentication
31+
32+
To authenticate with the Speakeasy Platform from within a Docker container, you need to:
33+
34+
1. Set the `SPEAKEASY_LOGIN_CALLBACK_PORT` environment variable
35+
2. Expose the callback port for OAuth authentication
36+
3. Mount your workspace directory
37+
38+
```bash
39+
docker run -it -v "$(pwd):/workspace" -w "/workspace" \
40+
-e SPEAKEASY_LOGIN_CALLBACK_PORT=$SPEAKEASY_LOGIN_CALLBACK_PORT \
41+
-p $SPEAKEASY_LOGIN_CALLBACK_PORT:$SPEAKEASY_LOGIN_CALLBACK_PORT \
42+
ghcr.io/speakeasy-api/speakeasy:latest auth login
43+
```
44+
45+
After running this command, a browser window will open for you to authenticate with the Speakeasy Platform.
46+
47+
### Using API keys in CI/CD
48+
49+
For automated environments like CI/CD pipelines, use an API key instead of interactive authentication:
50+
51+
```bash
52+
docker run -it -v "$(pwd):/workspace" -w "/workspace" \
53+
-e SPEAKEASY_API_KEY=$SPEAKEASY_API_KEY \
54+
ghcr.io/speakeasy-api/speakeasy:latest run
55+
```
56+
57+
Create an API key in the [Speakeasy Platform](https://app.speakeasy.com) and set it as the `SPEAKEASY_API_KEY` environment variable.
58+
59+
## Generate SDK
60+
61+
To generate an SDK using the Docker image, mount your workspace directory and run the generation command:
62+
63+
```bash
64+
docker run -it -v "$(pwd):/workspace" -w "/workspace" \
65+
ghcr.io/speakeasy-api/speakeasy:latest run all --pinned --frozen-workflow-lockfile --output console
66+
```
67+
68+
This command:
69+
- Mounts the current directory to `/workspace` in the container
70+
- Sets the working directory to `/workspace`
71+
- Runs all configured SDK generation workflows
72+
- Uses pinned versions for reproducibility
73+
- Uses a frozen workflow lockfile to ensure consistent dependencies
74+
- Outputs results to the console
75+
76+
## Common usage examples
77+
78+
### Run quickstart
79+
80+
Get started with an interactive quickstart:
81+
82+
```bash
83+
docker run -it -v "$(pwd):/workspace" -w "/workspace" \
84+
ghcr.io/speakeasy-api/speakeasy:latest quickstart
85+
```
86+
87+
### Validate OpenAPI spec
88+
89+
Validate your OpenAPI specification:
90+
91+
```bash
92+
docker run -it -v "$(pwd):/workspace" -w "/workspace" \
93+
ghcr.io/speakeasy-api/speakeasy:latest validate openapi -s ./openapi.yaml
94+
```
95+
96+
### Generate SDK for specific language
97+
98+
Generate an SDK for a specific language:
99+
100+
```bash
101+
docker run -it -v "$(pwd):/workspace" -w "/workspace" \
102+
ghcr.io/speakeasy-api/speakeasy:latest run -t typescript
103+
```
104+
105+
### Check SDK status
106+
107+
Check the status of your SDK generation:
108+
109+
```bash
110+
docker run -it -v "$(pwd):/workspace" -w "/workspace" \
111+
ghcr.io/speakeasy-api/speakeasy:latest status
112+
```
113+
114+
## Included build tools
115+
116+
The Speakeasy Docker image includes all necessary build tools for generating SDKs in the following languages:
117+
118+
- TypeScript/JavaScript (Node.js, npm, pnpm, yarn)
119+
- Python (Python 3.x, pip, poetry)
120+
- Go (Go compiler and tools)
121+
- Java (JDK, Maven, Gradle)
122+
- C# (.NET SDK)
123+
- PHP (PHP runtime and Composer)
124+
- Ruby (Ruby runtime and Bundler)
125+
- Rust (Rust compiler and Cargo)
126+
127+
This ensures that SDK generation works out of the box without requiring additional setup or dependencies.
128+
129+
## Using in CI/CD pipelines
130+
131+
The Docker image is designed for use in CI/CD pipelines. Here's an example GitHub Actions workflow:
132+
133+
```yaml
134+
name: Generate SDK
135+
on:
136+
push:
137+
branches: [main]
138+
139+
jobs:
140+
generate:
141+
runs-on: ubuntu-latest
142+
steps:
143+
- uses: actions/checkout@v4
144+
145+
- name: Generate SDK
146+
run: |
147+
docker run -v "$(pwd):/workspace" -w "/workspace" \
148+
-e SPEAKEASY_API_KEY=${{ secrets.SPEAKEASY_API_KEY }} \
149+
ghcr.io/speakeasy-api/speakeasy:latest run all --pinned --frozen-workflow-lockfile
150+
```
151+
152+
## Volume mounts and permissions
153+
154+
When using the Docker image, ensure that:
155+
156+
1. Your workspace directory is mounted to `/workspace`
157+
2. The working directory is set to `/workspace` with `-w "/workspace"`
158+
3. File permissions allow the container to read and write files
159+
160+
If you encounter permission issues, you may need to adjust file ownership or run the container with appropriate user permissions.
161+
162+
## Troubleshooting
163+
164+
### Authentication issues
165+
166+
If authentication fails, ensure that:
167+
- The callback port is properly exposed with `-p`
168+
- The `SPEAKEASY_LOGIN_CALLBACK_PORT` environment variable is set
169+
- Your firewall allows connections on the callback port
170+
171+
### File permission errors
172+
173+
If you encounter file permission errors, try running the container with your user ID:
174+
175+
```bash
176+
docker run -it --user $(id -u):$(id -g) \
177+
-v "$(pwd):/workspace" -w "/workspace" \
178+
ghcr.io/speakeasy-api/speakeasy:latest run
179+
```
180+
181+
### Network connectivity
182+
183+
Ensure your Docker container has network access to:
184+
- The Speakeasy Platform (app.speakeasy.com)
185+
- Package registries for your target languages
186+
- Your OpenAPI specification source (if remote)

0 commit comments

Comments
 (0)