Skip to content

Change docs to use Podman for Windows #30

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
chowington merged 4 commits into from
May 7, 2026
Merged

Change docs to use Podman for Windows #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
657036c
Change docs to use Podman for Windows
chowington May 7, 2026
75427dd
Add Podman Desktop install instruction
chowington May 7, 2026
5931e00
Add note about gh app requirement
chowington May 7, 2026
bfe8fb9
Update docs
chowington May 7, 2026
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
4 changes: 3 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,9 @@ This template comes preconfigured for Continuous Integration and Continuous Deli

Upon merging changes in to the `main` branch, your application will be built and packaged into a container. The default deployment behavior is controlled by [`IMAGE_VARIANT`](.github/workflows/ci-cd.yaml:20) in [`.github/workflows/ci-cd.yaml`](.github/workflows/ci-cd.yaml). It is currently set to `gui-xpra`, which builds the browser-served GUI variant by default. If your application is intended as a headless service, or works better from the command line, change [`IMAGE_VARIANT`](.github/workflows/ci-cd.yaml:20) to `cli`.

Once the container is built, it will be pushed into `adregistry.fnal.gov` ("Harbor") so it can be deployed into the Kubernetes environment. To reiterate: **this will happen on every commit to the `main` branch.** If you do not want a new container being generated every time you make a change (e.g., if you're in the middle of implementing a new feature and want to do it in stages), the recommended approach is to create a "feature" branch that tracks your pending updates. Starting on `main`, the process would look something like this:
Once the container is built, it will be pushed into Harbor at `adregistry.fnal.gov` so it can be deployed into the Kubernetes environment. Before images can be pushed to Harbor, a GitHub fermi-ad admin must add the appropriate GitHub App containing the AP Python Harbor secrets to your repository. Reach out to beau@fnal.gov or mariana@fnal.gov for this before you attempt to deploy.

To reiterate: **deployment will happen on every commit to the `main` branch.** If you do not want a new container being generated every time you make a change (e.g., if you're in the middle of implementing a new feature and want to do it in stages), the recommended approach is to create a "feature" branch that tracks your pending updates. Starting on `main`, the process would look something like this:

1. Run `git checkout -b <name of feature branch>` -> Creates a new branch based on `main` and checks out that branch
2. Run `git checkout -b <name of stage>` -> Creates a new branch based on your feature branch and checks out that branch
Expand Down
101 changes: 47 additions & 54 deletions docs/devpod.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,13 @@ The workspace uses the external image referenced there, which is expected to pro
### Setup

1. Ensure [VS Code is set up](#vs-code). This includes installing some necessary extensions, listed in the instructions.
2. Prepare your machine
2. Prepare your machine
- [Mac](#mac)
- [Windows](#windows)
3. On your local machine, [install DevPod](https://devpod.sh/docs/getting-started/install#install-devpod).
4. Open DevPod and enter the URL of your project's GitHub repository, or point it to the local directory if you've already cloned the repo.
5. Select Docker as the "Provider"
- If on Windows, edit the advanced options to specify the "Host" as `tcp://127.0.0.1:2375`
- If on Windows, edit the advanced options to specify the "Host" as `tcp://127.0.0.1:2375`.
6. Select VS Code as your IDE
7. Click Create - the dev container will be pulled down and started for you, and VS Code should open
8. After the workspace starts, open a terminal in VS Code and run
Expand All @@ -39,7 +39,7 @@ The workspace uses the external image referenced there, which is expected to pro
```
10. (Optional) Run the GUI
1. [Set up access to the container's desktop](#ui-development-after-setup-is-complete)
2. Run
2. Run
```bash
uv run ap-python-starter-kit
```
Expand All @@ -51,11 +51,11 @@ The workspace uses the external image referenced there, which is expected to pro
1. [Install VS Code](https://code.visualstudio.com/download)
2. Open VS Code and navigate to the Extensions tab (icon looks like four squares, where the top-right square is rotated 45 degrees)
3. In the search bar at the top, type "Dev Containers" and install the extension from Microsoft
4. (Windows-only) Do the same as step 3, searching for and installing the "WSL" extension (also by Microsoft)
4. (Windows-only) Do the same as step 3, searching for and installing the "WSL" extension (also by Microsoft)

#### Mac

Mac users will require Docker to be installed. While Windows users can leverage Docker Engine to avoid licensing issues, Mac users will have to leverage an alternative called [OrbStack](https://orbstack.dev/).
Mac users will run containers using the Docker-compatible [OrbStack](https://orbstack.dev/).

1. [Install OrbStack](https://orbstack.dev/download)
2. Start OrbStack by opening the app, or run in a terminal:
Expand All @@ -66,79 +66,72 @@ Mac users will require Docker to be installed. While Windows users can leverage

#### Windows

If your local machine is running Windows, you will need to have Windows Subsystem for Linux installed, with Docker or some other pod management system installed there. Here are the steps to accomplish this:
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.

1. Run the following in a terminal with administrator rights (you may be asked to restart your machine)
```PowerShell
wsl --install
```
Ubuntu will be the default Linux distribution, and the remainder of this guide will target that.
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
2. 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.
3. Open the Start menu and type `wsl`. Run the WSL application.
4. 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.
5. Update the packages installed by running
```bash
sudo apt update && sudo apt upgrade
```
5. Install needed packages for Docker
```bash
sudo apt install ca-certificates curl gnupg lsb-release
```
6. Set up GPG for Docker authentication
```bash
sudo mkdir -p /etc/apt/keyrings
```
```bash
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
```
7. Configure GPG authentication
```bash
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
```
8. Install Docker Engine

##### Install Podman (in WSL Ubuntu)

6. Install Podman from Ubuntu's repositories:
```bash
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo apt install -y podman
```
9. Add your user to the `docker` group (prevents needing to use `sudo` for every Docker command)
7. Verify Podman is installed:
```bash
sudo usermod -aG docker $USER
podman version
```
10. Start Docker

##### 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 docker
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 enable containerd
sudo systemctl edit podman.socket
```
Verify Docker is running
```bash
sudo systemctl status docker

In the editor, add:
```ini
[Socket]
ListenStream=127.0.0.1:2375
```
11. Configure Docker to be accessible to DevPod

Then reload and restart:
```bash
sudo systemctl edit --full docker.service
sudo systemctl daemon-reload && sudo systemctl restart podman.socket
```
This should open an editor. Look for
```
...
[Service]
ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock
...
```
On the end of this line, add `-H tcp://127.0.0.1:2375`. The full entry should now read
```
...
[Service]
ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock -H tcp://127.0.0.1:2375
...
```
Now run

10. Verify the socket is listening:
```bash
sudo systemctl daemon-reload && sudo systemctl restart docker.service
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.
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.

The development container comes with a minimal desktop overlay, in which your app will run when you kick it off. To see it, do the following:

Expand All @@ -148,7 +141,7 @@ The development container comes with a minimal desktop overlay, in which your ap
4. If it doesn't open automatically, go to your web browser and navigate to `localhost:6080`
5. Click "Connect"

You're all set! Now when you run the app locally, it will come up in your web browser at `localhost:6080`.
You're all set! Now when you run the app locally, it will come up in your web browser at `localhost:6080`.

## Notes

Expand Down