{"id":28940382,"url":"https://github.com/fiam/dc2","last_synced_at":"2026-02-19T01:08:34.441Z","repository":{"id":287623269,"uuid":"922476425","full_name":"fiam/dc2","owner":"fiam","description":"DC2 is an EC2 emulator using Docker containers","archived":false,"fork":false,"pushed_at":"2025-04-13T09:32:28.000Z","size":83,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-18T09:53:25.441Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fiam.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,"zenodo":null}},"created_at":"2025-01-26T10:17:20.000Z","updated_at":"2025-04-13T09:32:31.000Z","dependencies_parsed_at":"2025-04-13T09:15:46.758Z","dependency_job_id":null,"html_url":"https://github.com/fiam/dc2","commit_stats":null,"previous_names":["fiam/dc2"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fiam/dc2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiam%2Fdc2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiam%2Fdc2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiam%2Fdc2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiam%2Fdc2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fiam","download_url":"https://codeload.github.com/fiam/dc2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fiam%2Fdc2/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261392169,"owners_count":23151719,"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":"2025-06-23T01:09:31.264Z","updated_at":"2026-02-19T01:08:34.432Z","avatar_url":"https://github.com/fiam.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dc2\n\n`dc2` is a lightweight EC2 emulator that runs Docker containers instead of\nvirtual machines. It is designed for local testing and CI workflows that need\nan EC2-like API surface.\n\n## Quick Start\n\n### Run from GHCR\n\n`dc2` needs access to the Docker socket because instances/volumes are backed by\nlocal Docker resources.\n\n```sh\ndocker run --rm \\\n  --name dc2 \\\n  -p 8080:8080 \\\n  -e ADDR=0.0.0.0:8080 \\\n  -v /var/run/docker.sock:/var/run/docker.sock \\\n  ghcr.io/fiam/dc2:latest\n```\n\nThen point your AWS SDK/CLI to `http://localhost:8080`:\n\n```sh\nAWS_ACCESS_KEY_ID=test \\\nAWS_SECRET_ACCESS_KEY=test \\\nAWS_REGION=us-east-1 \\\naws ec2 describe-instances --endpoint-url http://localhost:8080\n```\n\n### Compose Setup for Integration Tests\n\n```yaml\nservices:\n  dc2:\n    image: ghcr.io/fiam/dc2:latest\n    ports: [\"8080:8080\"]\n    environment:\n      ADDR: 0.0.0.0:8080\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n```\n\nIn your test container/app, configure the EC2/Auto Scaling clients to use\n`http://dc2:8080` as the service endpoint.\nInstance containers can access IMDS at\n`http://169.254.169.254/latest/user-data` and\n`http://169.254.169.254/latest/meta-data/instance-id` by default.\nMetadata reads require an IMDSv2 token from `PUT /latest/api/token` first.\nThe shared IMDS proxy runs as a dedicated OpenResty container and routes\nrequests to the owning `dc2` process.\nAll dc2-managed containers include `DC2_RUNTIME`:\n- `host` when `dc2` is running directly on the host.\n- `container` when `dc2` is running in a container.\n\n## Workload Network Reachability\n\nBy default, when `dc2` runs in a container, `RunInstances` containers are\nattached to the same workload network as that `dc2` container (for example, a\nCompose project network). This makes Compose setups work without extra flags.\n\nOutside containers, or when network auto-detection is unavailable, `dc2` falls\nback to Docker's `bridge` network.\n\nTo make workload instances reachable from other containers, set\n`INSTANCE_NETWORK=\u003cnetwork-name\u003e` (or `--instance-network \u003cnetwork-name\u003e`) and\nattach your test stack to the same Docker network.\n\nIf the named network already exists, `dc2` uses it as-is. Existing networks do\nnot need the `dc2:owned-network=true` label.\n\nIf the named network does not exist, `dc2` creates it and labels it\n`dc2:owned-network=true`, then removes it when unused during shutdown.\n\nWhen `INSTANCE_NETWORK` is unset, `dc2` prefers container-network\nauto-detection and otherwise uses `bridge`. In both cases, default networks are\nnot owned/removed by `dc2`.\n\nUse `DescribeInstances` to discover the instance address to call from your\ntest containers on the workload network.\nIn `dc2`, `PublicIpAddress` currently mirrors `PrivateIpAddress`, so either\nfield points to the same reachable container IP on that network.\n\nFor runnable walkthroughs and scripts, see [examples/README.md](examples/README.md).\n\n## Testing\n\n- `make test`: unit tests + host-mode integration tests.\n- `make test-integration-in-container`: integration tests with `dc2` running in a container.\n- `make test-e2e`: all long-running compose-backed end-to-end tests.\n- `make test-e2e E2E_TEST_FILTER=TestComposeAutoDetectsWorkloadNetworkByDefault`: run a subset of E2E tests.\n\n## Exit Resource Mode\n\n`dc2` controls shutdown cleanup/verification with `--exit-resource-mode` (or\n`DC2_EXIT_RESOURCE_MODE`):\n\n- `cleanup` (default): delete owned resources on exit, then fail shutdown if\n  any owned resources remain.\n- `keep`: do not cleanup or verify owned resources.\n- `assert`: do not cleanup, but fail shutdown if owned resources remain.\n\n## Build Metadata\n\n`dc2 --help` and `dc2 -version` include build metadata (version, commit,\ndirty state, and Go version).\n\nFor machine-readable diagnostics, `dc2` also serves an internal endpoint:\n\n```sh\ncurl -s http://localhost:8080/_dc2/metadata\n```\n\nThe endpoint is intentionally internal and not part of the EC2-compatible API\nsurface.\n\n## API Status\n\n| Area | Status | Notes |\n| --- | --- | --- |\n| EC2 Instances | Partial | Lifecycle APIs plus IMDSv2 instance-id/user-data/tag metadata support. |\n| EC2 Volumes | Supported | Create/attach/detach/delete + describe pagination. |\n| EC2 Launch Templates | Partial | Create/describe/delete/versioning + default-version updates. |\n| Auto Scaling Groups | Supported | Create/describe/update/set desired/delete, including event-driven replacement after out-of-band instance container delete/stop and Docker healthcheck failures. |\n\nSee [docs/API_SURFACE.md](docs/API_SURFACE.md) for the detailed per-action compatibility matrix.\nSee [docs/IMDS.md](docs/IMDS.md) for IMDS architecture and behavior details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffiam%2Fdc2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffiam%2Fdc2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffiam%2Fdc2/lists"}