Skip to content

AWS ECS Anisette Account Bootstrap Runbook

Purpose

This runbook documents the interactive Apple account bootstrap step used to create account.json for the tracker fetcher stack.

The bootstrap script is intended to run inside the ECS task that already has:

  • network access to the private Anisette service
  • access to the shared /data EFS mount
  • ECS Exec enabled for an interactive shell

What Changed

The bootstrap script now reads these values from the environment:

  • ANISETTE_SERVER
  • ACCOUNT_STORE_PATH

That means the same script works in ECS without hardcoding Compose-only hostnames.

Anisette Endpoint

When staging Terraform enables Anisette, it registers a private Cloud Map service named anisette-v3 in the anisette-v3.local namespace.

The resulting private FQDN is:

  • anisette-v3.anisette-v3.local

The tracker fetcher should use:

  • http://anisette-v3.anisette-v3.local:6969

Bootstrap Flow

1. Confirm the service is healthy

Verify that the Anisette ECS service is running and that the private DNS name resolves inside the VPC.

2. Start a one-off ECS task

Use the tracker fetcher task definition or image, with the same EFS-backed /data volume that production uses.

Run the helper script from the repo root:

bash ./scripts/bootstrap_anisette_account.sh

By default the script uses:

  • AWS_PROFILE=glimpse-staging
  • AWS_REGION=eu-west-2
  • TERRAFORM_DIR=infra/envs/staging

To target a different environment, override those variables before running the script. For example:

AWS_PROFILE=glimpse-prod TERRAFORM_DIR=infra/envs/prod bash ./scripts/bootstrap_anisette_account.sh

3. Open an interactive shell

The helper script opens the ECS Exec session for you.

If you need to run it manually, the script derives the cluster and service names from Terraform's resource_prefix output and always uses the tracker-fetcher-2 container name.

4. Run the bootstrap script

Inside the container, run:

export ANISETTE_SERVER=http://anisette-v3.anisette-v3.local:6969
export ACCOUNT_STORE_PATH=/data/account.json
python scripts/authenticate_findmy.py

The script will prompt for:

  • Apple ID email
  • password
  • 2FA method, if required
  • OTP code, if required

5. Verify the output

Confirm the script saved the account file to:

  • /data/account.json

If the file is on EFS, the long-running tracker fetcher service can reuse it.

6. Restart the fetcher service

The helper script asks whether to force a new deployment of tracker-restapi-staging-tracker-fetcher-2 after the shell session ends.

Operational Notes

  • Do not hardcode http://anisette:6969 in ECS.
  • Do not store the account file in the image layer.
  • Keep account.json on the shared EFS mount.
  • If the private DNS name does not resolve, check Cloud Map registration and VPC DNS.
  • The helper script resolves resource_prefix, ecs_task_definition_arns, private_subnet_ids, ecs_security_group_id, and anisette_service_url from Terraform directly.
  • If ECS Exec returns TargetNotConnected, verify the task role includes the ssmmessages channel permissions and the VPC has an ssmmessages interface endpoint.