{"id":20500026,"url":"https://github.com/klothoplatform/stackpacks","last_synced_at":"2025-06-10T17:35:05.917Z","repository":{"id":254900220,"uuid":"761921186","full_name":"klothoplatform/StackPacks","owner":"klothoplatform","description":null,"archived":false,"fork":false,"pushed_at":"2024-08-26T18:13:29.000Z","size":1678,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-05T19:35:00.742Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/klothoplatform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2024-02-22T18:30:07.000Z","updated_at":"2024-08-26T18:00:33.000Z","dependencies_parsed_at":"2024-08-28T00:32:45.138Z","dependency_job_id":null,"html_url":"https://github.com/klothoplatform/StackPacks","commit_stats":null,"previous_names":["klothoplatform/stackpacks"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klothoplatform%2FStackPacks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klothoplatform%2FStackPacks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klothoplatform%2FStackPacks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klothoplatform%2FStackPacks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/klothoplatform","download_url":"https://codeload.github.com/klothoplatform/StackPacks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klothoplatform%2FStackPacks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259118265,"owners_count":22807937,"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-15T18:19:32.656Z","updated_at":"2025-06-10T17:35:05.886Z","avatar_url":"https://github.com/klothoplatform.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# stacksnap\n\n\u003c!-- TOC --\u003e\n* [stacksnap](#stacksnap)\n  * [Development](#development)\n    * [WSL2](#wsl2)\n  * [Format](#format)\n  * [CLI](#cli)\n  * [Personal Stacks](#personal-stacks)\n  * [Docker Images](#docker-images)\n    * [Using a Custom Docker Image](#using-a-custom-docker-image)\n      * [Declaring Custom Docker Images](#declaring-custom-docker-images)\n      * [Referencing Custom Docker Images](#referencing-custom-docker-images)\n      * [Configuring Docker Image Resolution](#configuring-docker-image-resolution)\n    * [Building and Pushing Docker Images](#building-and-pushing-docker-images)\n    * [Versioning Docker Images](#versioning-docker-images)\n\u003c!-- TOC --\u003e\n\n\n## Development\n\n### WSL2\nWhen developing on WSL2, use the [wsl-compose.yml](./wsl-compose.yml) file to start the backend's dependencies.\n\nThis file overrides incompatible settings like volume for dynamodb-local.\n\nExample:\n\n```shell\ndocker compose -f wsl-compose.yml up -d\n```\n\n\n## Format\n\n```yaml\nname: # The human-readable name of the stack pack\nversion: # Semver version of the stack pack, not used for now, but will be used in the future\n\nbase: # These are the default, basic features of the stack pack\n  # Resources are a map from the resource ID to Properties. These will get converted\n  # into constraints (both application \u0026 resource)\n  resources:\n    aws:type:name:\n      LoadBalancers[0].ContainerPort: 8065 # Properties are in \"constraint\" format, not in template (ie, nested) format\n      Cpu: ${CPU} # Can use configuration variables (see below)\n  edges: # Edges are more-or-less the same as in resources.yaml and get converted to edge constraints\n    aws:a:b -\u003e aws:x:y:\n  files: # Files describe files that need to be copied into the output folder.\n    Dockerfile:\n    .env:\n      template: true # If true, the file is a template and will be rendered with the configuration\n\nconfiguration:\n  CPU: # This is an example of a value used in the base config\n    name: # The human-readable name of the configuration value\n    description: # Description of the configuration for the UI\n    type: # The type of the configuration value (string, int, float, boolean, enum)\n    default: # The default value of the configuration, required if used in the `base` section\n    validation: # Validation rules based on the type\n    initial_only: # Whether the value can only be set on initial configuration\n\n  XYZ:\n    type: boolean\n    default: false\n    values: # Values can be used as a \"switch\" for boolean or enum types\n      true: # the \"if\" or \"case\" value\n        # The contents are the same struct used in the `base` section\n        resources:\n          aws:s3_bucket:xyz-s3:\n        edges:\n          aws:ecs_service:svc -\u003e aws:s3_bucket:xyz:\n\n  DBPassword:\n    name: Database Password\n    type: string\n    pulumi_key: # The pulumi config key to use for this value, set before the 'pulumi up'\n```\n\n\n## CLI\n\nTo generate infrastructure output from a stackpack file run from the root of the project\n```sh\nPYTHONPATH=. python3.11 scripts/cli.py iac generate-iac --file ./path/to/file.yaml --config ./path/to/config.json --project-name sample-project --output-dir output\n```\n\n\n## Personal Stacks\n\nTo create the setup for you personal stack:\n```\nmdkir personal\ncp deploy/stacksnap.yaml personal/stacksnap.yaml\n```\n\nMake any modifications to the personal/stacksnap.yaml, including\n```\nREMOVE ALIAS\n    aws:cloudfront_distribution:stacksnap-distribution:\n      # TODO: figure out a way to make this less brittle\n      Aliases:\n        - dev.stacksnap.io\n\nMODIFY EMAIL (IF NECESSARY)\n    aws:ses_email_identity:stacksnap-email-identity:\n      EmailIdentity: stacksnap@klo.dev\n```\n\nTo generate infra directory, run:\n```\nENGINE_PATH=/path/to/engine IAC_PATH=/path/to/iac make generate-personal-infra\n```\n\nTo deploy, run:\n```\nKLOTHO_DIR=../klotho STACK_NAME=MY-STACK PULUMI_ACCESS_TOKEN=${ACCESS_TOKEN} REGION=us-east-2 make deploy-personal-infra\n```\n\n## Docker Images\n\nDocker images referenced by StackPacks must either be pulled from a public registry or built\nand pushed to ECR using the process described below.\n\n### Using a Custom Docker Image\n\n\n#### Declaring Custom Docker Images\nCustom Docker images can be declared in the `docker_images` section of the StackPack file.\nThe `docker_images` section is a map from image name to build configuration.\n    \n    ```yaml\n    id: my-stack\n    version: 0.1.0\n    docker_images:\n      my-image:\n        Dockerfile: path/to/Dockerfile\n        Context: path/to/context  \n      my-other-image:\n        # inferred\n        # Dockerfile: ./Dockerfile\n        # Context: .\n    ```\n\nThe resulting image's repository will be a combination of the StackPack ID and the image name.\nIf the image name matches the StackPack ID, the repository will be the StackPack ID.\n\nThe image will be tagged with the StackPack version.\n\nContext is relative to the current file's directory.\n\n#### Referencing Custom Docker Images\nCustom Docker images can be referenced in the `resources` section of the StackPack file using the following format:\n\n```yaml\nresources:\n  aws:ecs_task_definition:my-task:\n    ContainerDefinitions[0].Image: ${docker_image:my-image}\n```\n\nIn the example above, `${docker_image:my-image}` will be replaced with the URI of the Docker image in the ECR repository by the backend at run time during the constraint generation process.\n\n#### Configuring Docker Image Resolution\nThe backend will attempt to resolve custom Docker image URIs by substituting the following variables in the following format:\n\n`\u003cECR_REGISTRY\u003e/\u003cIMAGE_NAME\u003e\u003cECR_SUFFIX\u003e:\u003cVERSION\u003e`\n\n- **AWS_ACCOUNT** - The ID of the AWS account that stacksnap is deployed in. This ID will also be used as part of the ECR registry URI for custom Docker images.\n- **IMAGE_NAME** - The image name. This is the name of the image as declared in the `docker_images` section of the StackPack file, including the StackPack ID prefix.\n- **ECR_SUFFIX** - The suffix to append to the image name. This is an optional variable that can be set as an environment variable.\n- **VERSION** - The version of the image. This is the version of the StackPack.\n\n\n### Building and Pushing Docker Images\n\nTo build and push a Docker image to ECR, run one of the following commands (depending on the environment):\n\n**Local**\n```sh\nmake dockergen-local\n```\n\n**Dev**\n```sh\nmake dockergen-dev\n```\n\n**Prod**\n```sh\nmake dockergen-prod\n```\n\nThis will generate a Pulumi program that builds and pushes all custom Docker images declared in the StackPack files to ECR.\nThe program will be output in the `docker_images/\u003cENVIRONMENT\u003e` directory.\n\nCreate a stack and run `pulumi up` to deploy the Docker images to ECR.\n\n### Versioning Docker Images\n\nWhen making a change to an existing Docker image, running `pulumi up` without modifying the StackPack version will overwrite the existing image tag in ECR with the new image.\n\nTo create a new version of the Docker image, increment the StackPack version in the StackPack file and run `pulumi up` to push the new image to ECR with the new version tag.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklothoplatform%2Fstackpacks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fklothoplatform%2Fstackpacks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklothoplatform%2Fstackpacks/lists"}