Skip to content

Streamline windows podman install instructions #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jacob-curley-fnal merged 1 commit into from
May 11, 2026
Merged

Streamline windows podman install instructions #33

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 8 additions & 52 deletions docs/devpod.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,68 +67,24 @@ Mac users will run containers using the Docker-compatible [OrbStack](https://orb

#### Windows

If your local machine is running Windows, you will need to have Windows Subsystem for Linux installed, with Podman installed there.

This guide uses **Podman** and exposes a **Docker-compatible API endpoint** to DevPod on Windows.
If your local machine is running Windows, you will need to have Podman installed and set up to use Windows Subsystem for Linux as its unix runtime host.

1. Run the following in a terminal with administrator rights (you may be asked to restart your machine)
```PowerShell
wsl --install -d Ubuntu
wsl --install --no-distribution
```
2. Open the Start menu and type `wsl`. Run the WSL application.
3. You will be asked to set up a username and password in the Ubuntu instance. This has no bearing on your Windows environment. The user you set up will have administrator (sudo) permissions in the Ubuntu image.
4. Update the packages installed by running
```bash
sudo apt update && sudo apt upgrade
2. Ensure WSL has the latest kernel by running
```PowerShell
wsl --update
```

##### Install Podman

5. Install Podman Desktop on Windows:
3. Install Podman Desktop on Windows:
- Download and install Podman Desktop: <https://podman-desktop.io/downloads/windows>
- Open Podman Desktop after installing so it can finish first-time setup. It will walk you through creating a Podman Machine. Be sure to select the WSL2 integration during this step.
6. Install Podman on your WSL instance from Ubuntu's repositories:
```bash
sudo apt install -y podman
```
7. Verify Podman is installed:
```bash
4. Verify Podman is installed:
```PowerShell
podman version
```

##### Expose Podman's Docker-compatible API to DevPod (TCP 2375)

DevPod's "Docker" provider talks to a Docker-compatible API endpoint. Podman can provide this via its socket.

8. Enable and start the Podman socket:
```bash
sudo systemctl enable --now podman.socket
```
9. Configure the socket to listen on `tcp://127.0.0.1:2375` (so DevPod on Windows can reach it).

Create a systemd override for the socket:
```bash
sudo systemctl edit podman.socket
```

In the editor, add:
```ini
[Socket]
ListenStream=127.0.0.1:2375
```

Then reload and restart:
```bash
sudo systemctl daemon-reload && sudo systemctl restart podman.socket
```

10. Verify the socket is listening:
```bash
sudo systemctl status podman.socket
```

Note: If your environment blocks TCP listeners, you may need to adjust firewall / security tooling.

### UI development (After setup is complete)

While building your app, you'll probably want to test out changes to the UI before deploying. In the container, this requires one preliminary step.
Expand Down