{"id":48247934,"url":"https://github.com/scartill/easysam","last_synced_at":"2026-04-04T20:42:39.764Z","repository":{"id":294748578,"uuid":"983955567","full_name":"scartill/easysam","owner":"scartill","description":"Opinionated Modular Cloud Deployment Tool ","archived":false,"fork":false,"pushed_at":"2026-03-21T06:54:19.000Z","size":483,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-21T22:25:18.933Z","etag":null,"topics":["aws","cicd","cloud","deployment","dynamodb","lambda","serverl"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/easysam/","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"adsight-app/easysam","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scartill.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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":"2025-05-15T07:09:38.000Z","updated_at":"2026-03-21T06:54:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/scartill/easysam","commit_stats":null,"previous_names":["scartill/easysam"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/scartill/easysam","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scartill%2Feasysam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scartill%2Feasysam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scartill%2Feasysam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scartill%2Feasysam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scartill","download_url":"https://codeload.github.com/scartill/easysam/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scartill%2Feasysam/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31413282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: 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":["aws","cicd","cloud","deployment","dynamodb","lambda","serverl"],"created_at":"2026-04-04T20:42:38.198Z","updated_at":"2026-04-04T20:42:39.753Z","avatar_url":"https://github.com/scartill.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EasySAM\n\nEasySAM is an opinionated YAML-to-SAM generator for modular AWS serverless applications.\n\nIt helps you define Lambda functions, API Gateway routes, DynamoDB tables, S3 buckets, SQS queues, Kinesis streams, OpenSearch Serverless collections, and IoT Core authorizers in a compact `resources.yaml` model, then generate and deploy the resulting SAM stack.\n\n## Why EasySAM\n\n- Simple YAML-first resource definitions\n- Recursive import system (`import` + local `easysam.yaml`)\n- Modular app structure with shared `common/` code support\n- Built-in validation (`inspect schema`, `inspect cloud`)\n- Native support for:\n  - Environment variable expansion and `.env` loading\n  - DynamoDB stream triggers from table definitions\n  - DynamoDB TTL\n  - Lambda Function URLs\n  - Prismarine model-driven tables\n  - OpenSearch Serverless search collections\n  - MQTT/IoT Core custom authorizers\n\n## Prerequisites\n\n- Python 3.12+ (Your local/CI environment version should match the `python:` option in `resources.yaml` to ensure dependency compatibility)\n- AWS credentials configured (named profile recommended)\n- AWS SAM CLI 1.138.0+\n- `pip` 25.1.1+ (used in deployment checks)\n- One of:\n  - `uv` (recommended for project-local workflows)\n  - `pipx` (recommended for global CLI install)\n  - `pip`\n\n## Installation\n\nChoose one installation method.\n\n### Option A: project-local with uv\n\n```bash\nuv add --dev easysam\n```\n\nUse as:\n\n```bash\nuv run easysam --help\n```\n\n### Option B: global with pipx\n\n```bash\npipx install easysam\n```\n\nUse as:\n\n```bash\neasysam --help\n```\n\n### Option C: global/local with pip\n\n```bash\npip install easysam\n```\n\n## Quick start (5 minutes)\n\n1. Create a Python project and initialize EasySAM:\n\n```bash\nmkdir my-easysam-app\ncd my-easysam-app\nuv init\nuv add --dev easysam\nuv run easysam init\n```\n\nFor a Prismarine scaffold:\n\n```bash\nuv run easysam init --prismarine\n```\n\n2. Validate your resources:\n\n```bash\nuv run easysam --environment dev inspect schema .\n```\n\n3. Generate templates:\n\n```bash\nuv run easysam --environment dev generate .\n```\n\n4. Deploy to AWS:\n\n```bash\nuv run easysam --environment dev --aws-profile my-profile deploy . --tag project=easysam-demo\n```\n\n5. Delete stack when done:\n\n```bash\nuv run easysam --environment dev --aws-profile my-profile delete --await\n```\n\nFor all options:\n\n```bash\nuv run easysam --help\n```\n\n## Minimal `resources.yaml`\n\n```yaml\nprefix: MyApp\n\nimport:\n  - backend\n```\n\nEasySAM recursively finds `easysam.yaml` files under `backend/` and merges them.\n\n## Local import file format (`easysam.yaml`)\n\n```yaml\nlambda:\n  name: myfunction\n  resources:\n    tables:\n      - MyItem\n  integration:\n    path: /items\n    open: true\n    greedy: false\n```\n\nYou can also define tables locally:\n\n```yaml\ntables:\n  MyItem:\n    attributes:\n      - name: ItemID\n        hash: true\n```\n\n## Key concepts\n\n### Environment Variables and `.env` files\n\nEasySAM automatically loads `.env` files if present in the target directory. It evaluates environment variables using the standard `${MY_VAR}` syntax in both global (`resources.yaml`) and local (`easysam.yaml`) files immediately after they are loaded.\n\nYou can also pass environment variables to your functions directly using the `envvars` property.\n\n```yaml\nfunctions:\n  myfunc:\n    uri: \"src/\"\n    envvars:\n      API_URL: \"${API_URL}\"\n      LOG_LEVEL: \"DEBUG\"\n```\n\n### DynamoDB table triggers\n\nTrigger a Lambda directly from table changes:\n\n```yaml\ntables:\n  SearchableItem:\n    attributes:\n      - name: ItemID\n        hash: true\n    trigger: indexfunc\n```\n\nAdvanced trigger configuration:\n\n```yaml\ntables:\n  SearchableItem:\n    attributes:\n      - name: ItemID\n        hash: true\n    trigger:\n      function: indexfunc\n      viewtype: new-and-old\n      batchsize: 10\n      batchwindow: 5\n      startingposition: latest\n```\n\n### Conditional resources\n\nConditional keys are resolved against deploy context (`environment`, `target_region`):\n\n```yaml\nbuckets:\n  ? !Conditional\n    key: my-bucket\n    environment: prod\n    region: eu-west-2\n  :\n    public: true\n    extaccesspolicy: ProdPolicy\n```\n\nNegation is supported using `~` (example: `environment: ~prod`).\n\n### Deployment context overrides\n\nUse a context file for CI/environment-specific patches:\n\n```yaml\noverrides:\n  buckets/my-bucket/public: true\n```\n\nThen pass it with:\n\n```bash\nuv run easysam --environment dev --context-file deploy-context.yaml deploy .\n```\n\n### Prismarine integration\n\n```yaml\nprismarine:\n  default-base: common\n  access-module: common.dynamo_access\n  modelling: typed-dict\n  tables:\n    - package: myobject\n```\n\nSet `modelling: pydantic` for Pydantic-based generated clients.\n\n### MQTT / IoT Core custom authorizer\n\n```yaml\nmqtt:\n  authorizer:\n    function: mqtt-auth\n  topics:\n    - channels/*\n```\n\nIf a function publishes to IoT topics, add `mqtt` in function `services`.\n\n## Documentation\n\n- [CLI reference](docs/CLI_REFERENCE.md)\n- [Resource reference](docs/RESOURCE_REFERENCE.md)\n- [Production hardening guide](docs/PRODUCTION_HARDENING.md)\n- [Examples catalog](example/README.md)\n\n## Examples\n\nAll examples live under `example/` and include focused scenarios such as:\n\n- minimal app bootstrap\n- conditionals and deploy context overrides\n- custom Lambda layers\n- global and local env vars (with `.env` file support) and plugins\n- DynamoDB TTL (plain + Prismarine)\n- Prismarine TypedDict and Pydantic modelling\n- OpenSearch Serverless + DynamoDB streams\n- Kinesis with multiple S3 destinations\n\nSee the full index: [example/README.md](example/README.md).\n\n## Development\n\n```bash\ngit clone https://github.com/adsight-app/easysam.git\ncd easysam\nuv sync\nsource .venv/bin/activate\n```\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md).\n\n## Support\n\nIf you hit an issue:\n\n1. Search [existing issues](https://github.com/adsight-app/easysam/issues)\n2. Open a new issue with a reproducible example\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscartill%2Feasysam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscartill%2Feasysam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscartill%2Feasysam/lists"}