Jalankan Dev Environment Lokal dengan Devcontainer

by Marcus Chen
Jalankan Dev Environment Lokal dengan Devcontainer

Kamu pernah nggak, clone repo lama terus langsung disambut error kayak gini:

Error: Cannot find module 'node-gyp'
gyp ERR! stack Error: not found: make

Atau lebih parah — kamu baru ganti laptop, dan butuh dua hari cuma buat setup environment supaya bisa npm run dev lagi. Node versinya beda, Python-nya conflict, PostgreSQL-nya nggak mau start.

Ini bukan masalah skill. Ini masalah environment yang nggak reproducible.

Solusinya bukan Docker Compose yang ribet, bukan VM yang berat. Solusinya: Devcontainer.

Apa Itu Devcontainer dan Kenapa Ini Beda

Devcontainer adalah spec terbuka (awalnya dari Microsoft, sekarang di bawah devcontainers.org) yang mendefinisikan dev environment kamu sebagai kode — disimpan di repo, di-commit bareng source code.

Bedanya sama Docker Compose biasa:

  • Docker Compose fokus ke runtime production.
  • Devcontainer fokus ke developer experience — IDE integration, port forwarding, dotfiles, VS Code extensions, semua bisa dikonfigurasi.

Kamu define environment di satu file JSON, dan siapapun yang clone repo kamu — termasuk kamu sendiri 6 bulan lagi di laptop baru — langsung dapat environment yang identik.

Support tool-nya juga udah luas: VS Code, Cursor, GitHub Codespaces, Zed (partial), dan CLI standalone buat yang nggak mau terikat editor.

Struktur File Devcontainer

Semua config hidup di folder .devcontainer/ di root repo kamu.

my-project/
├── .devcontainer/
│   ├── devcontainer.json
│   └── Dockerfile          # opsional
├── src/
└── package.json

File utamanya adalah devcontainer.json. Ini contoh minimal buat project Node.js + PostgreSQL:

// .devcontainer/devcontainer.json
{
  "name": "Node.js + PostgreSQL Dev",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",

  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "20"
    },
    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
  },

  "forwardPorts": [3000, 5432],

  "postCreateCommand": "npm install",

  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-azuretools.vscode-docker"
      ],
      "settings": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "esbenp.prettier-vscode"
      }
    }
  },

  "remoteUser": "node"
}

Beberapa field penting:

  • image — base image yang dipakai. Microsoft punya koleksi lengkap di mcr.microsoft.com/devcontainers/.
  • features — ini yang bikin devcontainer powerful. Kamu bisa tambah tooling (Git, Docker, kubectl, dll) tanpa nulis Dockerfile sendiri.
  • postCreateCommand — command yang jalan otomatis setelah container dibuat. Cocok buat npm install atau pip install -r requirements.txt.
  • forwardPorts — port yang di-forward ke host. Kalau kamu pakai Codespaces atau remote, ini yang bikin localhost tetap jalan.

Tambah PostgreSQL sebagai Service

Kalau project kamu butuh database, kamu bisa pakai Docker Compose di dalam devcontainer. Buat file docker-compose.yml di folder .devcontainer/:

# .devcontainer/docker-compose.yml
version: '3.8'

services:
  app:
    build:
      context: ..
      dockerfile: .devcontainer/Dockerfile
    volumes:
      - ../..:/workspaces:cached
    command: sleep infinity
    network_mode: service:db

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: devpassword
      POSTGRES_USER: devuser
      POSTGRES_DB: myapp_dev
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

Lalu update devcontainer.json supaya pakai Compose:

{
  "name": "Node.js + PostgreSQL Dev",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",

  "forwardPorts": [3000, 5432],

  "postCreateCommand": "npm install",

  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "ckolkman.vscode-postgres"
      ]
    }
  }
}

Database langsung available di localhost:5432 dari dalam container.

Dockerfile Custom: Kalau Base Image Nggak Cukup

Kadang kamu butuh tooling spesifik yang nggak ada di base image. Bikin Dockerfile sendiri:

# .devcontainer/Dockerfile
FROM mcr.microsoft.com/devcontainers/javascript-node:20

# Install tools tambahan
RUN apt-get update && apt-get install -y \
    redis-tools \
    httpie \
    && rm -rf /var/lib/apt/lists/*

# Install global npm packages
RUN npm install -g \
    typescript \
    ts-node \
    @prisma/cli

# Copy custom scripts
COPY scripts/init-db.sh /usr/local/bin/init-db
RUN chmod +x /usr/local/bin/init-db

Lalu di devcontainer.json, ganti field image dengan build:

{
  "name": "Custom Node Dev",
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".."
  }
  // ... sisa config
}

Cara Buka Devcontainer di VS Code

Prerequisite:

  1. Docker Desktop (atau Docker Engine di Linux) sudah jalan.
  2. Extension Dev Containers (ms-vscode-remote.remote-containers) sudah terinstall.

Langkah-langkahnya:

  1. Clone repo kamu.
  2. Buka folder di VS Code.
  3. VS Code otomatis detect .devcontainer/ dan muncul notifikasi di pojok kanan bawah: "Folder contains a Dev Container configuration file. Reopen in Container?"
  4. Klik Reopen in Container.
  5. Tunggu build pertama (biasanya 2–5 menit, tergantung image size). Build berikutnya dari cache, jauh lebih cepat.

Kalau notifikasinya nggak muncul, buka Command Palette (Ctrl+Shift+P) → ketik "Dev Containers: Reopen in Container".

Setelah masuk, terminal di VS Code langsung jalan di dalam container. Semua command (node, npm, psql) ada di sana, terisolasi dari sistem host kamu.

Gotcha yang Gue Pernah Kena

1. Volume mount lambat di macOS

Ini masalah klasik Docker di Mac. File sync antara host dan container bisa lambat kalau project kamu banyak file (terutama node_modules).

Solusinya: tambahkan "workspaceMount" dengan opsi cached, dan pindahkan node_modules ke named volume supaya nggak di-sync ke host:

{
  "mounts": [
    "source=${localWorkspaceFolderBasename}-node_modules,target=${containerWorkspaceFolder}/node_modules,type=volume"
  ]
}

Dengan ini, node_modules hidup di Docker volume, bukan di filesystem Mac kamu. Startup time bisa turun dari 30 detik ke 3 detik.

2. Permission issue di Linux

Kalau kamu pakai Linux dan container jalan sebagai user berbeda, file yang dibuat di dalam container bisa punya owner root dan nggak bisa diedit dari host.

Fix-nya: set remoteUser di devcontainer.json ke user yang UID-nya sama dengan user host kamu (biasanya 1000):

{
  "remoteUser": "node",
  "updateRemoteUserUID": true
}

Field updateRemoteUserUID ini yang bikin devcontainer otomatis adjust UID user di dalam container supaya match sama host.

3. .env file nggak kebawa ke container

Jangan commit .env ke repo (jelas). Tapi kamu perlu cara supaya environment variables tersedia di dalam container.

Opsi paling simpel: pakai runArgs untuk pass env file:

{
  "runArgs": ["--env-file", "${localWorkspaceFolder}/.env.local"]
}

Atau kalau kamu pakai Docker Compose, tambahkan env_file di service definition.

4. Port conflict dengan service lokal

Kalau kamu punya PostgreSQL jalan di host port 5432, dan devcontainer juga forward port 5432, bakal conflict. Solusinya: ganti forwardPorts ke port lain, misalnya 15432, dan update connection string di .env:

DATABASE_URL=postgresql://devuser:devpassword@localhost:15432/myapp_dev

Pakai Devcontainer CLI Tanpa VS Code

Kalau kamu lebih suka Neovim atau editor lain, ada CLI resmi yang bisa kamu pakai:

# Install
npm install -g @devcontainers/cli

# Build dan start container
devcontainer up --workspace-folder .

# Jalankan command di dalam container
devcontainer exec --workspace-folder . npm run dev

# Buka shell interaktif
devcontainer exec --workspace-folder . bash

Ini berguna juga buat CI/CD — kamu bisa jalankan test suite di dalam devcontainer yang sama yang dipakai developer, jadi nggak ada lagi masalah "works on my machine". Contoh GitHub Actions workflow menggunakan panduan migrasi hosting sebagai referensi untuk environment consistency:

# .github/workflows/test.yml
name: Test in Devcontainer

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install devcontainer CLI
        run: npm install -g @devcontainers/cli

      - name: Build devcontainer
        run: devcontainer up --workspace-folder .

      - name: Run tests
        run: devcontainer exec --workspace-folder . npm test

Sekarang environment CI kamu identik sama environment development. Bug yang cuma muncul di CI jadi jauh lebih mudah di-reproduce.

Yang Gue Lakuin Sekarang

Semua project baru yang gue mulai — API service, CLI tool, side project — langsung gue setup devcontainer dari awal. Bukan karena ikut-ikutan, tapi karena gue udah terlalu sering buang waktu debug masalah environment yang harusnya nggak perlu ada.

Flow gue sekarang:

  1. git clone repo.
  2. Buka di VS Code, klik "Reopen in Container".
  3. Langsung npm run dev — jalan.

Kalau kamu mau mulai, langkah paling simpel: ambil satu project yang lagi aktif kamu kerjain, buat folder .devcontainer/, copy config minimal dari artikel ini, dan coba buka di VS Code. Nggak perlu sempurna dari awal — iterate aja.

Satu hal lagi: commit .devcontainer/ ke repo. Itu yang bikin semua ini worth it — environment kamu jadi bagian dari source code, bukan dokumen README yang udah outdated sejak 6 bulan lalu.