LocalStack Initialization Hooks

LocalStack Initialization Hooks

Aug 28, 2023·

3 min read

So, you're already vibing with LocalStack, right? Well, hold onto your coding hats because I’m gonna let you in on a backstage secret: initialization hooks. These aren't your average hooks – they're like the cool sidekicks of LocalStack, ready to spruce things up.

Think of init hooks as your toolkit for behind-the-scenes customization, Shell or Python scripts that do your bidding when LocalStack hits the spotlight. Now, their superpower is pretty nifty – they let you pregame LocalStack's arrival with your own set of instructions.

So what's the game plan? When LocalStack starts up, these init hooks swing into action. They're like your crew setting the stage for the main event, whether it’s running services or exporting environment variables.

There are four well-defined lifecycle phases: BOOT, START, READY, and SHUTDOWN. At the BOOT phase, the container is up, but the LocalStack runtime has not started yet. The Python process is running during START, and the LocalStack runtime is being initialized. At the READY phase, LocalStack is fully prepared to serve requests. Lastly, during SHUTDOWN, LocalStack is in the process of shutting down.

You’ll find the corresponding directories for each phase under /etc/localstack/init: boot.d, start.d, ready.d, and shutdown.d. Users can mount individual files, stage directories, or even the entire init directory from their host into the LocalStack container.

When copying those scripts, a crucial move is making them execution-ready. Just give them the opportunity by running chmod +x script-name.sh, and that’s pretty much it

The scripts are sorted and executed in alphanumerical order, even if an earlier one fails. If they stumble with a non-zero exit or a Python one throws an exception, they're tagged with "ERROR."

Now, let's check out a quick example in a few breezy steps:

First, the architecture diagram:

The scene is quite simple: an API Gateway that serves endpoints for 2 Lambdas that save and fetch our favorite movie characters’ quotes, which are stored as text files in an S3 bucket. You can follow along with the repository.

  1. Clone the repo.

     git clone <https://github.com/tinyg210/stack-bytes-apigw-lambda-s3.git>
  2. Make sure the initialization file is executable.

     chmod +x init-resources.sh
  3. Export your LOCALSTACK_API_KEY as an environment variable.

  4. Ensure that these two lines are present in the docker-compose.yml file under volumes:

     - "./stack-bytes-lambda/target/apigw-lambda.jar:/etc/localstack/init/ready.d/target/apigw-lambda.jar"
     - "./init-resources.sh:/etc/localstack/init/ready.d/init-resources.sh"

    These two lines copy the Lambda .jar file and the script that creates the resources into the /etc/localstack/init/ready.d path in the container.

    *Sidenote: Make sure there’s apigw-lambda.jar in the /stack-bytes-lambda/target/ folder. If not, or if anything fails, please run mvn clean package shade:shade in the stack-bytes-lambda folder.

  5. Start LocalStack (in the root folder):

     docker compose up

And that’s it! The logs should show you the complete process of creating the resources. We’re using a custom REST API ID to keep the URL unchanged with every script run.

Let’s test it:

  • POST request (We’re using Postman, as it takes care of the headers for us):

  • GET request:

This flexibility in utilizing init hooks empowers users to finely tune their LocalStack instances and seamlessly integrate customized logic or configurations as per their specific requirements.

Everything works as expected. Now you can focus solely on developing and testing your client application!