Skip to content

Commit 7d5ee07

Browse files
alexellisalexellis
committed
Trim on walkthrough
Signed-off-by: Alex Ellis (OpenFaaS Ltd) <alexellis2@gmail.com>
1 parent 6e38a3f commit 7d5ee07

1 file changed

Lines changed: 96 additions & 50 deletions

File tree

‎docs/getting-started/walkthrough.md‎

Lines changed: 96 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -39,9 +39,6 @@ config:
3939
api:
4040
port: 8080
4141
bind_address: "127.0.0.1"
42-
ssh:
43-
port: 2222
44-
bind_address: "0.0.0.0"
4542
```
4643
4744
* `count` - the number of VMs to create - the default is `1` - you can set this to `0` to [create VMs via API instead](/reference/api)
@@ -51,22 +48,7 @@ config:
5148
* `storage_size` - for storage backends which support it, you can specify the size of the disk
5249
* `github_user` - your GitHub username, used to fetch your public SSH keys from your profile - additional SSH keys can be added via the [ssh_keys](/reference/ssh) API.
5350

54-
The HTTP API is enabled by default and can be disabled with `enabled: false`.
55-
56-
The Serial Over SSH (SOS) server is disabled by default and can be enabled by providing a port. Most users will not need the SOS.
57-
58-
The default `bind_address` for both the API and SSH is `127.0.0.1` - loopback on the host system.
59-
60-
There's no need to provide the HTTP API section unless you plan to run Slicer more than once on the same host, in that case, it's useful to include it so you can change it to a different port on another slicer instance.
61-
62-
**Configuration for an Arm64 Slicer installation**
63-
64-
`slicer new` will generate a configuration file for the correct image for Arm or x86_64, but if you create one manually, you'll need to edit the `image` field.
65-
66-
```diff
67-
- image: "ghcr.io/openfaasltd/slicer-systemd:5.10.240-x86_64-latest"
68-
+ image: "ghcr.io/openfaasltd/slicer-systemd-arm64:6.1.90-aarch64-latest"
69-
```
51+
The API can bind to a TCP address (secured with an auth token) or a unix socket (secured by OS filesystem permissions). If you run multiple Slicer instances on the same host, give each one a different port or socket path. See the [API reference](/reference/api) for details.
7052

7153
The `storage: image` setting means a disk image will be cloned from the root filesystem into a local file. It's not the fastest option for the initial setup, but it's the simplest, persistent and great for long-living VMs.
7254

@@ -90,6 +72,91 @@ Then, you can connect with SSH:
9072
ssh ubuntu@192.168.137.2
9173
```
9274

75+
## Quick start with slicer auto
76+
77+
If you want to skip the configuration step, use `slicer auto`:
78+
79+
```bash
80+
sudo slicer auto
81+
```
82+
83+
This will:
84+
85+
* Auto-detect a free bridge network range from `10.0.0.0/8` that doesn't conflict with your existing interfaces
86+
* Pick a random API port (so multiple instances don't clash)
87+
* Import your SSH keys from `~/.ssh/*.pub`
88+
* Write an `auto.yaml` config in the current directory
89+
* Start the API server ready for VMs to be launched
90+
91+
The API port is printed on startup and written to `auto.yaml` for reference.
92+
93+
To launch a VM, open a new terminal and run:
94+
95+
```bash
96+
export SLICER_URL="http://127.0.0.1:PORT"
97+
export SLICER_TOKEN_FILE="/var/lib/slicer/auth/token"
98+
99+
slicer vm add
100+
```
101+
102+
Replace `PORT` with the port shown in the `auto.yaml` file or the startup output.
103+
104+
### Flags
105+
106+
| Flag | Default | Description |
107+
|---|---|---|
108+
| `--count` | `0` | Number of VMs to pre-start (0 means API-only, launch with `slicer vm add`) |
109+
| `--ram` | `4` | RAM in GiB per VM |
110+
| `--cpu` | `2` | vCPUs per VM |
111+
| `--isolated` | `false` | Use isolated networking instead of bridge |
112+
| `--ssh-key` | | SSH public key(s) to add (can be repeated) |
113+
| `--github` | | GitHub username to import SSH keys from |
114+
| `--find-ssh-keys` | `true` | Scan `~/.ssh/` for public keys |
115+
| `--api-port` | auto | Explicit API server port (default: auto-assign free port) |
116+
| `--api-bind` | `127.0.0.1` | API bind address or unix socket path |
117+
| `--socket` | `false` | Use a unix socket at `./auto.sock` instead of TCP |
118+
| `--kernel` | | Path to a custom kernel, or leave blank to extract one from the rootfs |
119+
120+
### Examples
121+
122+
Pre-start VMs with the daemon instead of launching them separately:
123+
124+
```bash
125+
sudo slicer auto --count=1
126+
127+
sudo slicer auto --count=3 --ram=8 --cpu=4
128+
```
129+
130+
SSH keys from `~/.ssh/*.pub` on the host are imported automatically. You can also import keys from a GitHub profile:
131+
132+
```bash
133+
sudo slicer auto --github=alexellis
134+
```
135+
136+
Use isolated networking (no bridge, access VMs via `slicer vm exec` / `slicer vm forward`):
137+
138+
```bash
139+
sudo slicer auto --isolated
140+
```
141+
142+
Use a unix socket instead of TCP for the API:
143+
144+
```bash
145+
sudo slicer auto --socket
146+
```
147+
148+
Set a fixed API port instead of auto-assigning:
149+
150+
```bash
151+
sudo slicer auto --api-port=9090
152+
```
153+
154+
### Re-run behavior
155+
156+
On subsequent runs, `sudo slicer auto` reuses the existing `auto.yaml` - including the same port and CIDR. Pass any flag (like `--count=3`) to regenerate it with new settings.
157+
158+
The generated `auto.yaml` is a standard Slicer config - you can inspect or edit it to learn the format, then graduate to `slicer new` + `slicer up` for full control over networking, storage, and naming.
159+
93160
## Ignore changing SSH host keys
94161

95162
If, like the developers of Slicer, you'll be re-creating many hosts with the same IP addresses, you have two options:
@@ -136,46 +203,25 @@ If you want to tail the logs from all available VMs at once, use `fstail` via `a
136203
sudo -E fstail /var/log/slicer/
137204
```
138205

139-
## Launch a second VM
140-
141-
Edit the `count` field, and set it to `2`.
142-
143-
Then hit Control + C and launch slicer again.
144-
145-
You'll see the second VM come online and can connect to it over SSH.
206+
## Managing VMs
146207

147-
## Enable the HTTP API
208+
List running VMs:
148209

149-
The API is used by the `slicer vm` commands, and can also be used directly via `curl`.
150-
151-
```yaml
152-
api:
153-
port: 8080
154-
bind_address: "127.0.0.1:"
155-
auth:
156-
enabled: true
210+
```bash
211+
slicer vm list
157212
```
158213

159-
The auth token will be created at `/var/lib/slicer/auth/token` and can be used via a `Authorization: Bearer` header.
160-
161-
i.e.
214+
Launch additional VMs without restarting the daemon:
162215

163216
```bash
164-
curl -s http://127.0.0.1:8080/nodes -H "Authorization: Bearer $(sudo cat /var/lib/slicer/auth/token)" | jq
217+
slicer vm add
165218
```
166219

167-
## Enable the Serial Over SSH Console
220+
Delete a VM:
168221

169-
The Serial Over SSH (SOS) console can be used to log into a VM without a password, and without any form of networking enabled.
170-
171-
```yaml
172-
ssh:
173-
port: 2222
174-
bind_address: "0.0.0.0:"
222+
```bash
223+
slicer vm delete VM_NAME
175224
```
176225

177-
Example:
226+
See all available commands with `slicer vm --help`, or refer to the [API reference](/reference/api) for direct HTTP access.
178227

179-
```bash
180-
ssh -p 2222 ubuntu@localhost
181-
```

0 commit comments

Comments
 (0)