Skip to content

devcontainer.md

Latest commit

 

History

History
251 lines (159 loc) · 10.8 KB

devcontainer.md

File metadata and controls

251 lines (159 loc) · 10.8 KB
Raw

Developing with Dev Containers

This project ships a Development Container so you can get a reproducible, fully-provisioned environment in a few clicks — no need to install Python, uv, PostgreSQL, or any other tool on your host machine.

The container definition lives in .devcontainer/devcontainer.json and reuses the project's docker-compose.yaml plus a small .devcontainer/docker-compose.yml override.

This guide covers how to open the dev container from Visual Studio Code and from JetBrains IDEs (PyCharm Professional / IntelliJ IDEA Ultimate). For background on the Dev Container specification, see https://containers.dev/.

Table of contents

What is a Dev Container?

A Docker container configured as a development environment, described by an open specification at https://containers.dev/. VS Code and JetBrains IDEs both read the same devcontainer.json, so the team can stay on different editors without forking the configuration.

Prerequisites

You need a running container runtime on your host:

Platform Recommended runtime
macOS / Windows Docker Desktop
Linux Docker Engine
Alternative Podman Desktop, Rancher Desktop, OrbStack (macOS)

Make sure Docker is running before opening the dev container:

docker info

You also need Git and a local clone of this repository:

git clone git@github.com:softwareone-platform/ffc-extension.git
cd ffc-extension

Copy env.example to .env and adjust values as needed — the dev container reads it via docker-compose:

cp env.example .env

What this project's dev container provides

Looking at .devcontainer/devcontainer.json:

  • Service: the app service from docker-compose.yaml (built from dev.Dockerfile).
  • Workspace folder: /app.
  • Side-car services started automatically: db and test_db (PostgreSQL 17).
  • Mounts:
    • ~/.ssh — so git over SSH works from inside the container.
    • Named volumes for ~/.claude, ~/.cache/JetBrains, ~/.local/share/JetBrains, ~/.config/JetBrains — preserves IDE state and Claude Code sessions across container rebuilds.
  • VS Code extensions: Python, Ruff, Mypy, Claude Code, Commitizen.
  • JetBrains backend: PyCharm, with Claude Code plugins pre-installed.

You don't need to install Python, uv, or PostgreSQL on your host — everything lives inside the container.

Using the Dev Container with VS Code

1. Install the Dev Containers extension

Install the Dev Containers extension (ms-vscode-remote.remote-containers) from the VS Code Marketplace.

Dev Containers extension in the VS Code Marketplace

2. Open the project in the container

Open the project folder in VS Code, then either:

  • Click the Remote indicator in the bottom-left corner and pick Reopen in Container, or
  • Run Dev Containers: Reopen in Container from the Command Palette (F1 / Ctrl/Cmd+Shift+P).

Reopen in Container command in the VS Code Command Palette

VS Code will:

  1. Build (or pull) the images defined in the two compose files.
  2. Start the app, db, and test_db services.
  3. Connect the editor to the app container at /app.
  4. Install the extensions listed in customizations.vscode.extensions.

You can follow the progress by clicking Starting Dev Container (show log) in the bottom-right notification.

Dev container build log in VS Code

3. You're connected

The Remote indicator now reads Dev Container: FFC Extension. The integrated terminal is a shell inside the container — python, uv, and psql all resolve to the container's binaries.

VS Code Remote indicator showing the active dev container

4. Stop or rebuild

From the Command Palette:

  • Dev Containers: Rebuild Container — after editing devcontainer.json, dev.Dockerfile, or compose files.
  • Dev Containers: Reopen Folder Locally — disconnects from the container.

📖 Official documentation:

Using the Dev Container with JetBrains IDEs

Note: Dev Containers support in JetBrains IDEs requires a paid edition (PyCharm Professional / IntelliJ IDEA Ultimate). Community editions don't ship the Remote Development feature.

1. Open Remote Development

From the IDE welcome screen, choose Remote Development → Dev Containers.

Remote Development panel in PyCharm

2. Create a new Dev Container connection

Click New Dev Container. You have three sources:

  • From local project — point to the cloned repo on disk.
  • From VCS project — the IDE clones the repo for you.
  • From Docker — attach to an already-running container.

For this project, the simplest flow is From local project:

  1. Click From local project.
  2. Pick .devcontainer/devcontainer.json from your clone.
  3. Choose PyCharm as the IDE backend (matches customizations.jetbrains.backend).
  4. Click Build Container and Continue.

Selecting devcontainer.json in PyCharm

The IDE will build the compose stack, download the PyCharm backend into the container, and install the plugins declared under customizations.jetbrains.plugins.

Building compose stack

3. Connect

Once the backend is ready, a JetBrains Client (thin client) window opens, connected to PyCharm running inside the container. Project files live at /app.

JetBrains Client connected to PyCharm in the dev container

Reconnecting later

The IDE remembers your dev containers under Remote Development → Dev Containers. Pick the entry and click Connect — it will start the compose stack if it's stopped and reconnect to the backend.

📖 Official documentation:

Common operations

All commands below run inside the dev container (VS Code terminal, PyCharm terminal, or docker compose exec app bash).

Backend (run from /app)

Task Command
Run the app uv run ffcops serve --server-workers 2
Run tests uv run pytest
Lint uv run ruff check .
Type check uv run mypy .
Apply DB migrations uv run alembic upgrade head
Open a psql shell psql -h db -U $FFC_EXT_POSTGRES_USER $FFC_EXT_POSTGRES_DB

Frontend (run from /app/frontend)

Node.js 24 is preinstalled in the dev container (via nvm).

Task Command
Install dependencies npm ci
Build (types + bundle) into static/ npm run build
Watch and rebuild on change npm run start
Run the Vite dev server npm run dev
Lint npm run lint
Auto-fix lint issues npm run lint:fix
Format with Prettier npm run format
Check formatting npm run format:check
Lint + format check npm run check:all
Production build npm run build:prod

Troubleshooting

Build hangs or fails on first start. Check Docker has enough resources (at least 4 GB RAM, 4 CPUs on macOS/Windows). Rebuild with cache cleared:

docker compose -f docker-compose.yaml -f .devcontainer/docker-compose.yml build --no-cache app

SSH/git operations fail inside the container. The container bind-mounts ~/.ssh from your host. Confirm your host has working keys (ssh -T git@github.com on the host) and that the file permissions are sane (chmod 600 ~/.ssh/id_*).

.env not picked up. The compose env_file: .env directive expects a .env at the repo root. Copy env.example if you haven't yet.

Ports already in use. Stop any local PostgreSQL or any other process bound to 5432 / 8001, or change the host-side port mapping in .devcontainer/docker-compose.yml.

JetBrains plugins missing after rebuild. The named volumes (jetbrains-cache, jetbrains-share, jetbrains-config) preserve IDE state. If something gets wedged, remove them and let the IDE re-provision: docker volume rm jetbrains-cache jetbrains-share jetbrains-config.

Stuck "Connecting to dev container" in JetBrains. Try File → Invalidate Caches in the thin client, or rebuild the container from the IDE's Remote Development → Dev Containers list.

References

Dev Container specification

Microsoft / VS Code

JetBrains