Lifecycle tasks operate on a persistent development instance owned by the current project, or the owner selected with useSharedRuntime. It stays running after Gradle exits, ready for interactive development. When sharing, stop and restart affect every application using that development instance; prefer fully qualified commands on the owner.
With an external connection, the plugin owns no lifecycle. Start, stop, restart, prepare, cleanup, logs, and scenario reset commands are rejected. Status, doctor, connection exports, and scenario seeding use the external endpoint without Docker.
Task Reference
| Task | Behavior |
|---|---|
|
Build the pinned image, or locate/pull a configured image override. |
|
Start the development container and wait for HTTPS readiness. Reuse an existing instance if its settings match. |
|
Gracefully stop and remove the development container and its generated connection files. Safe to repeat. |
|
Stop and start the development instance with the current settings and empty resource state. |
|
Report the development container’s state, health, and endpoint. |
|
Write metadata-only HTML and JSON inventories for all 13 provisioned service families in an existing instance. Does not start an instance. See resource reports. |
|
Print the last 100 lines of development-container logs. |
|
Inspect Docker, image availability, ports, all project-owned containers, connection files, and HTTPS health. Does not build, pull, or start an instance. Reports failures with corrective hints. |
|
Archive logs and remove stale managed containers for the runtime owner. |
|
Start or reuse development and write sourceable |
Start A Development Session
Commands select the default runtime unless given --runtime <name>. Each named runtime also has fixed lifecycle tasks, such as startAwsEmulatorIntegration, stopAwsEmulatorIntegration, and cleanupAwsEmulatorIntegration. Use the suffixed tasks to operate on several runtimes in one invocation. Status, doctor, logs, cleanup, stop, and restart are scoped to the selected name; other runtime owners are untouched.
From the plugin repository, use the example application:
./gradlew -p examples/basic startAwsEmulator -PawsEmulator.port=9297
./gradlew -p examples/basic statusAwsEmulator
./gradlew -p examples/basic logsAwsEmulator
./gradlew -p examples/basic stopAwsEmulator
In your own project, omit -p examples/basic. The start and status tasks report the actual endpoint and runtime directory, including when you select a port automatically.
An unrelated container with the same name is never adopted or stopped. The plugin checks ownership before operating on containers.
Change Settings Or Start Fresh
If the development instance is already running, changed settings require restartAwsEmulator:
./gradlew -p examples/basic restartAwsEmulator -PawsEmulator.port=0
|
Warning
|
The emulator keeps resources in memory. Stop and restart discard buckets, objects, queues, and messages. This emulator release has no state-persistence or reset API. |
The Docker image remains cached after an instance stops. prepareAwsEmulator can build or pull it ahead of a development session without starting a runtime.
To recreate resources and load a dataset after restarting, define a development scenario and run resetAwsEmulator. Use seedAwsEmulator to load its fixtures without discarding other state. With explicit cleanup steps, resetAwsEmulator -PawsEmulator.resetScope=RESOURCES cleans only the declared resources before reseeding, preserving the running instance. cleanAwsEmulator runs those cleanup steps alone. See selective reset for ordering and ownership rules.
Provision Development Resources
Set the default for custom resource tasks once on the extension:
import io.github.gregwhitaker.awsemulator.model.EmulatorMode
import io.github.gregwhitaker.awsemulator.aws.s3.CreateS3BucketTask
awsEmulator {
defaultMode.set(EmulatorMode.DEVELOPMENT)
}
tasks.register<CreateS3BucketTask>("createDevelopmentBucket") {
bucketName.set("application-development-data")
}
The default applies lazily to custom resource tasks across this project’s runtime names. Tasks can override it with their own mode; consumers select their mode separately. See resource task configuration for precedence and consumer alignment.
Alternatively, set the mode on an individual typed provisioning task:
import io.github.gregwhitaker.awsemulator.model.EmulatorMode
import io.github.gregwhitaker.awsemulator.aws.s3.CreateS3BucketTask
val developmentBucket = tasks.register<CreateS3BucketTask>("createDevelopmentBucket") {
mode.set(EmulatorMode.DEVELOPMENT)
bucketName.set("application-development-data")
}
Run ./gradlew createDevelopmentBucket in that application. The task starts or reuses the development instance and leaves it running. Use stopAwsEmulator to remove it.
Use MANAGED resource tasks for tests opted in with useWith. Development tasks do not seed the separate managed instance.
Recover From An Interrupted Build
Managed teardown saves complete available timestamped container logs in the runtime owner’s workingDirectory/logs/ (by default .aws-emulator/logs/) before removing the container and connection files. Each archive has a unique name containing the container ID; the build prints its path. Startup failures also save logs if a container was created. Archives are streamed to disk without the normal command-output buffer limit. Log retrieval or disk errors produce a warning and cleanup continues. Logs remain until explicitly deleted and may contain application output; credential files are never copied into the archive.
Graceful cleanup needs the Gradle process and Docker daemon to remain available. A hard kill or daemon failure can leave a container behind. Inspect and clean up this runtime owner’s stale managed containers with:
./gradlew doctorAwsEmulator
./gradlew cleanupAwsEmulator --report-only
./gradlew cleanupAwsEmulator
Cleanup checks project ownership labels and the runtime-home owner marker, then acquires the managed instance’s lifetime lock. A lock held by another build prevents removal, even if its container has exited. Released locks allow cleanup of abandoned running containers after a hard kill. Development instances are always skipped; stop them with stopAwsEmulator. A legacy running container without a lifetime lock is skipped because its activity is unknown; identify and stop it individually before retrying. Stopped legacy managed containers with valid ownership can be removed. Lock files under workingDirectory/locks/ are bookkeeping and remain after cleanup.
The plugin does not prune other projects' containers, images, or AWS configuration. When sharing a runtime, invoke the owner’s qualified task (for example :local-aws:cleanupAwsEmulator). See troubleshooting for startup and connection failures.