Can you write a detailed, step-by-step tutorial describing how to set up and use VS Code…
- 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.
- 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.jsonfiles. We'll address permissions issues using theuserns=keep-idrun 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
- Install Required VS Code Extensions
- Set Up Rootless Podman on the Remote Host
- Configure SSH for Remote Access
- Prepare the Development Environment
- Configure
devcontainer.jsonfor Podman - Set Up User Namespace Mapping with
userns=keep-id - Connect to the Remote Host and Open the Container
- Develop Inside the Container
- Troubleshooting Tips
- Conclusion
1. Install Required VS Code Extensions
First, install the necessary VS Code extensions on your local machine.
-
Remote - SSH:
- Open VS Code.
- Go to the Extensions view (
Ctrl+Shift+XorCmd+Shift+Xon macOS). - Search for Remote - SSH and install it.
-
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 --versionConfigure Rootless Podman
Rootless Podman allows non-root users to run containers.
-
Initialize Containers Storage:
Ensure that the storage is set up for rootless mode.
podman infoThis command will initialize the storage for your user.
-
Add Subuid and Subgid Mappings:
Ensure that
/etc/subuidand/etc/subgidfiles 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.
-
Generate SSH Keys (if you haven't already):
ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -
Copy SSH Key to Remote Host:
ssh-copy-id username@remote_host -
Test SSH Connection:
ssh username@remote_hostYou should be able to log in without a password prompt.
4. Prepare the Development Environment
Create a Shared Dockerfile
Create a
Dockerfilethat 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.jsonFileCreate a
.devcontainerfolder and inside it, adevcontainer.jsonfile.// 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
vscodewith the username you've set in the Dockerfile.
5. Configure
devcontainer.jsonfor PodmanSince we're using Podman instead of Docker, we need to tell VS Code to use Podman as the container engine.
Edit the
devcontainer.jsonfile to include the following:// devcontainer.json additions "dockerPath": "/usr/bin/podman", "context": "default"The updated
devcontainer.jsonshould 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-idTo avoid permissions issues when mounting your local directory into the container, we use the
--userns=keep-idrun 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
- Press
F1to open the Command Palette. - Type
Remote-SSH: Connect to Host...and select it. - Enter
username@remote_hostand press Enter. - VS Code will open a new window connected to the remote host.
Open the Folder with the Dev Container Configuration
- In the Remote Explorer, navigate to the folder containing the
.devcontainerdirectory. - Open the folder.
Reopen the Folder in a Dev Container
- Press
F1and selectDev Containers: Reopen in Container. - 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
/workspacedirectory 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-idinrunArgs. - Verify that the UID and GID inside the container match those on the host.
Container Doesn't Start
- Check the logs by selecting
View -> Outputand choosingDev Containersfrom 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_HOSTenvironment variable in your.bashrcor.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-idensures 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
Dockerfileanddevcontainer.jsonare 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
Dockerfileanddevcontainer.jsonto add additional tools, ports, or settings as needed for your projects.
-