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 diff --git a/docs/devpod.md b/docs/devpod.md index de9b209..5482af2 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,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: + - 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: @@ -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