{"id":18636676,"url":"https://github.com/localstack/devcontainer-template","last_synced_at":"2025-06-13T02:02:50.179Z","repository":{"id":251046261,"uuid":"817352408","full_name":"localstack/devcontainer-template","owner":"localstack","description":"LocalStack DevContainer Template(s)","archived":false,"fork":false,"pushed_at":"2024-08-23T07:20:09.000Z","size":84,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-06-13T02:01:59.386Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/localstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-19T14:21:06.000Z","updated_at":"2025-04-04T04:22:07.000Z","dependencies_parsed_at":"2024-07-31T15:55:02.578Z","dependency_job_id":"04554e1e-7f41-4477-b93c-9bf58832f0fa","html_url":"https://github.com/localstack/devcontainer-template","commit_stats":null,"previous_names":["localstack/devcontainer-template"],"tags_count":4,"template":false,"template_full_name":"devcontainers/template-starter","purl":"pkg:github/localstack/devcontainer-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Fdevcontainer-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Fdevcontainer-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Fdevcontainer-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Fdevcontainer-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localstack","download_url":"https://codeload.github.com/localstack/devcontainer-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack%2Fdevcontainer-template/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259565528,"owners_count":22877344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T05:31:07.132Z","updated_at":"2025-06-13T02:02:49.658Z","avatar_url":"https://github.com/localstack.png","language":"Shell","readme":"# DevContainer Templates\nA collection of LocalStack related and managed DevContainer Templates.\n\n\u003eDevelopment Container Templates are source files packaged together that encode configuration for a complete development environment.\nA Template can be used in a new or existing project, and a [supporting tool](https://containers.dev/supporting) will use the configuration from the Template to build a development container.\n\n\u003e[!NOTE]\n\u003e This repo follows the [**proposed** DevContainer Template distribution specification](https://containers.dev/implementors/templates-distribution/).\n\n\u003e[!WARNING]\n\u003e This repo currently a work in progress which might introduce breaking changes without notification.\n\n## List of Templates\n- LocalStack Docker-in-Docker: setup a devcontainer with LocalStack running in an internal Docker service\n- LocalStack Docker-outside-of-Docker: setup a devcontainer communicating with a separate LocalStack instance running on the same Docker network\n\n## Usage\n\nTo use either of the Templates use a supported tool and choose one of them, then either add custom values to the options or keep the defaults.\nAlternatively, copy the contents of the desired Template's `.devcontainer` folder and customize it as necessary.\n\nBoth variation of the Templates adds automatically the [official LocalStack DevContainer Feature](https://github.com/localstack/devcontainer-feature), which installs the CLI and by demand the most popular *Local Tools™*.\nCurrently this calls for a **Debian-based** DevContainer image.\n\n### LocalStack - Docker-in-Docker\n\nThis version of the Template starts up LocalStack in an internal Docker service in the DevContainer, hence we set a volume by default for data persistence.\nAs a result the newly built DevContainers do not necessarily need to re-download images as long this volume exists on the system.  \nAdditionally the DevContainer bind mounts a folder from the host system as `/data`, which will be used to store LocalStack data (`LOCALSTACK_VOLUME_DIR`).\n\nLocalStack in this variation is controlled via the LocalStack CLI and some env variables that you can adjust or expand in the `devcontainer.json` file's `remoteEnv` block.\nFor further LocalStack configuration options please consult our [official documentation](https://docs.localstack.cloud/references/configuration/).\n\n#### Use LocalStack Pro\n\nSet `usePro: true` and set on your host system the `LOCALSTACK_AUTH_TOKEN` or the `LOCALSTACK_API_KEY` environment variable, this will be automatically picked up by the Template.\n\n### LocalStack - Docker-outside-of-Docker\n\nThis version of the Template starts up LocalStack as a separate container in the same Docker network using the host system's Docker socket.\n\nTo control LocalStack's behaviour adjust the provided `.env` file which will be loaded both into LocalStack and the created DevContainer after rebuild.\nFor further customisation you can edit the provided `Dockerfile` and/or the `devcontainer.json` file.\nOr add additional services by modifying the provided `docker-compose.yml` file.\nFor further LocalStack configuration options please consult our [official documentation](https://docs.localstack.cloud/references/configuration/).\n\n\u003e[!WARNING]\n\u003e In this Template version however the LocalStack CLI provides the `start` and `stop` options do **NOT** control the LocalStack container with them as that would result in name resolution issues in the container.\n\u003e\n\u003e In case you've made this mistake by accident, try running `docker compose -f \u003cDEV_CONTAINER_CONFIG_LOCATION\u003e/docker-compose.yml up -d localstack` or rebuild the container.\n\n#### Use LocalStack Pro\n\nSet `usePro: true` and set on your host system the `LOCALSTACK_AUTH_TOKEN` or the `LOCALSTACK_API_KEY` environment variable, this will be automatically picked up by the `.env` file.\n\n## Repo and Template Structure\n\nThis repository contains a _collection_ of two Templates - `localstack-dind` and `localstack-dood`. Similar to the [`devcontainers/templates`](https://github.com/devcontainers/templates) repo, this repository has a `src` folder.  Each Template has its own sub-folder, containing at least a `devcontainer-template.json` and `.devcontainer/devcontainer.json`. \n\n```\n├── src\n│   ├── localstack-dind\n│   │   ├── devcontainer-template.json\n│   │   ├── inputs.json\n│   │   └──| .devcontainer\n│   │      └── devcontainer.json\n│   ├── localstack-dood\n│   │   ├── devcontainer-template.json\n│   │   └──| .devcontainer\n│   │      ├── .env\n│   │      ├── devcontainer.json\n│   │      ├── docker-compose.yaml\n│   │      └── Dockerfile\n|   ├── ...\n│   │   ├── devcontainer-template.json\n│   │   └──| .devcontainer\n│   │      └── devcontainer.json\n├── test\n│   ├── localstack-dind\n|   |   ├── scenarios.json\n|   |   ├── ...\n│   │   └── test.sh\n│   ├── localstack-dood\n|   |   ├── scenarios.json\n|   |   ├── ...\n│   │   └── test.sh\n│   └──test-utils\n│      └── test-utils.sh\n...\n```\n\n### Options\n\nAll available options for a Template should be declared in the `devcontainer-template.json`. The syntax for the `options` property can be found in the [devcontainer Template json properties reference](https://containers.dev/implementors/templates#devcontainer-templatejson-properties).\n\nFor example, the `localstack-dind` Template provides four possible options (`jammy`, `focal`, `bookworm`, `bullseye`), where the default value is set to `jammy`.\n\n```jsonc\n{\n    // ...\n    \"options\": {\n        \"imageVariant\": {\n            \"type\": \"string\",\n            \"description\": \"Debian version (use bullseye or jammy on local arm64/Apple Silicon):\",\n            \"proposals\": [\n                \"jammy\",\n                \"focal\",\n                \"bullseye\",\n                \"bookworm\"\n            ],\n            \"default\": \"jammy\"\n        }\n    }\n}\n```\n\nAn [implementing tool](https://containers.dev/supporting#tools) will use the `options` property from [the documented Dev Container Template properties](https://containers.dev/implementors/templates#devcontainer-templatejson-properties) for customizing the Template. See [option resolution example](https://containers.dev/implementors/templates#option-resolution-example) for details.\n\n## Distributing Templates\n\n**Note**: *Allow GitHub Actions to create and approve pull requests* should be enabled in the repository's `Settings \u003e Actions \u003e General \u003e Workflow permissions` for auto generation of `src/\u003ctemplate\u003e/README.md` per Template (which merges any existing `src/\u003ctemplate\u003e/NOTES.md`).\n\n### Versioning\n\nTemplates are individually versioned by the `version` attribute in a Template's `devcontainer-template.json`. Templates are versioned according to the semver specification. More details can be found in [the Dev Container Template specification](https://containers.dev/implementors/templates-distribution/#versioning).\n\n### Publishing\n\n\u003e[!NOTE]\n\u003e NOTE: The Distribution spec can be [found here](https://containers.dev/implementors/templates-distribution/).  \n\u003e\n\u003e While any registry [implementing the OCI Distribution spec](https://github.com/opencontainers/distribution-spec) can be used, this template will leverage GHCR (GitHub Container Registry) as the backing registry.\n\nTemplates are source files packaged together that encode configuration for a complete development environment.\n\nThis repo contains a GitHub Action [workflow](.github/workflows/release.yaml) that will publish each template to GHCR.  By default, each Template will be prefixed with the `\u003cowner\u003e/\u003crepo\u003e` namespace.  For example, the two Templates in this repository can be referenced by an [implementing tool](https://containers.dev/supporting#tools) with:\n\n```\nghcr.io/devcontainers/template-starter/color:latest\nghcr.io/devcontainers/template-starter/hello:latest\n```\n\nThe provided GitHub Action will also publish a third \"metadata\" package with just the namespace, eg: `ghcr.io/devcontainers/template-starter`. This contains information useful for tools aiding in Template discovery.\n\n'`devcontainers/template-starter`' is known as the template collection namespace.\n\n### Marking Template Public\n\nFor your Template to be used, it currently needs to be available publicly. By default, OCI Artifacts in GHCR are marked as `private`. \n\nTo make them public, navigate to the Template's \"package settings\" page in GHCR, and set the visibility to 'public`. \n\n```\nhttps://github.com/users/\u003cowner\u003e/packages/container/\u003crepo\u003e%2F\u003ctemplateName\u003e/settings\n```\n\n### Adding Templates to the Index\n\nNext you will need to add your Templates collection to our [public index](https://containers.dev/templates) so that other community members can find them. Just follow these steps once per collection you create:\n\n* Go to [github.com/devcontainers/devcontainers.github.io](https://github.com/devcontainers/devcontainers.github.io)\n     * This is the GitHub repo backing the [containers.dev](https://containers.dev/) spec site\n* Open a PR to modify the [collection-index.yml](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml) file\n\nThis index is from where [supporting tools](https://containers.dev/supporting) like [VS Code Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and [GitHub Codespaces](https://github.com/templates/codespaces) surface Templates for their Dev Container Creation Configuration UI.\n\n### Testing Templates\n\nThis repo contains a GitHub Action [workflow](.github/workflows/test-pr.yaml) for testing the Templates. Similar to the [`devcontainers/templates`](https://github.com/devcontainers/templates) repo, this repository has a `test` folder.  Each Template has its own sub-folder, containing at least a `test.sh`.\n\nFor running the tests locally, you would need to execute the following commands -\n\n```\n    ./.github/actions/smoke-test/build.sh ${TEMPLATE-ID} \n    ./.github/actions/smoke-test/test.sh ${TEMPLATE-ID} \n```\n\nTo override the default values for example for manual testing an `inputs.json` file can be defined in the Template's folder. The file's structure is the following:\n```json\n{\n    \"input1\": \"value1\",\n    \"input2\": \"value2\"\n...\n}\n```\n\n#### Scenario Tests\nAdditionally the repo had been extended for scenario testing. To define scenario tests, you would need to define a `scenarios.json` file in the respective Template's `test` folder. The file's structure is the following:\n\n```json\n{\n\t\"\u003cscenario_name\u003e\": {\n        \"\u003coption_name\u003e\": \"\u003coption_value\u003e\",\n        ...\n        \"input\": \"value\"\n\t},\n\t...\n\t\"my_scenario1\": {\n\t\t\"input1\": \"value1\",\n\t\t\"input2\": \"value2\"\n\t},\n\t\"my_scenario2\": {\n\t\t\"input1\": \"value2\"\n\t}\n}\n```\nBy defining a scenario, you additionally need to define a similarly named shell script in the folder, ie. if the scenario key was `test_with_my_input` needs a `test_with_my_input.sh` file.\n\nIn case of scenarios you can add any other valid DevContainer config options like `features` or `customizations`, that you'd use normally, these options will be merged into the resulting `devcontainers.json` file.\n\nFor running the tests locally, you would need to execute the following commands -\n\n```\n    ./.github/actions/scenario-test/controller.sh ${TEMPLATE-ID}\n```\n\n#### Input precedence\nTo test with different inputs custom values can be provided with the following precedence in a top to bottom approach (top=highest, bottom=lowest):\n1. `scenario.json` (only with scenario tests)\n2. `inputs.json`\n3. `devcontainer-template.json`\n\n### Updating Documentation\n\nThis repo contains a GitHub Action [workflow](.github/workflows/release.yaml) that will automatically generate documentation (ie. `README.md`) for each Template. This file will be auto-generated from the `devcontainer-template.json` and `NOTES.md`.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Fdevcontainer-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalstack%2Fdevcontainer-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack%2Fdevcontainer-template/lists"}