Skip to main content
Version: 0.2.2

Quickstart

Emuplane runs as one container: the gateway and the console are two servers in the same image, and the state they own lives in the emulator's DynamoDB. The emulator itself is yours to run — MiniStack, LocalStack, moto or anything that speaks the same API.

What you need​

  • An emulator reachable from the Emuplane container. MiniStack on port 4566 is the reference setup.
  • A container runtime with compose: podman or docker.
  • Three settings — everything else has a default:
.env
EP_BACKEND=ministack
EP_BACKEND_URL=http://ministack:4566
EP_CONSOLE_URL=http://localhost:4570
EP_GATEWAY_URL=http://localhost:4571

EP_BACKEND picks the profile (generic, ministack, floci, localstack, moto); EP_BACKEND_URL is the only value that has to be right.

Pull it​

The image is published to the GitHub Container Registry: ghcr.io/mathewmusango/emuplane. Every release tags its version and moves latest to the same digest.

docker pull ghcr.io/mathewmusango/emuplane:latest # the newest release
docker pull ghcr.io/mathewmusango/emuplane:<version> # the tag docker-compose.yml names

The compose files pin a version, so bringing the stack up never changes the image under you; latest is there for a quick look at the newest release.

Start it​

The whole stack — MiniStack, its first-setup job and the control — fits in one file:

cp .env.all.example .env.all
docker compose --env-file .env.all -f docker-compose.all.yml up -d

The emulator is internal to that network and never published; the console answers on http://localhost:4570 and the gateway on http://localhost:4571.

Already running an emulator? Point EP_BACKEND_URL at it and skip the bundled one:

cp .env.example .env # set EP_BACKEND_URL to the backend's endpoint
docker compose up -d

Either way, the compose depends_on runs the bootstrap service to completion before the control starts. Bootstrap applies bootstrap/template.yml as the emuplane stack — the DynamoDB tables Emuplane keeps its own accounts and sessions in — and is idempotent. The control refuses to serve if those tables are missing, rather than starting and failing on the first login.

By hand, the same thing:

docker compose run --rm bootstrap
docker compose up -d emuplane

Two ports are published on loopback only:

PortWhat it is
4570Console and control API
4571Gateway for your tools

The first account​

Nothing is seeded, so open localhost:4570/signup and create the first root user. That account owns everything until you add more.

The sign-in screen: root user or IAM user

The sign-in screens mirror the AWS ones: user type, credentials, then MFA.

Your first bucket​

  1. Sign in at /login with the root user you just made.
  2. The region menu at the top picks the region every page acts in. A region an account has not used yet is enabled on first use.
  3. S3 → Create bucket. Give it a name and leave the defaults.
  4. Open the bucket. Its Objects tab is empty because the bucket is.

Prove it from outside the console​

Mint an access key for the account in the console (Account → Access keys), then point the AWS CLI at the gateway:

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
aws s3 cp ./README.md s3://<your-bucket>/README.md

The gateway resolves the account from the key, checks that the request's signing region is enabled for that account, and forwards it. The object you uploaded is now in the console's Objects tab.

Where next​