Skip to content

Commit 394d048

Browse files
mikesir87mikesir87
authored
Add documentation for Docker+Wasm (docker#15952)
* Add documentation for Docker+Wasm * Fix issues discovered by linter * Adjust text at the beginning of the doc and link to the blog post
1 parent 4f5c82e commit 394d048

File tree

2 files changed

+171
-0
lines changed

2 files changed

+171
-0
lines changed

‎_data/toc.yaml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1379,6 +1379,8 @@ manuals:
13791379
path: /desktop/extensions-sdk/dev/api/reference/README/
13801380
- path: /desktop/containerd/
13811381
title: Containerd Image Store (Beta)
1382+
- path: /desktop/wasm/
1383+
title: Wasm (Beta)
13821384
- sectiontitle: FAQs
13831385
section:
13841386
- path: /desktop/faqs/general/

‎desktop/wasm/index.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Docker+Wasm (Beta)
3+
description: How to use the Wasm integration in Docker Desktop
4+
keywords: Docker, WebAssembly, wasm, containerd, engine
5+
toc_max: 3
6+
---
7+
8+
This page provides information about the new ability to run Wasm applications alongside your Linux containers in Docker.
9+
10+
To learn more about the launch and how it works, read [the launch blog post here](https://www.docker.com/blog/docker-wasm-technical-preview/).
11+
12+
> **Beta**
13+
>
14+
> The Docker+Wasm feature is currently in [Beta](../../release-lifecycle.md/#beta). We recommend that you do not use this feature in production environments as this feature may change or be removed from future releases.
15+
16+
17+
## Enabling the Docker+Wasm integration
18+
19+
The Docker+Wasm integration currently requires a special build of Docker Desktop.
20+
21+
- **Important note #1:** This is a technical preview build of Docker Desktop and things might not work as expected. Be sure to back up your containers and images before proceeding.
22+
- **Important note #2:** This preview has the containerd image store enabled and cannot be disabled. If you’re not currently using the containerd image store, then pre-existing images and containers will be inaccessible.
23+
24+
You can download the technical preview build of Docker Desktop here:
25+
26+
- [macOS Apple Silicon](https://dockr.ly/3sf56vH)
27+
- [macOS Intel](https://dockr.ly/3VF6uFB)
28+
- [Windows AMD64](https://dockr.ly/3ShlsP0)
29+
- Linux Arm64 ([deb](https://dockr.ly/3TDcjRV))
30+
- Linux AMD64 ([deb](https://dockr.ly/3TgpWH8), [rpm](https://dockr.ly/3eG6Mvp), [tar](https://dockr.ly/3yUhdCk))
31+
32+
33+
## Usage examples
34+
35+
### Running a Wasm application with docker run
36+
37+
```
38+
$ docker run -dp 8080:8080 \
39+
--name=wasm-example \
40+
--runtime=io.containerd.wasmedge.v1 \
41+
--platform=wasi/wasm32 \
42+
michaelirwin244/wasm-example
43+
```
44+
45+
Note the addition of two additional flags to the run command:
46+
47+
- **--runtime=io.containerd.wasmedge.v1** - This informs the Docker engine that we want to use the Wasm containerd shim instead of the standard Linux container runtime
48+
- **--platform=wasi/wasm32** - This specifies the architecture of the image we want to use. By leveraging a Wasm architecture, we don’t need to build separate images for the different machine architectures. The Wasm runtime will do the final step of converting the Wasm binary to machine instructions.
49+
50+
### Running a Wasm application with Docker Compose
51+
52+
The same application can be run using the following Docker Compose file:
53+
54+
```yaml
55+
services:
56+
app:
57+
image: michaelirwin244/wasm-example
58+
platform: wasi/wasm32
59+
runtime: io.container.wasmedge.v1
60+
ports:
61+
- 8080:8080
62+
```
63+
64+
Then start the application using the normal Docker Compose commands:
65+
66+
```
67+
docker compose up
68+
```
69+
70+
71+
### Running a multi-service application with Wasm
72+
73+
Networking works the same as you expect with Linux containers, giving you the flexibility to combine Wasm applications with other containerized workloads (such as a database) in a single application stack.
74+
75+
In this example, the Wasm application will leverage a MariaDB database running in a container.
76+
77+
1. Start by cloning the repository.
78+
79+
```
80+
$ git clone https://github.com/second-state/microservice-rust-mysql.git
81+
Cloning into 'microservice-rust-mysql'...
82+
remote: Enumerating objects: 75, done.
83+
remote: Counting objects: 100% (75/75), done.
84+
remote: Compressing objects: 100% (42/42), done.
85+
remote: Total 75 (delta 29), reused 48 (delta 14), pack-reused 0
86+
Receiving objects: 100% (75/75), 19.09 KiB | 1.74 MiB/s, done.
87+
Resolving deltas: 100% (29/29), done.
88+
```
89+
90+
2. Navigate into the cloned project and start the project using Docker Compose.
91+
92+
```
93+
$ cd microservice-rust-mysql
94+
$ docker compose up
95+
[+] Running 0/1
96+
⠿ server Warning 0.4s
97+
[+] Building 4.8s (13/15)
98+
...
99+
microservice-rust-mysql-db-1 | 2022-10-19 19:54:45 0 [Note] mariadbd: ready for connections.
100+
microservice-rust-mysql-db-1 | Version: '10.9.3-MariaDB-1:10.9.3+maria~ubu2204' socket: '/run/mysqld/mysqld.sock' port: 3306 mariadb.org binary distribution
101+
```
102+
103+
3. In another terminal, we can see the Wasm image that was created.
104+
105+
```
106+
$ docker images
107+
REPOSITORY TAG IMAGE ID CREATED SIZE
108+
server latest 2c798ddecfa1 2 minutes ago 3MB
109+
```
110+
111+
4. Inspecting the image will show the image has a `wasi/wasm32` platform (combination of Os and Architecture).
112+
113+
```
114+
$ docker image inspect server | grep -A 3 "Architecture"
115+
"Architecture": "wasm32",
116+
"Os": "wasi",
117+
"Size": 3001146,
118+
"VirtualSize": 3001146,
119+
```
120+
121+
5. Open the website at http://localhost:8090 and create a few sample orders. All of these are interacting with the Wasm server.
122+
123+
6. When you're all done, tear everything down by hitting Ctrl+C in the terminal you launched the application.
124+
125+
126+
### Building and pushing a Wasm module
127+
128+
1. Create a Dockerfile that will build your Wasm application. This will vary depending on the language you are using.
129+
130+
2. In a separate stage in your `Dockerfile`, extract the module and set it as the `ENTRYPOINT`.
131+
132+
```
133+
FROM scratch
134+
COPY --from=build /build/hello_world.wasm /hello_world.wasm
135+
ENTRYPOINT [ "hello_world.wasm" ]
136+
```
137+
138+
3. Build and push the image specifying the `wasi/wasm32` architecture. Buildx makes this easy to do in a single command.
139+
140+
```
141+
$ docker buildx build --platform wasi/wasm32 -t username/hello-world .
142+
...
143+
=> exporting to image 0.0s
144+
=> => exporting layers 0.0s
145+
=> => exporting manifest sha256:2ca02b5be86607511da8dc688234a5a00ab4d58294ab9f6beaba48ab3ba8de56 0.0s
146+
=> => exporting config sha256:a45b465c3b6760a1a9fd2eda9112bc7e3169c9722bf9e77cf8c20b37295f954b 0.0s
147+
=> => naming to docker.io/username/hello-world:latest 0.0s
148+
=> => unpacking to docker.io/username/hello-world:latest 0.0s
149+
$ docker push username/hello-world
150+
```
151+
152+
153+
## Docker+Wasm Release Notes
154+
155+
(2022-10-24)
156+
Initial release
157+
158+
### New
159+
- Initial implementation of Wasm integration
160+
161+
### Known issues
162+
- Docker Compose may not exit cleanly when interrupted
163+
- Workaround: Clean up `docker-compose` processes by sending them a SIGKILL (`killall -9 docker-compose`).
164+
- Pushes to Hub might give an error stating `server message: insufficient_scope: authorization failed`, even after logging in using Docker Desktop
165+
- Workaround: Run `docker login` in the CLI
166+
167+
## Feedback
168+
169+
Thanks for trying the new Docker+Wasm integration. We’d love to hear from you! Please feel free to give feedback or report any bugs you may find through the issues tracker on the [public roadmap item](https://github.com/docker/roadmap/issues/426){: target="_blank" rel="noopener" class="_"}.

0 commit comments

Comments
 (0)