Skip to content

Latest commit

 

History

History
133 lines (110 loc) · 6.9 KB

container-and-env.md

File metadata and controls

133 lines (110 loc) · 6.9 KB

Container And Environment Guide

This page documents what the devkit container includes and which environment variables are useful when running it.

Container Contents

The Docker image is built from .devcontainer/Dockerfile. It includes:

  • Java 8 and Java 21
  • Maven
  • Tomcat 9 and Tomcat 11
  • ActiveMQ Classic
  • IBM MQ tooling path placeholders
  • Node.js, npm, Bun, TypeScript, and TypeScript language server
  • Python 3
  • jq, ripgrep, ag, fd, xmlstarlet, xmllint, xsltproc, tmux, and common shell tools
  • Semgrep, Checkov, Hadolint, Syft, Grype, and SonarScanner
  • OpenCode, oh-my-openagent, opencode-codebase-index, and the devkit skills
  • OpenSpec CLI (openspec) for spec-driven changes with archived history
  • Claude Code, with the same devkit skills in ~/.claude/skills/ and global instructions in ~/.claude/CLAUDE.md, and auto permission mode in ~/.claude/settings.json (secret-file read denies come from the project .claude/settings.json)
  • OpenAI Codex CLI, with the devkit skills in ~/.agents/skills/, global instructions in ~/.codex/AGENTS.md, and MCP servers in ~/.codex/config.toml
  • MCP tooling for Context7, GitHub (remote server, needs GITHUB_TOKEN), and Playwright (headless Chromium in /opt/ms-playwright)

Useful commands inside the container:

use-java8
use-java21
mvn clean verify
opencode
claude
openspec list
start-tomcat9
start-tomcat11
start-activemq

The shell also provides aliases:

java8
java21
mvn8
mvn21
t9
t11

Environment Variables

Use these variables from the target project's docker-compose.yml, from the manual startup script, or inside the running container.

DevKit Runtime

Variable Default Purpose
DEVKIT_PROJECT_DIR /workspace Mounted target project path inside the container. OpenCode, Claude Code, and Codex read AGENTS.md from this directory.
DEVKIT_IMAGE ghcr.io/yuneysi/java-agentic-devkit:latest Host-side only, read by the template docker-compose.yml. Pin a version tag for reproducible sessions.
DEVKIT_APP_PORT 8080 Host-side only, read by the template docker-compose.yml. Application port published on 127.0.0.1 with --service-ports.
DEVKIT_DEBUG_PORT 5005 Host-side only, read by the template docker-compose.yml. Host port for remote debugging.
DEVKIT_DOCKER_SOCKET false Host-side only, read by start-devkit-container.sh. true mounts /var/run/docker.sock for Testcontainers. This gives agents in the container control of the host Docker engine.
DEVKIT_PORTS 8080 5005 Host-side only, read by start-devkit-container.sh. Space-separated PORT (bound to 127.0.0.1) or HOST_PORT:CONTAINER_PORT entries. Set to an empty string to publish no ports.
DEVKIT_JAVA_TEMPLATE java8 Selects the runtime and template. Supported values: java8, java21, java21-migration.
DEFAULT_JAVA_TEMPLATE java8 Container fallback when DEVKIT_JAVA_TEMPLATE is not set.

AI Providers

Variable Purpose
OPENAI_API_KEY Used by the bundled OpenCode OpenAI provider and by Codex (API-key login). Optional; codex login --device-auth also works.
GITHUB_TOKEN Passed to the GitHub MCP server as GITHUB_PERSONAL_ACCESS_TOKEN.
NEXUS_REPOSITORY_URL Release repository URL for check-release-version. Set it on the host; Compose and the start script pass it through.
NEXUS_REPOSITORY_ID Server id in ~/.m2/settings.xml that holds the Nexus credentials (default nexus). Maven reads the credentials; the script never does.
RELEASE_ARTIFACT groupId:artifactId of the deployed artifact for check-release-version (default: the root POM).
GITHUB_PERSONAL_ACCESS_TOKEN Internal MCP environment variable populated from GITHUB_TOKEN by opencode/opencode.json.
ANTHROPIC_API_KEY Optional for Anthropic-compatible tools if enabled by the user.
OLLAMA_API_BASE Optional for local Ollama clients. Use http://host.docker.internal:11434 on Docker Desktop for Windows/macOS. The bundled OpenCode config points to http://host.docker.internal:11434/v1 by default.

Example:

export OPENAI_API_KEY="sk-..."
export GITHUB_TOKEN="ghp_..."
export ANTHROPIC_API_KEY="sk-ant-..."
export OLLAMA_API_BASE="http://host.docker.internal:11434"

Container Runtime Paths

These are set inside the container by the Docker image or shell startup.

Variable Default Purpose
DEBIAN_FRONTEND noninteractive Keeps apt operations noninteractive while building the image.
JAVA8_HOME /opt/java/jdk8 Java 8 installation path.
JAVA21_HOME /opt/java/jdk21 Java 21 installation path.
JAVA_HOME /opt/java/jdk8 Active Java runtime path. Updated by use-java8 and use-java21.
PATH Includes Java, Maven, and ActiveMQ bins Command lookup path assembled by the image.
MAVEN_HOME /opt/maven Maven installation path.
MAVEN_OPTS -Dmaven.repo.local=/home/vscode/.m2/repository Maven JVM options and local repository location. Mount host ~/.m2 to /home/vscode/.m2 in Compose.
TOMCAT9_HOME /opt/tomcat/tomcat9 Tomcat 9 installation path.
TOMCAT11_HOME /opt/tomcat/tomcat11 Tomcat 11 installation path.
CATALINA_HOME /opt/tomcat/tomcat9 Default Tomcat home. Helper scripts override it for Tomcat 9 or 11.
CATALINA_BASE Same as selected Tomcat home Set by start-tomcat9 and start-tomcat11.
ACTIVEMQ_HOME /opt/activemq ActiveMQ installation path.
MQ_INSTALLATION_PATH /opt/mqm IBM MQ installation path.
IBM_MQ_HOME /opt/mqm IBM MQ home path.
LD_LIBRARY_PATH /opt/mqm/lib64:/opt/mqm/lib IBM MQ native library lookup path.
JDTLS_WORKSPACE /var/tmp/jdtls-workspace Optional Eclipse JDT Language Server workspace path.

Docker Build Arguments

These are build arguments, not runtime environment variables. Override them only when rebuilding the image intentionally.

Build argument Default
USERNAME vscode
USER_UID 1000
USER_GID ${USER_UID}
MAVEN_VERSION 3.9.16
TOMCAT9_VERSION 9.0.123
TOMCAT11_VERSION 11.0.27
ACTIVEMQ_VERSION 6.4.0 (runs on JDK 21; Java 8 clients connect over OpenWire)
BUN_VERSION 1.4.4
HADOLINT_VERSION 2.15.1
SYFT_VERSION / GRYPE_VERSION 1.55.0 / 0.121.0
SONAR_SCANNER_VERSION 8.2.0.6438
SEMGREP_VERSION / CHECKOV_VERSION 1.181.1 / 3.3.30
PLAYWRIGHT_MCP_VERSION / PLAYWRIGHT_VERSION 0.0.83 / matching Playwright build
CLAUDE_CODE_VERSION stable
CODEX_VERSION 0.164.0

Every download is pinned to a version and verified: Temurin JDKs (latest patch release, by design) with the SHA-256 that Adoptium publishes, and Maven, Tomcat, and ActiveMQ with the Apache .sha512 files.