devcontainer-starter

A multi-language VS Code Dev Container starter. Pick the branch that matches the stack you want to work in, open the folder in VS Code, and you're dropped straight into a ready-to-go container with the right tools and editor settings.

Pick your starter

Each branch is a complete, self-contained starter. Check out the branch you want before opening the folder in VS Code.

Branch	What's inside
main	Generic Ubuntu base container with a custom bash prompt, common CLI tools (git, curl, jq, htop, ...) and Fira Code. Use as the starting point for any new variant.
python	Everything in main, plus Python 3, pip, FastAPI / SQLAlchemy, and a PostgreSQL + Redis stack wired up via docker-compose.
terraform	Everything in main, plus the official Terraform Dev Container Feature (Terraform CLI, TFLint, terraform-docs), the HashiCorp Terraform VS Code extension, terraform fmt on save, and a minimal hello-world main.tf sample.

git clone https://github.com/serrade/devcontainer-starter.git
cd devcontainer-starter
git switch python    # or main, terraform, ...

Setup (Podman + Dev Containers)

You don't need Docker Desktop. Podman is a free, open-source container engine that works seamlessly with VS Code Dev Containers on Windows, macOS, and Linux. Expand the dropdown for your operating system in each step.

1. Install Git

Git is what you'll use to download the project and switch between starter branches.

Windows

Download and run the installer:

https://git-scm.com/download/win

The defaults during install are fine.

macOS

The easiest path is the Xcode Command Line Tools, which include Git. In Terminal:

xcode-select --install

Or, if you already use Homebrew:

brew install git

Linux

Install Git via your distribution's package manager:

• Debian / Ubuntu: sudo apt install git
• Fedora: sudo dnf install git
• Arch: sudo pacman -S git

See https://git-scm.com/download/linux for other distros.

Open a new terminal and confirm it works:

git --version

2. Install Podman Desktop

Podman is the container engine; Podman Desktop is the cross-platform GUI that bundles it.

Windows

Download and run the installer:

https://podman-desktop.io/downloads

Requirements: Windows 10 build 19043+ or Windows 11, plus admin rights to enable WSL 2 or Hyper-V the first time.

macOS

Download the Universal .dmg (works on Intel and Apple Silicon) and drag Podman Desktop into Applications:

https://podman-desktop.io/downloads/macos

If you previously installed Podman via Homebrew, uninstall it first to avoid conflicts — the .dmg is the recommended install path.

Linux

Flatpak is the recommended install path:

flatpak remote-add --if-not-exists --user flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install --user flathub io.podman_desktop.PodmanDesktop

Launch it with flatpak run io.podman_desktop.PodmanDesktop. AppImage and tar bundles are also available at https://podman-desktop.io/downloads/linux.

If you prefer the CLI only, you can skip Podman Desktop entirely and install plain podman via your package manager (sudo apt install podman, sudo dnf install podman, ...). The Dev Containers extension only needs the podman binary on PATH.

Open Podman Desktop after install. It will walk you through creating a "Podman machine" (a small Linux VM that runs your containers under the hood — required on Windows and macOS, not needed on Linux where containers run natively). The defaults are fine.

3. Install VS Code

If you don't already have it, download for your platform here:

https://code.visualstudio.com/

4. Install the Dev Containers extension

Inside VS Code, install Dev Containers by Microsoft:

https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers

(Or open the Extensions panel with Ctrl+Shift+X / Cmd+Shift+X on macOS and search for "Dev Containers".)

5. Point Dev Containers at Podman

Open VS Code Settings with Ctrl+, (Windows / Linux) or Cmd+, (macOS), click the Open Settings (JSON) icon in the top-right of that tab, and add these two lines inside the outer {}:

"dev.containers.dockerPath": "podman",
"dev.containers.dockerComposePath": "podman-compose"

Save the file. VS Code will now use Podman everywhere it would have used Docker.

6. Open the project in a container

1. File → Open Folder... and pick the cloned devcontainer-starter folder.
2. VS Code should show a notification: "Folder contains a Dev Container configuration file. Reopen folder to develop in a container." Click Reopen in Container.
   • If you miss the popup, click the green >< icon in the bottom-left of the VS Code window and choose Reopen in Container.
3. The first build downloads the base image and installs packages — expect a few minutes. After that, the integrated terminal drops you inside the container with everything ready.

Optional VS Code extensions for Podman

Neither of these is required to use this starter, but they're nice if you want a GUI for managing containers from inside VS Code:

• Container Tools (Microsoft) — evolved from the Docker extension, supports Podman, Containerfile / Dockerfile syntax highlighting, image building.
• Pod Manager (community) — GUI for managing Podman containers, images, volumes, networks, and compose stacks.

Contributing

See CONTRIBUTING.md for how to add a new starter and how to keep variant branches in sync with main.