From 657036c8260a11cd2859321104311df28dfd023b Mon Sep 17 00:00:00 2001 From: Connor Howington Date: Thu, 7 May 2026 09:19:07 -0500 Subject: [PATCH 1/4] Change docs to use Podman for Windows --- docs/devpod.md | 101 ++++++++++++++++++++++++------------------------- 1 file changed, 49 insertions(+), 52 deletions(-) diff --git a/docs/devpod.md b/docs/devpod.md index de9b209..235fd77 100644 --- a/docs/devpod.md +++ b/docs/devpod.md @@ -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 @@ -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 ``` @@ -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: @@ -66,7 +66,9 @@ 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 in WSL** 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 @@ -74,71 +76,66 @@ If your local machine is running Windows, you will need to have Windows Subsyste ``` 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. +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 ``` -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) + +5. 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) +6. 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. + +7. Enable and start the Podman socket: ```bash - sudo systemctl enable --now docker + sudo systemctl enable --now podman.socket ``` +8. 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= + ListenStream=127.0.0.1:2375 ``` -11. Configure Docker to be accessible to DevPod + + Note that both `ListenStream` lines are required. + + Then reload and restart: ```bash - sudo systemctl edit --full docker.service - ``` - This should open an editor. Look for - ``` - ... - [Service] - ExecStart=/usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock - ... + sudo systemctl daemon-reload && sudo systemctl restart podman.socket ``` - 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 + +9. Verify the socket is listening: ```bash - sudo systemctl daemon-reload && sudo systemctl restart docker.service + sudo systemctl status podman.socket ``` +10. In DevPod (Windows), select the Docker provider and set the Host to: + + `tcp://127.0.0.1:2375` + +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: @@ -148,7 +145,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 From 75427dd281f8a0957c6f69ea2d3ddddae17fc1a7 Mon Sep 17 00:00:00 2001 From: Connor Howington Date: Thu, 7 May 2026 10:53:04 -0500 Subject: [PATCH 2/4] Add Podman Desktop install instruction --- docs/devpod.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/devpod.md b/docs/devpod.md index 235fd77..82fd7df 100644 --- a/docs/devpod.md +++ b/docs/devpod.md @@ -68,27 +68,30 @@ Mac users will run containers using the Docker-compatible [OrbStack](https://orb 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 in WSL** and exposes a **Docker-compatible API endpoint** to DevPod on Windows. +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: + - 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 ``` ##### Install Podman (in WSL Ubuntu) -5. Install Podman from Ubuntu's repositories: +6. Install Podman from Ubuntu's repositories: ```bash sudo apt install -y podman ``` -6. Verify Podman is installed: +7. Verify Podman is installed: ```bash podman version ``` @@ -97,11 +100,11 @@ This guide uses **Podman in WSL** and exposes a **Docker-compatible API endpoint DevPod's "Docker" provider talks to a Docker-compatible API endpoint. Podman can provide this via its socket. -7. Enable and start the Podman socket: +8. Enable and start the Podman socket: ```bash sudo systemctl enable --now podman.socket ``` -8. Configure the socket to listen on `tcp://127.0.0.1:2375` (so DevPod on Windows can reach it). +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 @@ -111,23 +114,20 @@ DevPod's "Docker" provider talks to a Docker-compatible API endpoint. Podman can In the editor, add: ```ini [Socket] - ListenStream= ListenStream=127.0.0.1:2375 ``` - Note that both `ListenStream` lines are required. - Then reload and restart: ```bash sudo systemctl daemon-reload && sudo systemctl restart podman.socket ``` -9. Verify the socket is listening: +10. Verify the socket is listening: ```bash sudo systemctl status podman.socket ``` -10. In DevPod (Windows), select the Docker provider and set the Host to: +11. In DevPod (Windows), select the Docker provider and set the Host to: `tcp://127.0.0.1:2375` From 5931e00a1c7de589ef4d0a07776bbcef808b3c9d Mon Sep 17 00:00:00 2001 From: Connor Howington Date: Thu, 7 May 2026 11:24:42 -0500 Subject: [PATCH 3/4] Add note about gh app requirement --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a239530..2ede5ad 100644 --- a/README.md +++ b/README.md @@ -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 ` -> Creates a new branch based on `main` and checks out that branch 2. Run `git checkout -b ` -> Creates a new branch based on your feature branch and checks out that branch From bfe8fb91d7b08de71080820cae8016230a9592c9 Mon Sep 17 00:00:00 2001 From: Connor Howington Date: Thu, 7 May 2026 12:22:19 -0500 Subject: [PATCH 4/4] Update docs --- docs/devpod.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/devpod.md b/docs/devpod.md index 82fd7df..5482af2 100644 --- a/docs/devpod.md +++ b/docs/devpod.md @@ -127,10 +127,6 @@ DevPod's "Docker" provider talks to a Docker-compatible API endpoint. Podman can sudo systemctl status podman.socket ``` -11. In DevPod (Windows), select the Docker provider and set the Host to: - - `tcp://127.0.0.1:2375` - Note: If your environment blocks TCP listeners, you may need to adjust firewall / security tooling. ### UI development (After setup is complete)