Skip to content

Commit 15e17fd

Browse files
committed
docs(quickstart): add Podman quickstart section
Add Podman setup to quickstart: install, configure containers.conf with [engine.runtimes], optional urunc config.toml for monitor path, and run example with --runtime urunc. Align structure with Docker and nerdctl sections. Minor README update. Signed-off-by: sidneychang <2190206983@qq.com>
1 parent d5178ae commit 15e17fd

File tree

2 files changed

+92
-2
lines changed

2 files changed

+92
-2
lines changed

README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ inside the unikernel through the respective VM process.
4545

4646
## Quick start
4747

48-
The easiest and fastest way to try out `urunc` would be with `docker`
48+
The easiest and fastest way to try out `urunc` is with [Docker](#quick-start) or [Podman](https://urunc.io/quickstart/#using-podman).
4949
Before doing so, please make sure that the host system satisfies the
5050
following dependencies:
5151

docs/quickstart.md

Lines changed: 91 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ refer to the [installation guide](../installation) for more detailed installatio
33
instructions, or the [design](../design#architecture) document for more
44
details regarding `urunc`'s architecture.
55

6-
We can quickly set `urunc` either with [docker](https://docs.docker.com/engine/install/ubuntu/) or [containerd](https://github.com/containerd/containerd) and [nerdctl](https://github.com/containerd/nerdctl/).
6+
We can quickly set `urunc` with [docker](https://docs.docker.com/engine/install/ubuntu/), [Podman](https://podman.io/), or [containerd](https://github.com/containerd/containerd) and [nerdctl](https://github.com/containerd/nerdctl/).
77
We assume a vanilla ubuntu 22.04 environment, although `urunc` is able to run
88
on a number of GNU/Linux distributions.
99

@@ -88,6 +88,96 @@ $ curl 172.17.0.2
8888
</body>
8989
</html>
9090
```
91+
92+
## Using Podman
93+
94+
You can run `urunc` with [Podman](https://podman.io/) by configuring Podman to use `urunc` as the OCI runtime.
95+
96+
**Prerequisites:** [Podman](https://podman.io/), [QEMU](https://www.qemu.org/) (e.g. `sudo apt install qemu-system`), and the `urunc` binary. Install `urunc` from source as in [Install `urunc` from source](#install-urunc-from-source) above, or follow the [installation guide](installation.md).
97+
98+
### Install Podman
99+
100+
If Podman is not already installed:
101+
102+
```bash
103+
sudo apt install podman
104+
```
105+
106+
### Configure Podman to use urunc
107+
108+
Copy the default configuration and register the `urunc` runtime:
109+
110+
```bash
111+
sudo mkdir -p /etc/containers
112+
sudo cp /usr/share/containers/containers.conf /etc/containers/containers.conf
113+
```
114+
115+
Edit `/etc/containers/containers.conf` and add:
116+
117+
```toml
118+
[engine.runtimes]
119+
urunc = ["/usr/local/bin/urunc"]
120+
```
121+
122+
### Configure urunc
123+
124+
Create `/etc/urunc/config.toml` and set the monitor `path` for your hypervisor (e.g. QEMU). See [configuration](configuration.md) for full options.
125+
126+
```bash
127+
which qemu-system-$(uname -m)
128+
# Example output: /usr/bin/qemu-system-x86_64
129+
```
130+
131+
```toml
132+
[monitors.qemu]
133+
default_memory_mb = 256
134+
default_vcpus = 1
135+
path = "/usr/bin/qemu-system-x86_64"
136+
# default_memory_mb, default_vcpus, etc. are optional; see configuration.md
137+
```
138+
139+
### Run the unikernel with Podman
140+
141+
Run the Nginx Unikraft unikernel (use `--runtime urunc` unless you set it as default above):
142+
143+
```console
144+
$ podman run --rm -d --runtime urunc harbor.nbfc.io/nubificus/urunc/nginx-qemu-unikraft-initrd:latest
145+
88aa2508eb9ba7bc9932b5046f90eab8a57f27d99f19def8dd01ea7d98249217
146+
```
147+
148+
Inspect and verify (replace the container ID with yours):
149+
150+
```console
151+
$ podman ps
152+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
153+
88aa2508eb9b harbor.nbfc.io/nubificus/urunc/nginx-qemu-unikraft-initrd:latest -c /nginx/conf/ng... About a minute Up About a minute compassionate_swanson
154+
155+
$ podman inspect 88aa2508eb9ba7bc9932b5046f90eab8a57f27d99f19def8dd01ea7d98249217 | grep IPAddress
156+
"IPAddress": "10.88.0.2",
157+
"IPAddress": "10.88.0.2",
158+
```
159+
160+
Verify connectivity (e.g. ping or curl the Nginx server):
161+
162+
```console
163+
$ ping -c 3 10.88.0.2
164+
PING 10.88.0.2 (10.88.0.2) 56(84) bytes of data.
165+
64 bytes from 10.88.0.2: icmp_seq=1 ttl=255 time=0.455 ms
166+
...
167+
168+
$ curl 10.88.0.2
169+
<!DOCTYPE html>
170+
<html>
171+
<head>
172+
<title>Hello, world!</title>
173+
</head>
174+
<body>
175+
<h1>Hello, world!</h1>
176+
<p>Powered by <a href="http://unikraft.org">Unikraft</a>.</p>
177+
</body>
178+
</html>
179+
```
180+
91181
## Using containerd and nerdctl
92182

93183
The second way to quickly start with `urunc` would be by setting up a high-level

0 commit comments

Comments
 (0)