From 062fd86866323e24cd5b1fb14d0ddd0de60c4448 Mon Sep 17 00:00:00 2001 From: Khayal Alasgarov Date: Wed, 30 Oct 2024 10:30:34 -0700 Subject: [PATCH 1/2] docs: update README to include Podman migration steps and troubleshooting section --- README.md | 213 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) diff --git a/README.md b/README.md index f0953677d..3883a4fcd 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,8 @@ To install the browsers needed for the Storybook testing with `@vitest/browser`, pnpm test ``` +To run tests, you also need to have Podman (previously Docker) installed so that PostgreSQL can start in a container before the tests run. Follow the sections below to set up Podman if you haven't done so. + To run tests in watch mode (except the `infra` tests, which use Jest): ```bash @@ -83,3 +85,214 @@ A command-line interface is provided for manually running operations. The corres ```bash ./manage.sh --help ``` + + +## Migrating from Docker Desktop to Podman + +If you already have Docker Desktop installed and need to migrate to Podman, follow these steps: + + +### Step 1: Install Podman + +First, you need to install Podman. If you're using Homebrew, you can install it with: + +```bash +brew install podman +``` + +### Step 2: Initialize and Start Podman Machine + +Initialize and start the Podman machine: + +```bash +podman machine init +podman machine start +``` + +### Step 3: Uninstall Docker Desktop + +1. Open Docker Desktop. +2. From the Docker menu, select the Troubleshoot icon. +3. Click Uninstall. +4. Confirm the uninstallation. + +Alternatively, you can uninstall Docker Desktop from the CLI: + +```bash +/Applications/Docker.app/Contents/MacOS/uninstall +``` + +After uninstalling Docker Desktop, you may want to remove residual files: + +```bash +rm -rf ~/Library/Group\ Containers/group.com.docker +rm -rf ~/Library/Containers/com.docker.docker +rm -rf ~/.docker +``` + +### Step 4: Emulate Docker CLI Using Podman + +Follow the steps [here](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman#linux--macos) to create a script to emulate Docker CLI using Podman. This allows you to use Docker commands transparently. + +### Step 5: Configure Environment Variables + +Set the necessary environment variables to ensure testcontainers works correctly with Podman. Add the following lines to your shell configuration file (~/.zshrc for Zsh or ~/.bashrc for Bash): + +```bash +export DOCKER_HOST=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}') +export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock +export TESTCONTAINERS_RYUK_DISABLED=true +``` + +### Step 6: Apply Changes + +After adding the above lines to your shell configuration file, apply the changes by reloading your shell configuration: + + +For Zsh: +```bash +source ~/.zshrc +``` + +For Bash: +```bash +source ~/.bashrc +``` + +### Step 7: Verify Environment and Run Tests + +Ensure the environment variables are set and run your tests: + +```bash +echo $DOCKER_HOST +echo $TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE +echo $TESTCONTAINERS_RYUK_DISABLED + +pnpm test +``` + +## Setting Up Podman for New Team Members + +If you're new to the team and need to start with Podman, follow these steps: + + +### Step 1: Install Podman + +Install Podman using Homebrew: + +```bash +brew install podman +``` + +### Step 2: Initialize and Start Podman Machine + +Initialize and start the Podman machine: + +```bash +podman machine init +podman machine start +``` + +### Step 3: Emulate Docker CLI Using Podman + +Follow the steps [here](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman#linux--macos) to create a script to emulate Docker CLI using Podman. This allows you to use Docker commands transparently. + +### Step 4: [Set Environment Variables](https://github.com/testcontainers/testcontainers-node/blob/08da47baeaa9a43f29aec3a9bb1ce67a3bc1849f/docs/supported-container-runtimes.md) + +Set the necessary environment variables to ensure testcontainers works correctly with Podman. Add the following lines to your shell configuration file (~/.zshrc for Zsh or ~/.bashrc for Bash): + +```bash +export DOCKER_HOST=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}') +export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock +export TESTCONTAINERS_RYUK_DISABLED=true +``` + +### Step 5: Apply Changes + +After adding the above lines to your shell configuration file, apply the changes by reloading your shell configuration: + + +For Zsh: +```bash +source ~/.zshrc +``` + +For Bash: +```bash +source ~/.bashrc +``` + +### Step 6: Verify Environment and Run Tests + +Ensure the environment variables are set and run your tests: + +```bash +echo $DOCKER_HOST +echo $TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE +echo $TESTCONTAINERS_RYUK_DISABLED + +pnpm test +``` + +# Optional: Troubleshooting nvm, Node.js, and pnpm Issues + +If you encounter issues with nvm, node, or pnpm, follow these steps: + +## Issue: Commands Not Found + +### Step 1: Edit Your Shell Configuration File + +Open your shell configuration file in a text editor. For Zsh: + +```bash +nano ~/.zshrc +``` + +Or for Bash: +```bash +nano ~/.bashrc +``` + +### Step 2: Add nvm Initialization + +Add the following lines to ensure nvm is properly initialized upon starting a new shell session: + +```bash +export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" +[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm +[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion +``` + +### Step 3: Add Paths for pnpm + +Add the following lines to ensure pnpm is correctly added to the PATH: + +```bash +export PNPM_HOME="$HOME/.local/share/pnpm" +export PATH="$PNPM_HOME:$PATH" +``` + +### Step 4: Apply Changes + +Save the file and close the editor. Apply the changes by reloading your shell configuration: + + +For Zsh: +```bash +source ~/.zshrc +``` + +For Bash: +```bash +source ~/.bashrc +``` + +### Step 5: Verify Installations + +Ensure that node, nvm, and pnpm are properly installed and accessible: + +```bash +node -v +nvm -v +pnpm -v +``` From 1b7fbf985ba05471c587d873a62d8e4b17cd7760 Mon Sep 17 00:00:00 2001 From: Khayal Alasgarov Date: Wed, 30 Oct 2024 11:38:14 -0700 Subject: [PATCH 2/2] docs: move the Podman-specific instructions into a separate document in the documents directory --- README.md | 213 +------------------------------- documents/podman-integration.md | 209 +++++++++++++++++++++++++++++++ 2 files changed, 210 insertions(+), 212 deletions(-) create mode 100644 documents/podman-integration.md diff --git a/README.md b/README.md index 3883a4fcd..226a8c389 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ To install the browsers needed for the Storybook testing with `@vitest/browser`, pnpm test ``` -To run tests, you also need to have Podman (previously Docker) installed so that PostgreSQL can start in a container before the tests run. Follow the sections below to set up Podman if you haven't done so. +To run tests, you will need to have either Podman or Docker Desktop installed to enable PostgreSQL to start in a container before the tests execute. While we support both Docker and Podman, we recommend using Podman as a free alternative. For detailed setup instructions, refer to the [Podman Desktop Integration](./documents/podman-integration.md) guide. To run tests in watch mode (except the `infra` tests, which use Jest): @@ -85,214 +85,3 @@ A command-line interface is provided for manually running operations. The corres ```bash ./manage.sh --help ``` - - -## Migrating from Docker Desktop to Podman - -If you already have Docker Desktop installed and need to migrate to Podman, follow these steps: - - -### Step 1: Install Podman - -First, you need to install Podman. If you're using Homebrew, you can install it with: - -```bash -brew install podman -``` - -### Step 2: Initialize and Start Podman Machine - -Initialize and start the Podman machine: - -```bash -podman machine init -podman machine start -``` - -### Step 3: Uninstall Docker Desktop - -1. Open Docker Desktop. -2. From the Docker menu, select the Troubleshoot icon. -3. Click Uninstall. -4. Confirm the uninstallation. - -Alternatively, you can uninstall Docker Desktop from the CLI: - -```bash -/Applications/Docker.app/Contents/MacOS/uninstall -``` - -After uninstalling Docker Desktop, you may want to remove residual files: - -```bash -rm -rf ~/Library/Group\ Containers/group.com.docker -rm -rf ~/Library/Containers/com.docker.docker -rm -rf ~/.docker -``` - -### Step 4: Emulate Docker CLI Using Podman - -Follow the steps [here](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman#linux--macos) to create a script to emulate Docker CLI using Podman. This allows you to use Docker commands transparently. - -### Step 5: Configure Environment Variables - -Set the necessary environment variables to ensure testcontainers works correctly with Podman. Add the following lines to your shell configuration file (~/.zshrc for Zsh or ~/.bashrc for Bash): - -```bash -export DOCKER_HOST=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}') -export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock -export TESTCONTAINERS_RYUK_DISABLED=true -``` - -### Step 6: Apply Changes - -After adding the above lines to your shell configuration file, apply the changes by reloading your shell configuration: - - -For Zsh: -```bash -source ~/.zshrc -``` - -For Bash: -```bash -source ~/.bashrc -``` - -### Step 7: Verify Environment and Run Tests - -Ensure the environment variables are set and run your tests: - -```bash -echo $DOCKER_HOST -echo $TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE -echo $TESTCONTAINERS_RYUK_DISABLED - -pnpm test -``` - -## Setting Up Podman for New Team Members - -If you're new to the team and need to start with Podman, follow these steps: - - -### Step 1: Install Podman - -Install Podman using Homebrew: - -```bash -brew install podman -``` - -### Step 2: Initialize and Start Podman Machine - -Initialize and start the Podman machine: - -```bash -podman machine init -podman machine start -``` - -### Step 3: Emulate Docker CLI Using Podman - -Follow the steps [here](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman#linux--macos) to create a script to emulate Docker CLI using Podman. This allows you to use Docker commands transparently. - -### Step 4: [Set Environment Variables](https://github.com/testcontainers/testcontainers-node/blob/08da47baeaa9a43f29aec3a9bb1ce67a3bc1849f/docs/supported-container-runtimes.md) - -Set the necessary environment variables to ensure testcontainers works correctly with Podman. Add the following lines to your shell configuration file (~/.zshrc for Zsh or ~/.bashrc for Bash): - -```bash -export DOCKER_HOST=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}') -export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock -export TESTCONTAINERS_RYUK_DISABLED=true -``` - -### Step 5: Apply Changes - -After adding the above lines to your shell configuration file, apply the changes by reloading your shell configuration: - - -For Zsh: -```bash -source ~/.zshrc -``` - -For Bash: -```bash -source ~/.bashrc -``` - -### Step 6: Verify Environment and Run Tests - -Ensure the environment variables are set and run your tests: - -```bash -echo $DOCKER_HOST -echo $TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE -echo $TESTCONTAINERS_RYUK_DISABLED - -pnpm test -``` - -# Optional: Troubleshooting nvm, Node.js, and pnpm Issues - -If you encounter issues with nvm, node, or pnpm, follow these steps: - -## Issue: Commands Not Found - -### Step 1: Edit Your Shell Configuration File - -Open your shell configuration file in a text editor. For Zsh: - -```bash -nano ~/.zshrc -``` - -Or for Bash: -```bash -nano ~/.bashrc -``` - -### Step 2: Add nvm Initialization - -Add the following lines to ensure nvm is properly initialized upon starting a new shell session: - -```bash -export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" -[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm -[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion -``` - -### Step 3: Add Paths for pnpm - -Add the following lines to ensure pnpm is correctly added to the PATH: - -```bash -export PNPM_HOME="$HOME/.local/share/pnpm" -export PATH="$PNPM_HOME:$PATH" -``` - -### Step 4: Apply Changes - -Save the file and close the editor. Apply the changes by reloading your shell configuration: - - -For Zsh: -```bash -source ~/.zshrc -``` - -For Bash: -```bash -source ~/.bashrc -``` - -### Step 5: Verify Installations - -Ensure that node, nvm, and pnpm are properly installed and accessible: - -```bash -node -v -nvm -v -pnpm -v -``` diff --git a/documents/podman-integration.md b/documents/podman-integration.md new file mode 100644 index 000000000..14e9f3ef5 --- /dev/null +++ b/documents/podman-integration.md @@ -0,0 +1,209 @@ +## Migrating from Docker Desktop to Podman + +If you already have Docker Desktop installed and need to migrate to Podman, follow these steps: + + +### Step 1: Install Podman + +First, you need to install Podman. If you're using Homebrew, you can install it with: + +```bash +brew install podman +``` + +### Step 2: Initialize and Start Podman Machine + +Initialize and start the Podman machine: + +```bash +podman machine init +podman machine start +``` + +### Step 3: Uninstall Docker Desktop + +1. Open Docker Desktop. +2. From the Docker menu, select the Troubleshoot icon. +3. Click Uninstall. +4. Confirm the uninstallation. + +Alternatively, you can uninstall Docker Desktop from the CLI: + +```bash +/Applications/Docker.app/Contents/MacOS/uninstall +``` + +After uninstalling Docker Desktop, you may want to remove residual files: + +```bash +rm -rf ~/Library/Group\ Containers/group.com.docker +rm -rf ~/Library/Containers/com.docker.docker +rm -rf ~/.docker +``` + +### Step 4: Emulate Docker CLI Using Podman + +Follow the steps [here](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman#linux--macos) to create a script to emulate Docker CLI using Podman. This allows you to use Docker commands transparently. + +### Step 5: Configure Environment Variables + +Set the necessary environment variables to ensure testcontainers works correctly with Podman. Add the following lines to your shell configuration file (~/.zshrc for Zsh or ~/.bashrc for Bash): + +```bash +export DOCKER_HOST=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}') +export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock +export TESTCONTAINERS_RYUK_DISABLED=true +``` + +### Step 6: Apply Changes + +After adding the above lines to your shell configuration file, apply the changes by reloading your shell configuration: + + +For Zsh: +```bash +source ~/.zshrc +``` + +For Bash: +```bash +source ~/.bashrc +``` + +### Step 7: Verify Environment and Run Tests + +Ensure the environment variables are set and run your tests: + +```bash +echo $DOCKER_HOST +echo $TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE +echo $TESTCONTAINERS_RYUK_DISABLED + +pnpm test +``` + +## Setting Up Podman for New Team Members + +If you're new to the team and need to start with Podman, follow these steps: + + +### Step 1: Install Podman + +Install Podman using Homebrew: + +```bash +brew install podman +``` + +### Step 2: Initialize and Start Podman Machine + +Initialize and start the Podman machine: + +```bash +podman machine init +podman machine start +``` + +### Step 3: Emulate Docker CLI Using Podman + +Follow the steps [here](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman#linux--macos) to create a script to emulate Docker CLI using Podman. This allows you to use Docker commands transparently. + +### Step 4: [Set Environment Variables](https://github.com/testcontainers/testcontainers-node/blob/08da47baeaa9a43f29aec3a9bb1ce67a3bc1849f/docs/supported-container-runtimes.md) + +Set the necessary environment variables to ensure testcontainers works correctly with Podman. Add the following lines to your shell configuration file (~/.zshrc for Zsh or ~/.bashrc for Bash): + +```bash +export DOCKER_HOST=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}') +export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock +export TESTCONTAINERS_RYUK_DISABLED=true +``` + +### Step 5: Apply Changes + +After adding the above lines to your shell configuration file, apply the changes by reloading your shell configuration: + + +For Zsh: +```bash +source ~/.zshrc +``` + +For Bash: +```bash +source ~/.bashrc +``` + +### Step 6: Verify Environment and Run Tests + +Ensure the environment variables are set and run your tests: + +```bash +echo $DOCKER_HOST +echo $TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE +echo $TESTCONTAINERS_RYUK_DISABLED + +pnpm test +``` + +# Optional: Troubleshooting nvm, Node.js, and pnpm Issues + +If you encounter issues with nvm, node, or pnpm, follow these steps: + +## Issue: Commands Not Found + +### Step 1: Edit Your Shell Configuration File + +Open your shell configuration file in a text editor. For Zsh: + +```bash +nano ~/.zshrc +``` + +Or for Bash: +```bash +nano ~/.bashrc +``` + +### Step 2: Add nvm Initialization + +Add the following lines to ensure nvm is properly initialized upon starting a new shell session: + +```bash +export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" +[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm +[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion +``` + +### Step 3: Add Paths for pnpm + +Add the following lines to ensure pnpm is correctly added to the PATH: + +```bash +export PNPM_HOME="$HOME/.local/share/pnpm" +export PATH="$PNPM_HOME:$PATH" +``` + +### Step 4: Apply Changes + +Save the file and close the editor. Apply the changes by reloading your shell configuration: + + +For Zsh: +```bash +source ~/.zshrc +``` + +For Bash: +```bash +source ~/.bashrc +``` + +### Step 5: Verify Installations + +Ensure that node, nvm, and pnpm are properly installed and accessible: + +```bash +node -v +nvm -v +pnpm -v +```