feat: rebase main devcontainer recommendation on compose+Dockerfile setup

[marcelocra]

Summary

Replaces the image/features-only devcontainer with a Docker Compose based setup (devcontainer.json + docker-compose.yml + Dockerfile + .env), modeled on a battle-tested real-world config, and updates the installer and website to match.

New .devcontainer/ (main recommendation)

• devcontainer.json — Compose-based; name and workspaceFolder derive from ${localWorkspaceFolderBasename}; TZ/LC_ALL/LANG forwarded from the host via ${localEnv:VAR:fallback} instead of hardcoded values; github-cli feature active (docker-in-docker and git-lfs commented); the devmagic.run/setup script kept as a commented opt-in postCreateCommand.
• docker-compose.yml — a single dev service with tmpfs /tmp, cross-platform (${HOME}${USERPROFILE}) dotfiles mount, and bridge network, plus one commented PostgreSQL example showing how to add auxiliary services behind Compose profiles. Targets Docker: builds via build:, with a note that Podman users may prefer building the image manually and using image:.
• Dockerfile — pinned typescript-node:5.0.1-24 base, adds tmux, neovim, ripgrep, fd; ARG-based TZ/locale defaults (runtime values come from localEnv forwarding).
• .env.example — the canonical reference for every value shared between the devcontainer files, documenting which values must match by convention (devcontainer.json can't read .env; ${localEnv:*} reads host env vars). The dev service also loads .env via env_file (required: false), so its values are available inside the container at runtime.
• .env is not committed — the installer generates it per project; without it, Compose falls back to sane defaults.

Installer (devmagic.run/install → setup/devmagic.sh)

• Downloads all files (devcontainer.json, docker-compose.yml, Dockerfile, .env.example) into .devcontainer/ in the current directory.
• Generates .devcontainer/.env with COMPOSE_PROJECT_NAME set to the current folder name, sanitized to Compose naming rules. If sanitization changed the name, the installer automatically patches workspaceFolder in the downloaded devcontainer.json to match.
• Next-steps output suggests git add -f .devcontainer so .env survives common .env* ignore rules.

Docs & website

• README: consumer flow lists the downloaded files, customization mapped to each file's responsibility, Docker-first prerequisites, compact auxiliary-services section based on the commented example, dotfiles section rewritten around the host mount.
• docs/ARCHITECTURE.md: separation-of-concerns diagram, install flow (ASCII + Mermaid), scripts overview and file layout updated to the new design.
• Website (www): simpler landing page — hero gains a one-line quick start (Docker + VS Code + "Reopen in Container"); the standalone/contribute cards and the redundant Quick Start section are gone (those workflows still live in Getting Started). Getting-started file tree shows all five files; prerequisites link Docker first (Podman as fallback); install-flow and dotfiles strings updated in both locales (en, pt-BR), avoiding literal {} in messages (ICU syntax in next-intl); unused strings removed.

Test plan

• bash -n on the installer; compose YAML and devcontainer JSONC parse-checked
• Installer run end-to-end against a local file server: all files downloaded, .env generated with the folder name; auto-patch of workspaceFolder verified with a folder named My Weird App
• git check-ignore confirms .devcontainer/.env.example is committable while .env stays ignored
• pnpm run build passes in www; /, /features, /getting-started, /docs/architecture rendered in both locales (200s, new strings present)
• Prettier clean on all changed files
• Open a real project after curl -fsSL https://devmagic.run/install | bash (post-merge, once main serves the new script) and "Reopen in Container"

Notes

• env_file with required: false needs Docker Compose ≥ 2.24 (Jan 2024).
• The alpine variant under .devcontainer/devcontainers/alpine/ is left untouched as an alternative.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LuKjgTCp3QuvUWqxPf7Q1y

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
devmagic	Ready	Preview, Comment	Jul 13, 2026 6:34am

[greptile-apps]

Greptile Summary

This PR changes DevMagic’s main devcontainer setup to a Docker Compose based flow. The main changes are:

• Adds the recommended .devcontainer Dockerfile, compose file, and env templates.
• Updates the installer to download all devcontainer files and generate .devcontainer/.env.
• Rewrites README and architecture docs for the new Docker-first setup.
• Updates website pages and localized messages to match the new flow.

Confidence Score: 4/5

The generated devcontainer path can break for sanitized folder names, and the dotfiles mount can break Windows hosts.

• Folder names with spaces or uppercase letters can produce mismatched workspace paths.
• Windows users can lose the home-directory fallback used by the host bind mount.
• The docs and website copy changes do not show a concrete rendering issue.

setup/devmagic.sh and .devcontainer/docker-compose.yml

Important Files Changed

Filename	Overview
setup/devmagic.sh	Downloads the expanded devcontainer file set and generates .env, but sanitized project names can diverge from the configured workspace path.
.devcontainer/docker-compose.yml	Defines the new dev service and optional services; the dotfiles mount no longer preserves the Windows home-directory fallback.
.devcontainer/devcontainer.json	Switches the devcontainer to Compose and host locale forwarding, with the workspace path tied to the local folder basename.
www/messages/en.json	Updates English site copy for the Docker-first Compose setup.
www/messages/pt-BR.json	Updates Portuguese site copy in parallel with the English messages.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Installer runs in project folder] --> B[Downloads devcontainer files]
  B --> C[Generates .devcontainer/.env]
  C --> D[VS Code reads devcontainer.json]
  D --> E[Compose starts dev service]
  E --> F[Workspace bind mount uses COMPOSE_PROJECT_NAME]
  D --> G[workspaceFolder uses localWorkspaceFolderBasename]
  F --> H{Paths match?}
  G --> H
  H -->|yes| I[Project opens in container]
  H -->|no| J[Requested workspace path is missing]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
  A[Installer runs in project folder] --> B[Downloads devcontainer files]
  B --> C[Generates .devcontainer/.env]
  C --> D[VS Code reads devcontainer.json]
  D --> E[Compose starts dev service]
  E --> F[Workspace bind mount uses COMPOSE_PROJECT_NAME]
  D --> G[workspaceFolder uses localWorkspaceFolderBasename]
  F --> H{Paths match?}
  G --> H
  H -->|yes| I[Project opens in container]
  H -->|no| J[Requested workspace path is missing]

Loading

_{Reviews (1): Last reviewed commit: "feat: rebase main devcontainer recommend..." | Re-trigger Greptile}