Skip to content
TheChatArchiveThe Chat Archive
o1-preview-2024-09-12· OpenAIAi2 WildChat-4.8M (AI2)

Can you write a detailed, step-by-step tutorial describing how to set up and use VS Code…

  1. User

    Can you write a detailed, step-by-step tutorial describing how to set up and use VS Code to do development inside containers? The containers will be on a remote hose, so we will have to use the remote ssh at dev containers extensions. Containers on the remote host will be using podman, and all containers will run alpine linux. We must run rootless podman, and all developers must be able to mount their own working directories into their containers while sharing the same dockerfiles and devcontainer.json files. So please make sure to include details on how to set that up to avoid permissions issues using the userns=keep-id runArg. The audience for the tutorial is a group of mid-level professional developers.

  2. Assistant

    Developing Inside Remote Containers with VS Code and Podman

    This tutorial provides a detailed, step-by-step guide on how to set up Visual Studio Code (VS Code) for developing inside containers that are running on a remote host. We will be using rootless Podman with Alpine Linux containers. Developers will mount their own working directories into their containers while sharing the same Dockerfiles and devcontainer.json files. We'll address permissions issues using the userns=keep-id run argument.

    Prerequisites

    Before you begin, ensure you have the following:

    • Local Machine:

      • VS Code installed.
      • SSH access to the remote host.
      • VS Code extensions: Remote - SSH and Dev Containers.
    • Remote Host:

      • Rootless Podman installed and configured for your user.
      • Network access for SSH connections.

    Table of Contents

    1. Install Required VS Code Extensions
    2. Set Up Rootless Podman on the Remote Host
    3. Configure SSH for Remote Access
    4. Prepare the Development Environment
    5. Configure devcontainer.json for Podman
    6. Set Up User Namespace Mapping with userns=keep-id
    7. Connect to the Remote Host and Open the Container
    8. Develop Inside the Container
    9. Troubleshooting Tips
    10. Conclusion

    1. Install Required VS Code Extensions

    First, install the necessary VS Code extensions on your local machine.

    1. Remote - SSH:

      • Open VS Code.
      • Go to the Extensions view (Ctrl+Shift+X or Cmd+Shift+X on macOS).
      • Search for Remote - SSH and install it.
    2. Dev Containers:

      • In the Extensions view, search for Dev Containers (formerly known as Remote - Containers) and install it.

    These extensions allow VS Code to connect to remote hosts via SSH and work inside containers.


    2. Set Up Rootless Podman on the Remote Host

    On the remote host, ensure that rootless Podman is installed and configured for your user.

    Install Podman

    If Podman is not installed, you can install it as follows:

    # For Fedora/CentOS/RHEL
    sudo dnf install podman
    
    # For Debian/Ubuntu
    sudo apt-get update
    sudo apt-get install podman
    
    # Verify installation
    podman --version
    

    Configure Rootless Podman

    Rootless Podman allows non-root users to run containers.

    1. Initialize Containers Storage:

      Ensure that the storage is set up for rootless mode.

      podman info
      

      This command will initialize the storage for your user.

    2. Add Subuid and Subgid Mappings:

      Ensure that /etc/subuid and /etc/subgid files contain entries for your user.

      sudo sh -c "echo '$USER:100000:65536' >> /etc/subuid"
      sudo sh -c "echo '$USER:100000:65536' >> /etc/subgid"
      

    3. Configure SSH for Remote Access

    Ensure that you can SSH into the remote host without being prompted for a password every time.

    1. Generate SSH Keys (if you haven't already):

      ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
      
    2. Copy SSH Key to Remote Host:

      ssh-copy-id username@remote_host
      
    3. Test SSH Connection:

      ssh username@remote_host
      

      You should be able to log in without a password prompt.


    4. Prepare the Development Environment

    Create a Shared Dockerfile

    Create a Dockerfile that defines the container environment. Save this file in a shared location accessible to all developers (e.g., a Git repository).

    # Dockerfile
    
    FROM alpine:latest
    
    # Install necessary tools
    RUN apk add --no-cache \
        bash \
        git \
        build-base
    
    # Set the working directory
    WORKDIR /workspace
    
    # [Optional] Add a non-root user
    ARG USERNAME=vscode
    ARG USER_UID=1000
    ARG USER_GID=$USER_UID
    RUN adduser -D -u $USER_UID -G users $USERNAME
    
    # Switch to the non-root user
    USER $USERNAME
    
    # Set the entrypoint
    ENTRYPOINT [ "sleep", "infinity" ]
    

    Create a Shared devcontainer.json File

    Create a .devcontainer folder and inside it, a devcontainer.json file.

    // devcontainer.json
    
    {
      "name": "Alpine Dev Container",
      "build": {
        "dockerfile": "Dockerfile",
        "args": {
          "VARIANT": "latest"
        }
      },
      "runArgs": [
        "--userns=keep-id"
      ],
      "forwardPorts": [],
      "mounts": [
        "type=bind,source=${localWorkspaceFolder},target=/workspace,consistency=cached"
      ],
      "remoteUser": "vscode"
    }
    

    Note: Replace vscode with the username you've set in the Dockerfile.


    5. Configure devcontainer.json for Podman

    Since we're using Podman instead of Docker, we need to tell VS Code to use Podman as the container engine.

    Edit the devcontainer.json file to include the following:

    // devcontainer.json additions
    
    "dockerPath": "/usr/bin/podman",
    "context": "default"
    

    The updated devcontainer.json should look like this:

    {
      "name": "Alpine Dev Container",
      "dockerPath": "/usr/bin/podman",
      "context": "default",
      "build": {
        "dockerfile": "Dockerfile",
        "args": {
          "VARIANT": "latest"
        }
      },
      "runArgs": [
        "--userns=keep-id"
      ],
      "forwardPorts": [],
      "mounts": [
        "type=bind,source=${localWorkspaceFolder},target=/workspace,consistency=cached"
      ],
      "remoteUser": "vscode"
    }
    

    6. Set Up User Namespace Mapping with userns=keep-id

    To avoid permissions issues when mounting your local directory into the container, we use the --userns=keep-id run argument.

    This tells Podman to map your user and group IDs from the host to the container, ensuring that file permissions remain consistent.

    In your devcontainer.json:

    "runArgs": [
      "--userns=keep-id"
    ],
    

    7. Connect to the Remote Host and Open the Container

    Connect to the Remote Host via SSH in VS Code

    1. Press F1 to open the Command Palette.
    2. Type Remote-SSH: Connect to Host... and select it.
    3. Enter username@remote_host and press Enter.
    4. VS Code will open a new window connected to the remote host.

    Open the Folder with the Dev Container Configuration

    1. In the Remote Explorer, navigate to the folder containing the .devcontainer directory.
    2. Open the folder.

    Reopen the Folder in a Dev Container

    1. Press F1 and select Dev Containers: Reopen in Container.
    2. VS Code will start building the container using Podman and the provided Dockerfile.

    8. Develop Inside the Container

    Once the container is up and running, you can start developing as if you were working on your local machine.

    • The /workspace directory inside the container is mounted from your working directory on the remote host.
    • Any changes you make are reflected both inside and outside the container.
    • Extensions and settings are isolated to the container environment.

    9. Troubleshooting Tips

    Permission Issues

    If you encounter permission issues with files or directories:

    • Ensure that you're using --userns=keep-id in runArgs.
    • Verify that the UID and GID inside the container match those on the host.

    Container Doesn't Start

    • Check the logs by selecting View -> Output and choosing Dev Containers from the dropdown.
    • Verify that Podman is correctly installed and configured on the remote host.

    Podman Socket Error

    • VS Code expects a Docker-compatible socket. Ensure that Podman's compatibility layer is enabled:

      systemctl --user enable --now podman.socket
      
    • If using rootless Podman, set the DOCKER_HOST environment variable in your .bashrc or .bash_profile:

      export DOCKER_HOST='unix://$XDG_RUNTIME_DIR/podman/podman.sock'
      

    10. Conclusion

    By following this tutorial, you've set up a development environment where multiple developers can work inside containers running on a remote host using VS Code. Using rootless Podman with userns=keep-id ensures that file permissions are maintained correctly when mounting directories, avoiding common issues encountered with containerized development.


    Additional Tips

    • Extensions in the Container: You can install VS Code extensions inside the container. They will be isolated from your local environment.
    • Sharing Configurations: Since the Dockerfile and devcontainer.json are in a shared location, all developers can use the same environment setup, ensuring consistency across the team.
    • Customizing the Environment: Feel free to modify the Dockerfile and devcontainer.json to add additional tools, ports, or settings as needed for your projects.