Skip to content
mathewmusangoPublic

About

The control plane, console and gateway for AWS-compatible emulators

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Emuplane — the console, control API and gateway for AWS-compatible emulators

Documentation Python 3.13 | 3.14 | 3.15 ghcr.io OpenSSF Best Practices OpenSSF Scorecard License

Checks Tests Docs Security CodeQL Semgrep Trivy Scorecard Dependabot Updates


Emuplane is not an emulator, and not a replacement for AWS. It is what you put in front of an emulator like MiniStack.

The console and the control API are the front door; accounts, logins and access keys live in the emulator's DynamoDB, never on the host.

Note

MiniStack is the only emulator this is tested against. Another one that speaks the same protocol points at the same EP_BACKEND_URL, but nothing else is verified.

cp .env.example .env    # EP_BACKEND_URL: the emulator as the container sees it
podman-compose up -d    # or: docker compose up -d

The container must reach that address: an emulator container on a shared network (http://ministack:4566), or one on the host listening beyond loopback (http://host.containers.internal:4566 on Podman, http://host.docker.internal:4566 on Docker Desktop).

The image is ghcr.io/mathewmusango/emuplane, published per release: docker pull ghcr.io/mathewmusango/emuplane:latest fetches the newest, and the compose file names the pinned tag it runs.

Or bring the emulator along: docker-compose.all.yml with .env.all.example runs MiniStack (ministackorg/ministack:1.5.40-full), the first-setup job and the control as one stack.

bootstrap runs first and applies the CloudFormation stack that owns the control's DynamoDB tables; the console then answers on http://localhost:4570.

More: Quickstart — the emulator first, then the first account and the first bucket.

Nothing is seeded: create the first account at /signup.

The console

Sign in, then the services the console has a page for are one click away. Everything else the instance answers is reachable over the wire.

The sign-in screen All services, after sign-in

Accessing it

What On the host In the compose network Behind a proxy
Console and control API http://localhost:4570/ http://emuplane:4570 EP_CONSOLE_URL
AWS gateway http://localhost:4571 http://emuplane:4571 EP_GATEWAY_URL
export AWS_ENDPOINT_URL=http://localhost:4571
export AWS_ACCESS_KEY_ID=<the key id from the console>
export AWS_SECRET_ACCESS_KEY=<the secret, shown once>
aws s3 ls

The host ports bind 127.0.0.1 and the backend is never published — a client wants the gateway, never the emulator. An issued AKIA… key is verified; the 12-digit account id is that account's root and is accepted with any secret.

More: Accessing it — the per-command form, the region rule, and the two kinds of key.

Documentation

Page What it covers
Quickstart two containers, one sign-in, one bucket
The console the frame, the service pages, and what each one can read
Access keys minting a key and using it from the CLI
Architecture the gateway, the control plane and the emulator
S3 the console's S3 pages
Control API every console route
Configuration every EP_ setting
Contributing how to report a bug or an idea, and what a pull request has to clear

Layout

Path What it is
control/ gateway, console pages, control API
web/ the React + Cloudscape console (its own README)
site/ the documentation site
bootstrap/ the CloudFormation template and init job for the control's tables
scripts/ the QA gate and the maintainer's helpers
docker-compose.yml, docker-compose.all.yml the container contract and the all-in-one stack

References

About

The control plane, console and gateway for AWS-compatible emulators

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages