devcontainer-dotfiles

Shared dotfiles baseline for Team Alembic devcontainers.

This repository is the common starting point used by our standard templates in devcontainer-templates.

What this repo is for

• Team-maintained default shell and tool setup for devcontainers
• Consistent baseline across projects
• Quick onboarding for new developers

Related repo

• devcontainer-templates - standard templates that consume this dotfiles setup

Build a project devcontainer with this repo

VS Code (Dev Containers extension)

1. Open Preferences: Open User Settings (JSON).
2. Add or update:

{
  "dotfiles.repository": "team-alembic/devcontainer-dotfiles",
  "dotfiles.targetPath": "~/dotfiles",
  "dotfiles.installCommand": "install.sh"
}

3. Run Dev Containers: Rebuild and Reopen in Container.

Result: VS Code clones this repository and runs install.sh when the container is created.

Dev Container CLI

From the project root:

devcontainer up \
  --workspace-folder . \
  --dotfiles-repository https://github.com/team-alembic/devcontainer-dotfiles.git \
  --dotfiles-install-command install.sh

Result: the devcontainer CLI clones this repository and runs install.sh.

DevPod CLI

From the project root:

devpod up . \
  --dotfiles https://github.com/team-alembic/devcontainer-dotfiles.git \
  --dotfiles-script install.sh

Result: DevPod clones this repository and runs install.sh.

Fork and customise

We encourage developers to fork this repository and make it their own.

If you prefer different tools, aliases, or shell behaviour, point your devcontainer config to your fork.

Adding your own tools

Important: do not commit files in this repository that start with . (for example .bashrc).

Some devcontainer tooling can auto-copy dot-prefixed files into the devcontainer user's home directory, but may not overwrite defaults. This can lead to confusing behaviour, especially for shell startup files.

Preferred pattern: keep non-dot files in this repo (for example bashrc, config/...) and copy them explicitly from install.sh.

Use this flow:

1. Fork this repository to your own GitHub account.
2. Add the tool version:
   • If supported by asdf, add it to tool-versions.
   • Otherwise add a manual install step to install.sh.
3. Add any configuration files you want in your fork.
4. Update bashrc for environment or aliases needed by the tool.
5. Update install.sh to copy configuration files into the home directory.

Example: Helix

• tool-versions:

helix-editor 25.07.1

• install.sh (after creating ~/.config):

mkdir -p ~/.config
cp -rv config/helix ~/.config/

• bashrc:

if command -v hx &>/dev/null; then
  export EDITOR="hx"
  alias vi=hx
fi