{"id":25521890,"url":"https://github.com/rotiroti/alessandrina","last_synced_at":"2026-02-26T21:35:42.648Z","repository":{"id":218270849,"uuid":"662104194","full_name":"rotiroti/alessandrina","owner":"rotiroti","description":"Example of serverless application using Go, AWS SAM and GitHub Actions","archived":false,"fork":false,"pushed_at":"2025-10-22T20:51:13.000Z","size":236,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-22T22:24:24.852Z","etag":null,"topics":["artilleryio","aws-sam-cli","ci-cd","docker","go"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rotiroti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-07-04T11:11:08.000Z","updated_at":"2025-10-22T20:49:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"86cfa012-0ebf-46a9-bb2c-3744afcd8047","html_url":"https://github.com/rotiroti/alessandrina","commit_stats":null,"previous_names":["rotiroti/alessandrina"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rotiroti/alessandrina","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rotiroti%2Falessandrina","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rotiroti%2Falessandrina/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rotiroti%2Falessandrina/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rotiroti%2Falessandrina/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rotiroti","download_url":"https://codeload.github.com/rotiroti/alessandrina/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rotiroti%2Falessandrina/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29873307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-26T21:05:00.265Z","status":"ssl_error","status_checked_at":"2026-02-26T20:57:13.669Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["artilleryio","aws-sam-cli","ci-cd","docker","go"],"created_at":"2025-02-19T18:17:32.671Z","updated_at":"2026-02-26T21:35:42.582Z","avatar_url":"https://github.com/rotiroti.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Alessandrina\n\n[![codecov](https://codecov.io/gh/rotiroti/alessandrina/branch/main/graph/badge.svg?token=eWAHfGU54Y)](https://codecov.io/gh/rotiroti/alessandrina)\n![CI/CD](https://github.com/rotiroti/alessandrina/actions/workflows/pipeline.yaml/badge.svg)\n\nThis project aims to build a Go-based serverless application using AWS SAM. It provides an API with endpoints for interacting with a book database, allowing users to search, create, and delete books. The project also includes a robust CI/CD pipeline for automated build, test, and deployment on AWS using GitHub Actions.\n\n## Requirements\n\nTo set up and run this serverless application locally or in a cloud environment, ensure you have the following prerequisites:\n\n- [AWS Account](https://aws.amazon.com/account)\n- [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html)\n- [Go Programming Language](https://go.dev)\n- [GNU Make](https://www.gnu.org/software/make)\n- [Docker](https://www.docker.com)\n- [k6](https://k6.io/)\n- [Localstack](https://localstack.cloud) (required only for running AWS DynamoDB locally)\n\nOnce you have these prerequisites, you can set up and run the serverless application locally or deploy it to your preferred cloud environment.\n\n## Serverless Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/architecture.png\" alt=\"Alessandrina Architecture\"/\u003e\n\u003c/p\u003e\n\n## Project Structure\n\nThe serverless application is structured using the *hexagonal architecture* known as *ports and adapters*. This architectural pattern provides a way to separate the core business logic (`domain`) of the application from specific technical implementations, like the infrastructure (`database`) and the handling of client requests (`web`). Encapsulating the domain logic within the hexagon makes it easier to maintain and modify the application without affecting other components.\n\n```shell\n├── assets\n├── domain\n├── events\n├── functions\n│  ├── create-book\n│  ├── delete-book\n│  ├── get-book\n│  └── get-books\n├── go.mod\n├── go.sum\n├── locals.json\n├── Makefile\n├── README.md\n├── samconfig.toml\n├── scripts\n│  ├── create-table.sh\n│  └── delete-table.sh\n├── sys\n│  └── database\n│     ├── ddb\n│     └── memory\n├── template.yaml\n├── tests\n│  ├── integration\n│  └── performance\n└── web\n```\n\n### `/functions`\n\nThis project's entire AWS Lambda functions inside the `/functions` folder. The folders under `/functions` are consistently named for each lambda that SAM will build. Each folder has a matching source code file that contains the `main` package. None of the packages inside the folder `functions` can import each other.\n\n### `/tests`\n\nThe `/tests` folder houses a collection of `integration` and `performance` tests specifically designed to evaluate the functionality and performance of the serverless application. These tests are developed to simulate real-world scenarios and interactions with the application, ensuring it behaves as expected and performs optimally under different conditions.\n\n### `/events`\n\nThis folder contains multiple event bodies that can be passed to SAM when invoking the AWS serverless functions locally.\n\n```shell\nsam local invoke CreateBookFunction \\\n   -e events/create-book.json \\\n   --docker-network alessandrina \\\n   --env-vars locals.json\n```\n\n### `/scripts`\n\nThis folder contains shell scripts to perform migrations when running DynamoDB on Localstack.\n\n## Environment Variables for SAM\n\nThe serverless application can be configured via some environment variables.\n\n```shell\n# Set the table name (mandatory)\nDB_TABLE=BooksTable-local\n\n# Set the DynamoDB client connection (possible values: aws|localstack, default: aws)\nDB_CONNECTION=localstack\n\n# Enable AWS Client Logs for the DynamoDB service (default: false)\n#\n# When running with DB_CONNECTION=localstack, client logs are enabled as default\nDB_LOG=true\n```\n\n## Makefile Commands\n\n```shell\n# Perform unit tests.\nmake unit-tests\n\n# Run unit tests and create an HTML code coverage report.\nmake coverage\n\n# Format Go source files.\nmake format\n\n# Run Go linters aggregator (golangci-lint) using Docker.\nmake lint\n\n# Perform integration tests. (see Integration Tests setup section)\nmake integration-tests\n\n# Generate Go mocks\nmake mocks\n\n# Remove Go mocks\nmake remove-mocks\n\n# Cleanup artifacts, coverage and report files.\nmake clean\n```\n\n## Integration Tests\n\nThe integration tests assume that you have already installed all the requirements mentioned in the \"Requirements\" section.\n\n### Running on SAM Local API + Localstack DynamoDB\n\n```shell\n# 1. Create a Docker network\ndocker create network alessandrina\n\n# 2. Start the Localstack server.\nDOCKER_FLAGS=\"--network alessandrina -d\" localstack start\n\n# 3. Create a new DynamoDB table on Localstack\nsh ./scripts/create-table.sh BooksTable-local\n\n# 4. Build the serverless application.\nsam build --parallel\n\n# 5. Start a local HTTP API server using the \"BooksTable-local\" DynamoDB table.\nsam local start-api --docker-network alessandrina --warm-containers LAZY --env-vars locals.json\n\n# 6. Open another shell and execute the command in the project's root directory.\nmake integration-tests\n```\n\n### Running on AWS (feature, dev, prod branches)\n\n```shell\n# 1. Build the serverless application\nsam build --parallel\n\n# 2. Run integration tests\nmake integration-tests API_URL=\u003cSTACK_WEBPOINT_URL\u003e\n```\n\n## Performance Tests\n\nThe performance tests assume that you have already installed all the requirements mentioned in the \"Requirements\" section.\n\n### Environment Variables for k6\n\n```shell\n# Set the API URL (mandatory)\nAPI_URL=\u003cSTACK_WEBPOINT_URL\u003e\n\n# Set the workload (possible values: 0|1|2, default: 0)\nWORKLOAD=0\n\n# Set the book operation (mandatory, possible values: list|create|flow)\nBOOK_OP=list\n\n# Set the test name (default: main.js)\nTEST_NAME=smoke-create\n```\n\n### Run a test locally\n\n```shell\nAPI_URL=\u003cSTACK_WEBPOINT_URL\u003e BOOK_OP=list k6 run ./tests/performance/main.js\n```\n\n#### Authenticate with Grafana Cloud\n\n```shell\nk6 login cloud --token \u003cPERSONAL_API_TOKEN\u003e\n```\n\n### Run a test in the cloud\n\n```shell\n./k6 cloud -e K6_CLOUD_PROJECT_ID=\u003cPROJECT_ID\u003e \\\n  -e API_URL=\u003cSTACK_WEBPOINT_URL\u003e \\\n  -e TEST_NAME=\u003cTEST_NAME\u003e \\\n  -e BOOK_OP=\u003cBOOK_OP\u003e \\\n  ./tests/performance/main.js\n```\n\n### Run a test locally and stream the results to Grafana Cloud\n\n```shell\n./k6 run -e K6_CLOUD_PROJECT_ID=\u003cPROJECT_ID\u003e\\\n  -e API_URL=\u003cSTACK_WEBPOINT_URL\u003e \\\n  -e TEST_NAME=\u003cTEST_NAME\u003e \\\n  -e BOOK_OP=\u003cBOOK_OP=\u003cBOOK_OP\u003e \\\n  -e WORKLOAD=\u003cWORKLOAD\u003e \\\n  --out cloud \\\n  --out dashboard=report=\u003cREPORT_NAME\u003e.html \\\n  ./tests/performance/main.js\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frotiroti%2Falessandrina","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frotiroti%2Falessandrina","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frotiroti%2Falessandrina/lists"}