SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdevcontainers-nix

devcontainers-nix

Deployment & operations

View repository

Updated 10-26 02:45

About this skill

Dev Containers & Nix Environments

Reproducible, portable development environments that eliminate environment drift.

When to Use This Skill

Use this skill when:

  • Onboarding new developers (zero-to-productive in minutes)
  • Standardizing toolchains across a team
  • Eliminating "works on my machine" problems
  • Setting up CI environments that match local dev
  • Creating ephemeral, disposable dev environments

Environment execution boundaries

Devcontainer features, lifecycle hooks, Nix shell hooks, direnv and dependency installers execute code; inspect the complete configuration, locked inputs and source before activation. Do not run moving downloaded installers or accept a hash mismatch by deleting/recreating state; verify publisher/version and integrity first. Avoid privileged Docker-in-Docker and host sockets for untrusted repositories. Never pass production credentials into a development environment by default. Offline operation needs every dependency/artifact already available locally; a lockfile alone is insufficient. nix build/run need corresponding outputs, which the devShell-only example does not define.

Dev Containers

Basic Configuration

// .devcontainer/devcontainer.json
{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" },
    "ghcr.io/devcontainers/features/python:1": { "version": "3.12" },
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    "ghcr.io/devcontainers/features/kubectl-helm-minikube:1": {}
  },
  "forwardPorts": [3000, 5432],
  "postCreateCommand": "npm install",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-python.python"
      ],
      "settings": {
        "editor.formatOnSave": true
      }
    }
  }
}

Docker Compose Dev Container

// .devcontainer/devcontainer.json
{
  "name": "Full Stack Dev",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "forwardPorts": [3000, 5432, 6379],
  "postCreateCommand": "npm install && npx prisma migrate dev"
}

# .devcontainer/docker-compose.yml
services:
  app:
    build:
      context: ..
      dockerfile: .devcontainer/Dockerfile
    volumes:
      - ..:/workspace:cached
    command: sleep infinity
    depends_on: [db, redis]

  db:
    image: postgres:16
    environment:
      POSTGRES_DB: dev
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "127.0.0.1:5432:5432"

  redis:
    image: redis:7-alpine
    ports:
      - "127.0.0.1:6379:6379"

volumes:
  pgdata:

Custom Dockerfile

# .devcontainer/Dockerfile
FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04

# System dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    curl \
    git \
    jq \
    unzip \
    && rm -rf /var/lib/apt/lists/*

# Install project-specific tools
RUN curl -fsSL https://get.opentofu.org/install-opentofu.sh -o /tmp/install-opentofu.sh \
    && sh /tmp/install-opentofu.sh -s -- --install-method standalone \
    && rm /tmp/install-opentofu.sh
RUN curl -LO "https://dl.k8s.io/release/$(curl -sL https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" \
    && install kubectl /usr/local/bin/

# Non-root user setup
USER vscode
WORKDIR /workspace

Nix Flakes

Basic Flake

# flake.nix
{
  description = "Project development environment";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = nixpkgs.legacyPackages.${system};
      in {
        devShells.default = pkgs.mkShell {
          buildInputs = with pkgs; [
            # Languages
            nodejs_20
            python312
            go_1_22
            rustc
            cargo

            # Tools
            docker-compose
            kubectl
            kubernetes-helm
            opentofu
            awscli2
            jq
            yq-go

            # Databases
            postgresql_16
            redis
          ];

          shellHook = ''
            echo "Dev environment loaded"
            export PROJECT_ROOT=$(pwd)
            export PATH="$PROJECT_ROOT/node_modules/.bin:$PATH"
          '';
        };
      }
    );
}

# Enter the dev shell
nix develop

# Or run a single command
nix develop --command bash -c "node --version && go version"

# Build and run
nix build
nix run

Pin Dependencies

# Lock flake inputs for reproducibility
nix flake lock
nix flake update  # Update all inputs

# Update a specific input
nix flake lock --update-input nixpkgs

Devbox (Nix Made Simple)

Devbox wraps Nix with a friendlier interface:

# Install Devbox
curl -fsSL https://get.jetify.com/devbox -o /tmp/install-devbox.sh && sh /tmp/install-devbox.sh && rm /tmp/install-devbox.sh

# Initialize project
devbox init

# Add packages
devbox add nodejs@20 python@3.12 postgresql@16
devbox add go@1.22 kubectl helm

# Enter shell
devbox shell

# Run commands without entering shell
devbox run node --version

devbox.json Configuration

{
  "$schema": "https://raw.githubusercontent.com/jetify-com/devbox/main/.schema/devbox.schema.json",
  "packages": [
    "nodejs@20",
    "python@3.12",
    "go@1.22",
    "kubectl@1.29",
    "kubernetes-helm@3.14",
    "opentofu@1.8",
    "awscli2@2.15",
    "jq@1.7",
    "postgresql@16",
    "redis@7"
  ],
  "env": {
    "PROJECT_ROOT": "$PWD",
    "DATABASE_URL": "postgresql://localhost:5432/dev"
  },
  "shell": {
    "init_hook": [
      "echo 'Dev environment ready'",
      "npm ci --ignore-scripts"
    ],
    "scripts": {
      "dev": "npm run dev",
      "test": "npm test",
      "db:start": "pg_ctl -D .devbox/virtenv/postgresql/data start",
      "db:stop": "pg_ctl -D .devbox/virtenv/postgresql/data stop",
      "db:migrate": "npx prisma migrate dev"
    }
  }
}

# Run project scripts
devbox run dev
devbox run test
devbox run db:start

# Generate direnv integration (auto-activate on cd)
devbox generate direnv

# Generate Dockerfile from devbox config
devbox generate dockerfile

Devbox + direnv (Auto-Activate)

# Install direnv
devbox add direnv

# Generate .envrc
devbox generate direnv

# Allow direnv
direnv allow

# .envrc (auto-generated)
eval "$(devbox generate direnv --print-envrc)"

Now cd-ing into the project automatically loads the environment.

CI/CD Integration

GitHub Actions with Devbox

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: jetify-com/devbox-install-action@v0.11.0
        with:
          enable-cache: true
      - run: devbox run test
      - run: devbox run lint

GitHub Actions with Nix

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: cachix/install-nix-action@v26
        with:
          nix_path: nixpkgs=channel:nixos-unstable
      - uses: cachix/cachix-action@v14
        with:
          name: my-project
          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
      - run: nix develop --command bash -c "npm ci && npm test"

GitHub Codespaces

// .devcontainer/devcontainer.json — works in Codespaces
{
  "name": "Codespaces Dev",
  "image": "mcr.microsoft.com/devcontainers/universal:2",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" }
  },
  "postCreateCommand": "npm install",
  "portsAttributes": {
    "3000": { "label": "App", "onAutoForward": "openBrowser" },
    "5432": { "label": "Postgres", "onAutoForward": "ignore" }
  }
}

Comparison

Feature Dev Containers Nix Flakes Devbox
Learning curve Low High Low
Reproducibility Good (Docker) Excellent Excellent (Nix)
Speed Slow (build image) Fast (cached) Fast (cached)
IDE support VS Code, JetBrains Any terminal Any terminal
CI integration Docker-based Nix actions Devbox action
Offline support Limited Full Full
macOS/Linux/Win All macOS/Linux macOS/Linux

Best Practices

  • Pin all tool versions explicitly — never use latest
  • Commit lock files (flake.lock, devbox.lock, etc.)
  • Use direnv for automatic environment activation
  • Cache Nix store in CI (Cachix or GitHub cache)
  • Document setup in README: devbox shell or nix develop
  • Keep dev environment close to production (same Node/Python versions)

Troubleshooting

Issue Solution
Nix build slow first time Use binary cache (Cachix), nix develop caches after first run
Dev Container won't build Check Docker disk space, rebuild with --no-cache
Package not in Nixpkgs Search at search.nixos.org, or use fetchFromGitHub overlay
Devbox hash mismatch Run devbox update, delete .devbox/ and re-init
direnv not activating Run direnv allow, check shell hook is installed

Related Skills

  • docker-management (docker-management) — Container image optimization
  • github-actions (github-actions) — CI/CD pipeline setup
  • linux-administration (linux-administration) — System-level tooling

Limitations

  • Guidance executes against real environments: confirm target, blast radius, and rollback plan before applying anything.
  • Never deploy to production without explicit approval. Docs-only import: upstream scripts and templates not bundled.

Example

git status && git diff --stat
kubectl diff -f manifest.yaml

Adapted from BagelHole/DevOps-Security-Agent-Skills (MIT); frontmatter, When to Use/Limitations, and safety boundaries added for upstream compliance. Docs-only import: helper scripts and templates not bundled.