> For the complete documentation index, see [llms.txt](https://docs.terrakube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terrakube.io/getting-started/development/dev-container.md). # Local Dev Container This is the supported local development environment for macOS (Apple Silicon and Intel), Linux, Windows, and WSL. The tools and dependencies run in Linux containers, so contributors use the same workflow on every host platform. ### Prerequisites * VS Code and the **Dev Containers** extension * A container runtime with Docker Compose support * [mkcert](https://github.com/FiloSottile/mkcert) on the host * 4 CPUs and 8 GB RAM available to the container runtime On Windows, use Docker Desktop's WSL integration and clone inside the WSL filesystem (for example, `~/src/terrakube`), not `/mnt/c`. This avoids slow bind mounts and unreliable file watching. No custom Docker subnet, local DNS server, or hosts-file entries are required. The `*.localhost` names used by the environment resolve to the loopback address on supported browsers and operating systems. ### Start developing 1. Follow the certificate step below once. 2. Clone your fork, open it in VS Code, and choose **Dev Containers: Reopen in Container** when prompted. 3. Once setup finishes, select **Terrakube Postgresql** in Run and Debug. 4. Open and sign in with `admin@example.com` / `admin`. PostgreSQL, MinIO, Redis, and Traefik start with the Dev Container. Do not run `docker compose up` or **setup-env2** yourself. ### Make and debug changes Use only **Terrakube Postgresql** for the normal local stack. **Terrakube** is an alternative H2 stack: never run both compounds, because they start the same applications on the same ports. * UI changes refresh the browser automatically. * For API, Registry, or Executor changes, use hot-code replace when available; otherwise restart just that service's **Run** configuration. * Check the changed behaviour at . Rebuild the Dev Container only after changing `.devcontainer/`, its Dockerfile, features, or trusted CA files. ### Validate before a pull request Run the checks relevant to the change from the repository root: ``` # Backend or shared changes mvn -B verify -Dspring-boot.build-image.skip=true # UI changes cd ui yarn install --immutable yarn lint:modules:check yarn format:modules:check yarn build ``` Then use **Terrakube Postgresql** to verify the affected user flow. Record what you ran and checked in the pull request. See [CONTRIBUTING.md](https://github.com/terrakube-io/terrakube/blob/main/CONTRIBUTING.md). Traefik publishes ports 80 and 443 by default. If either is already occupied, set `TRAEFIK_HTTP_PORT` and `TRAEFIK_HTTPS_PORT` in `.devcontainer/.env` before rebuilding. The app URLs and OAuth redirects expect HTTPS on port 443, so use the default ports for the full sign-in flow. ### One-time certificate setup Terrakube uses a local mkcert certificate. Install mkcert using its upstream instructions for your platform, then trust its local CA once on the host: ``` mkcert -install ``` Generate the certificate before opening the Dev Container: ``` mkdir -p .devcontainer/tls mkcert -cert-file .devcontainer/tls/cert.pem -key-file .devcontainer/tls/key.pem \ localhost terrakube.localhost terrakube-api.localhost \ terrakube-registry.localhost terrakube-executor.localhost \ terrakube-dex.localhost cp "$(mkcert -CAROOT)/rootCA.pem" .devcontainer/tls/rootCA.pem ``` Restart the browser after the one-time CA installation. If organisation policy blocks `mkcert -install`, follow your organisation's process for trusting a development CA; this cannot be automated portably without changing host trust settings. #### Corporate HTTPS inspection If your company proxies or inspects HTTPS traffic, Maven and other tooling need the company CA trusted inside the Dev Container. Put the approved root or intermediate CA in [certs](https://github.com/terrakube-io/terrakube/blob/main/.devcontainer/certs/README.md), then run **Dev Containers: Rebuild Container**. This also supplies the trusted store to Java tools bundled with VS Code, including the Java language server. The certificate remains local and is not committed. #### Running Example
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.terrakube.io/getting-started/development/dev-container.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.