{"id":18573136,"url":"https://github.com/localstack-samples/sample-pro-version-shipment-list-demo-lambda-dynamodb-s3","last_synced_at":"2025-10-17T08:35:52.063Z","repository":{"id":253484575,"uuid":"843645629","full_name":"localstack-samples/sample-pro-version-shipment-list-demo-lambda-dynamodb-s3","owner":"localstack-samples","description":"Shipment List demo application using the LocalStack Pro image.","archived":false,"fork":false,"pushed_at":"2024-08-17T02:59:07.000Z","size":36595,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-30T08:06:00.705Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/localstack-samples.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-17T02:06:46.000Z","updated_at":"2024-11-11T15:37:43.000Z","dependencies_parsed_at":"2024-08-17T05:45:13.355Z","dependency_job_id":null,"html_url":"https://github.com/localstack-samples/sample-pro-version-shipment-list-demo-lambda-dynamodb-s3","commit_stats":null,"previous_names":["localstack-samples/sample-pro-version-shipment-list-demo-lambda-dynamodb-s3"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/localstack-samples/sample-pro-version-shipment-list-demo-lambda-dynamodb-s3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack-samples%2Fsample-pro-version-shipment-list-demo-lambda-dynamodb-s3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack-samples%2Fsample-pro-version-shipment-list-demo-lambda-dynamodb-s3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack-samples%2Fsample-pro-version-shipment-list-demo-lambda-dynamodb-s3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack-samples%2Fsample-pro-version-shipment-list-demo-lambda-dynamodb-s3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/localstack-samples","download_url":"https://codeload.github.com/localstack-samples/sample-pro-version-shipment-list-demo-lambda-dynamodb-s3/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/localstack-samples%2Fsample-pro-version-shipment-list-demo-lambda-dynamodb-s3/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265558733,"owners_count":23787970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T23:08:07.830Z","updated_at":"2025-10-17T08:35:51.982Z","avatar_url":"https://github.com/localstack-samples.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Pro Image: Shipment List Demo Application - AWS in PROD and LocalStack on DEV environment\n\n\n| Environment | \u003cimg src=\"https://img.shields.io/badge/LocalStack-deploys-4D29B4.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAKgAAACoABZrFArwAAABl0RVh0U29mdHdhcmUAd3d3Lmlua3NjYXBlLm9yZ5vuPBoAAALbSURBVHic7ZpNaxNRFIafczNTGIq0G2M7pXWRlRv3Lusf8AMFEQT3guDWhX9BcC/uFAr1B4igLgSF4EYDtsuQ3M5GYrTaj3Tmui2SpMnM3PlK3m1uzjnPw8xw50MoaNrttl+r1e4CNRv1jTG/+v3+c8dG8TSilHoAPLZVX0RYWlraUbYaJI2IuLZ7KKUWCisgq8wF5D1A3rF+EQyCYPHo6Ghh3BrP8wb1en3f9izDYlVAp9O5EkXRB8dxxl7QBoNBpLW+7fv+a5vzDIvVU0BELhpjJrmaK2NMw+YsIxunUaTZbLrdbveZ1vpmGvWyTOJToNlsuqurq1vAdWPMeSDzwzhJEh0Bp+FTmifzxBZQBXiIKaAq8BBDQJXgYUoBVYOHKQRUER4mFFBVeJhAQJXh4QwBVYeHMQJmAR5GCJgVeBgiYJbg4T8BswYPp+4GW63WwvLy8hZwLcd5TudvBj3+OFBIeA4PD596nvc1iiIrD21qtdr+ysrKR8cY42itCwUP0Gg0+sC27T5qb2/vMunB/0ipTmZxfN//orW+BCwmrGV6vd63BP9P2j9WxGbxbrd7B3g14fLfwFsROUlzBmNM33XdR6Meuxfp5eg54IYxJvXCx8fHL4F3w36blTdDI4/0WREwMnMBeQ+Qd+YC8h4g78wF5D1A3rEqwBiT6q4ubpRSI+ewuhP0PO/NwcHBExHJZZ8PICI/e73ep7z6zzNPwWP1djhuOp3OfRG5kLROFEXv19fXP49bU6TbYQDa7XZDRF6kUUtEtoFb49YUbh/gOM7YbwqnyG4URQ/PWlQ4ASllNwzDzY2NDX3WwioKmBgeqidgKnioloCp4aE6AmLBQzUExIaH8gtIBA/lFrCTFB7KK2AnDMOrSeGhnAJSg4fyCUgVHsolIHV4KI8AK/BQDgHW4KH4AqzCQwEfiIRheKKUAvjuuu7m2tpakPdMmcYYI1rre0EQ1LPo9w82qyNziMdZ3AAAAABJRU5ErkJggg==\"\u003e \u003cimg src=\"https://img.shields.io/badge/AWS-deploys-F29100.svg?logo=amazon\"\u003e |\n|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| __Services__ | Amazon S3, Lambda, DynamoDB, SNS, SQS |\n| __Integrations__ | AWS SDK, Terraform, AWS CLI |\n| __Categories__ | Spring Boot, S3 Trigger |\n| __Level__ | Intermediate |\n| __Works on__ | LocalStack v3 |\n\n\n\n## Introduction\n\nThis application was created for demonstration purposes to highlight the ease of switching from\nusing actual AWS dependencies to having them emulated on LocalStack for your *developer environment* .\n\n## Architecture Overview\n\n![Diagram](app_diagram.png)\n\n## Prerequisites\n\n- [Maven 3.8.5](https://maven.apache.org/install.html) \u0026 [Java 17](https://www.java.com/en/download/help/download_options.html)\n- [AWS free tier account](https://aws.amazon.com/free/)\n- [LocalStack](https://localstack.cloud/)\n- [Docker](https://docs.docker.com/get-docker/) - for running LocalStack\n- [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) (+ Python pip for [tflocal](https://pypi.org/project/terraform-local/)) for creating AWS \u0026 LocalStack resources\n- [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) - for running the frontend app\n\n#### Application Overview\n\n*shipment-list-demo* is a Spring Boot application dealing with CRUD operations a person can execute\non a bunch of shipments that they're allowed to view - think of it like the Post app.\nThe demo consists of a backend and a frontend (using Rect) implementation, both running locally.\nThis depicts the phase of the application when it gets constant improvements, so development needs to be fast.\n\nThe AWS services involved are:\n\n- [S3](https://docs.localstack.cloud/user-guide/aws/s3/) for storing pictures\n- [DynamoDB](https://docs.localstack.cloud/user-guide/aws/dynamodb/) for the entities\n- [Lambda](https://docs.localstack.cloud/user-guide/aws/lambda/) function that will validate the pictures, apply a watermark and replace non-compliant files.\n- [SNS](https://docs.localstack.cloud/user-guide/aws/sns/) that receives update notifications\n- [SQS](https://docs.localstack.cloud/user-guide/aws/sqs/) that subscribes to a topic and delivers the messages to the Spring Boot app\n\n\n#### How to use it\n\nWe’ll walk through a few actions using the application, and we expect it to maintain the behavior in both production (AWS) and development (LocalStack) environments.\n\nLet's take advantage of one of the core features of the Spring framework that allows us to bind our\nbeans to different profiles, such as `dev`, and `prod`. Of course, these beans need to know how to\nbehave in each environment, so they’ll get that information from their designated configuration\nfiles, `application-prod.yml`, and `application-dev.yml`.\n\n#### Terraform\n\nThe Terraform configuration file will create the needed S3 bucket, the DynamoDB `shipment` table and populate it with some\nsample data, the Lambda function that will help with the picture processing (make sure you create the jar),\nthe SQS and SNS which will bring back the notification when the processing is finished.\n\nTerraform randomly generates names for the bucket, in order to avoid conflicts\nat a global scale on AWS. This name will be written out to a properties file, which the app will pick up\nand use for the S3 client. Furthermore, the name is also passed as an environment variable to the Lambda function by Terraform,\nso there's no need to worry about managing it.\n\n## Instructions\n\n### Only run once\n\nThe following instructions only need to run once, weather you choose to run both cases, on AWS and LocalStack, or just jump straight to LocalStack.\n\n### Building the validator module\n\nStep into the `shipment-picture-lambda-validator` module and run `mvn clean package shade:shade`.\nThis will create an uber-jar by packaging all its dependencies. We'll need this one in the next steps. \nWe can keep the same jar for running on AWS and LocalStack.\n\n### Running the GUI\n\n`cd` into `src/main/shipment-list-frontend` and run `npm install` and `npm start`.\nThis will spin up the React app that can be accessed on `localhost:3000`.\nYou'll only see the title, as the backend is not running yet to provide the list of shipments.\n\nFor running it on Windows, there are some\n[extra requirements](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/react-on-windows), but no worries, it should be straightforward.\n\n## Running on AWS\n\nNow, we don’t have a real production environment because that’s not the point here, but most likely\nan application like this runs on a container orchestration platform, and all the necessary configs are still provided. \nSince we’re only simulating a production instance, all the configurations are kept in the `application-prod.yml` file.\n\n### User credentials\n\nBefore getting started, it's important to note that an IAM user needs to be created with the `AdministratorAccess` policy. \nSome companies will have more restrictive and fine-grained permissions defined, for allowing the creation/update of each individual resource.\nIn this case, we will choose an umbrella policy, that covers all our needs.\n\nFor simplicity, we chose to use full access to all the services, so we don't have to add new permissions later on.\nWe will use the user's credentials and export them as temporary environment variables with the\n`export` (`set` on Windows) command:\n\n```\n$ export AWS_ACCESS_KEY_ID=[your_aws_access_key_id]\n$ export AWS_SECRET_ACCESS_KEY=[your_aws_secret_access_key_id]\n```\n\n### Creating resources - running Terraform\n\nMake sure you have Terraform [installed](https://developer.hashicorp.com/terraform/downloads)\n\nUnder `terraform` run:\n\n```\n$ terraform init\n$ terraform plan\n```\n\nOnce these 2 commands run successfully and no errors occur, it's time to run:\n\n```\n$ terraform apply\n```\nIf everything finishes successfully, the AWS services should be up and running.\n\n### Starting the backend\n\nGo back to the root folder and run the backend simply by using\n\n```\n$ mvn spring-boot:run -Dspring-boot.run.profiles=prod\n```\n\nNotice the `prod` profile is being set via command line arguments.\n\n#### How to use the GUI\n\nAfter starting the backend, refreshing the React app will fetch a list of shipments.\nThe weight of a shipment is already given, but not the size, that's why we need pictures to\nunderstand it better, using the \"banana for scale\" measuring unit. How else would we know??\nYou can add pictures from the `sample-pictures` folder.\n\nCurrent available actions using the GUI:\n\n- upload a new image\n- delete shipment from the list\n- create and update shipment are available only via Postman (or any other API platform)\n\nFiles that are not pictures will be deleted and the shipment picture will be replaced with a generic icon, because we don't want any trouble.\n\n### Using the application\n\nYou can now interact with the application using the React app. All services used in the backend are running on the real AWS cloud.\n\nBefore moving on, make sure you clean up your AWS resources by running (also in the `terraform` folder):\n\n```\n$ terraform destroy\n```\n\n## Running on LocalStack\n\n\nTo switch to using LocalStack instead of AWS services just run `docker compose up` in the root\nfolder to spin up a Localstack container.\n\n### Creating resources on LocalStack\n\nTo generate the exact same resources on LocalStack, we need `tflocal`, a thin wrapper script around\nthe terraform command line client. `tflocal` takes care of automatically configuring the local\nservice endpoints, which allows you to easily deploy your unmodified Terraform scripts against LocalStack.\n\nYou can [install](https://docs.localstack.cloud/user-guide/integrations/terraform/) the `tflocal`\ncommand via pip (requires a local Python installation):\n\n```\n$ pip install terraform-local\n```\n\nOnce installed, the `tflocal` command should be available, with the same interface as the terraform\ncommand line. Try it out:\n\n```\n$ tflocal --help\nUsage: terraform [global options] \u003csubcommand\u003e [args]\n...\n```\n\nFrom here on, it's the same as using AWS. In the `terraform` folder, run the `cleanup` script\nto get rid of any files that keep track of the resources' state. Then:\n\n```\n$ tflocal init\n$ tflocal plan\n$ tflocal apply\n```\n\nWe run the exact same commands for the exact same file. We no longer need to pass any environment variables, since the bucket name is generated and passed by Terraform.\n\n### Starting the backend\n\nAfter that, the Spring Boot application needs to start using the dev profile (make sure you're in the root folder):\n\n```\n$ mvn spring-boot:run -Dspring-boot.run.profiles=dev\n```\n### Using the application\n\nGo back to `localhost:3000` and a new list will be available; notice that the functionalities of the application have not changed.\n\nThere you have it, smooth transition from AWS to Localstack, with no code change. 👍🏻\n\n## Contributing\n\nWe appreciate your interest in contributing to our project and are always looking for new ways to improve the developer experience. We welcome feedback, bug reports, and even feature ideas from the community.\nPlease refer to the [contributing file](CONTRIBUTING.md) for more details on how to get started. \n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack-samples%2Fsample-pro-version-shipment-list-demo-lambda-dynamodb-s3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flocalstack-samples%2Fsample-pro-version-shipment-list-demo-lambda-dynamodb-s3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flocalstack-samples%2Fsample-pro-version-shipment-list-demo-lambda-dynamodb-s3/lists"}