{"id":19447067,"url":"https://github.com/stacktape/starter-socketio-websocket-api-redis","last_synced_at":"2025-10-28T17:40:04.835Z","repository":{"id":226143560,"uuid":"679259779","full_name":"stacktape/starter-socketio-websocket-api-redis","owner":"stacktape","description":"Stacktape starter project","archived":false,"fork":false,"pushed_at":"2025-01-20T01:56:38.000Z","size":8,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-20T02:41:45.768Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://stacktape.com","language":"TypeScript","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/stacktape.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}},"created_at":"2023-08-16T12:52:34.000Z","updated_at":"2025-01-20T01:56:39.000Z","dependencies_parsed_at":"2024-06-26T14:49:35.873Z","dependency_job_id":"510cf42b-1fa3-4295-9bb2-5f4285332a36","html_url":"https://github.com/stacktape/starter-socketio-websocket-api-redis","commit_stats":null,"previous_names":["stacktape/starter-socketio-websocket-api-redis"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacktape%2Fstarter-socketio-websocket-api-redis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacktape%2Fstarter-socketio-websocket-api-redis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacktape%2Fstarter-socketio-websocket-api-redis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stacktape%2Fstarter-socketio-websocket-api-redis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stacktape","download_url":"https://codeload.github.com/stacktape/starter-socketio-websocket-api-redis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240636642,"owners_count":19832922,"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-10T16:16:19.402Z","updated_at":"2025-10-28T17:40:04.807Z","avatar_url":"https://github.com/stacktape.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Websocket API with Socket.io\n\n\u003e [!TIP]\n\u003e To deploy this project using **GUI-based flow**, navigate to [console](https://console.stacktape.com/create-new-project/git-project-using-console?name=my-stacktape-app\u0026repositoryType=public\u0026repositoryUrl=https://github.com/stacktape/starter-socketio-websocket-api-redis)\n\n- simple Websocket API built using [Socket.io](https://socket.io/).\n- The application runs in a\n  [container workload](https://docs.stacktape.com/compute-resources/multi-container-workloads/) and uses\n  [Upstash redis](https://docs.stacktape.com/resources/upstash-redis-databases/) to store the session data. The requests\n  are routed using [Application Load Balancer](https://docs.stacktape.com/resources/application-load-balancers/).\n- This project includes a pre-configured [stacktape.yml configuration](stacktape.yml).\nThe configured infrastructure is described in the [stack description section](#stack-description)\n\n## Pricing\n\n- Fixed price resources:\n\n  - **Container workload** (~$0.012/hour, ~$9/month)\n\n- There are also other resources that might incur costs (with pay-per-use pricing). If your load won't get high, these costs will be close to $0.\n\n## Prerequisites\n\n1. **AWS account**. If you don't have one, [create new account here](https://portal.aws.amazon.com/billing/signup).\n\n2. **Stacktape account**. If you don't have one, [create new account here](https://console.stacktape.com/sign-up).\n\n3. **Stacktape installed**.\n\n  \u003cdetails\u003e\n  \u003csummary\u003eInstall on Windows (Powershell)\u003c/summary\u003e\n\n  ```bash\n  iwr https://installs.stacktape.com/windows.ps1 -useb | iex\n  ```\n\n  \u003c/details\u003e\n  \u003cdetails\u003e\n  \u003csummary\u003eInstall on Linux\u003c/summary\u003e\n\n  ```bash\n  curl -L https://installs.stacktape.com/linux.sh | sh\n  ```\n\n  \u003c/details\u003e\n  \u003cdetails\u003e\n  \u003csummary\u003eInstall on MacOS\u003c/summary\u003e\n\n  ```bash\n  curl -L https://installs.stacktape.com/macos.sh | sh\n  ```\n\n  \u003c/details\u003e\n  \u003cdetails\u003e\n  \u003csummary\u003eInstall on MacOS ARM (Apple silicon)\u003c/summary\u003e\n\n  ```bash\n  curl -L https://installs.stacktape.com/macos-arm.sh | sh\n  ```\n\n  \u003c/details\u003e\n\n\n4. **Upstash account**. If you don't have one, [create new account here](https://console.upstash.com/login).\n\n## 1. Generate your project\nTo initialize the project, use\n\n```bash\nstacktape init --starterId socketio-websocket-api-redis\n```\n\n## 2. Before deploy\n- Fill in your Upstash credentials in the `providerConfig.upstash` section of the stacktape.yml config file. You can get your API key in the [Upstash console](https://console.upstash.com/account/api).\n\n## 3. Deploy your stack\n\nThe deployment will take ~5-15 minutes. Subsequent deploys will be significantly faster.\n\n\u003cdetails\u003e\n\u003csummary\u003eDeploy from local machine\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nThe deployment from local machine will build and deploy the application from your system. This means you also need to have:\n- Docker. To install Docker on your system, you can follow [this guide](https://docs.docker.com/get-docker/).- Node.js installed.\n\n\u003cbr /\u003e\n\nTo perform the deployment, use the following command:\n\n```bash\nstacktape deploy --projectName \u003c\u003cproject-name\u003e\u003e --stage \u003c\u003cstage\u003e\u003e --region \u003c\u003cregion\u003e\u003e\n```\n\n`stage` is an arbitrary name of your environment (for example **staging**, **production** or **dev-john**)\n\n`region` is the AWS region, where your stack will be deployed to. All the available regions are listed below.\n\n`projectName` is the name of your project. You can create it in the console or interactively using CLI.\n\n\u003cbr /\u003e\n\n| Region name \u0026 Location     | code           |\n  | -------------------------- | -------------- |\n  | Europe (Ireland)           | eu-west-1      |\n  | Europe (London)            | eu-west-2      |\n  | Europe (Frankfurt)         | eu-central-1   |\n  | Europe (Milan)             | eu-south-1     |\n  | Europe (Paris)             | eu-west-3      |\n  | Europe (Stockholm)         | eu-north-1     |\n  | US East (Ohio)             | us-east-2      |\n  | US East (N. Virginia)      | us-east-1      |\n  | US West (N. California)    | us-west-1      |\n  | US West (Oregon)           | us-west-2      |\n  | Canada (Central)           | ca-central-1   |\n  | Africa (Cape Town)         | af-south-1     |\n  | Asia Pacific (Hong Kong)   | ap-east-1      |\n  | Asia Pacific (Mumbai)      | ap-south-1     |\n  | Asia Pacific (Osaka-Local) | ap-northeast-3 |\n  | Asia Pacific (Seoul)       | ap-northeast-2 |\n  | Asia Pacific (Singapore)   | ap-southeast-1 |\n  | Asia Pacific (Sydney)      | ap-southeast-2 |\n  | Asia Pacific (Tokyo)       | ap-northeast-1 |\n  | China (Beijing)            | cn-north-1     |\n  | China (Ningxia)            | cn-northwest-1 |\n  | Middle East (Bahrain)      | me-south-1     |\n  | South America (São Paulo)  | sa-east-1      |\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eDeploy using AWS CodeBuild pipeline\u003c/summary\u003e\n\n\u003cbr /\u003e\n\nDeployment using AWS CodeBuild will build and deploy your application inside [AWS CodeBuild pipeline](https://aws.amazon.com/codebuild/). To perform the deployment, use\n\n```bash\nstacktape codebuild:deploy --stage \u003c\u003cstage\u003e\u003e --region \u003c\u003cregion\u003e\u003e --projectName \u003c\u003cproject-name\u003e\u003e\n```\n\n`stage` is an arbitrary name of your environment (for example **staging**, **production** or **dev-john**)\n\n`region` is the AWS region, where your stack will be deployed to. All the available regions are listed below.\n\n`projectName` is the name of your project. You can create it in the console or interactively using CLI.\n\n\u003cbr /\u003e\n\n| Region name \u0026 Location     | code           |\n  | -------------------------- | -------------- |\n  | Europe (Ireland)           | eu-west-1      |\n  | Europe (London)            | eu-west-2      |\n  | Europe (Frankfurt)         | eu-central-1   |\n  | Europe (Milan)             | eu-south-1     |\n  | Europe (Paris)             | eu-west-3      |\n  | Europe (Stockholm)         | eu-north-1     |\n  | US East (Ohio)             | us-east-2      |\n  | US East (N. Virginia)      | us-east-1      |\n  | US West (N. California)    | us-west-1      |\n  | US West (Oregon)           | us-west-2      |\n  | Canada (Central)           | ca-central-1   |\n  | Africa (Cape Town)         | af-south-1     |\n  | Asia Pacific (Hong Kong)   | ap-east-1      |\n  | Asia Pacific (Mumbai)      | ap-south-1     |\n  | Asia Pacific (Osaka-Local) | ap-northeast-3 |\n  | Asia Pacific (Seoul)       | ap-northeast-2 |\n  | Asia Pacific (Singapore)   | ap-southeast-1 |\n  | Asia Pacific (Sydney)      | ap-southeast-2 |\n  | Asia Pacific (Tokyo)       | ap-northeast-1 |\n  | China (Beijing)            | cn-north-1     |\n  | China (Ningxia)            | cn-northwest-1 |\n  | Middle East (Bahrain)      | me-south-1     |\n  | South America (São Paulo)  | sa-east-1      |\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eDeploy using Github actions CI/CD pipeline\u003c/summary\u003e\n\n\u003cbr /\u003e\n\n1. If you don't have one, create a new repository at https://github.com/new\n2. Create Github repository secrets: https://docs.stacktape.com/user-guides/ci-cd/#2-create-github-repository-secrets\n3. Replace `\u003c\u003cstage\u003e\u003e` and `\u003c\u003cregion\u003e\u003e` in the .github/workflows/deploy.yml file.\n4. `git init --initial-branch=main`\n5. `git add .`\n6. `git commit -m \"setup stacktape project\"`\n7. `git remote add origin git@github.com:\u003c\u003cnamespace-name\u003e\u003e/\u003c\u003crepo-name\u003e\u003e.git`\n8. `git push -u origin main`\n9. To monitor the deployment progress, navigate to your github project and select the Actions tab\n\n`stage` is an arbitrary name of your environment (for example **staging**, **production** or **dev-john**)\n\n`region` is the AWS region, where your stack will be deployed to. All the available regions are listed below.\n\n`projectName` is the name of your project. You can create it in the console or interactively using CLI.\n\n\u003cbr /\u003e\n\n| Region name \u0026 Location     | code           |\n  | -------------------------- | -------------- |\n  | Europe (Ireland)           | eu-west-1      |\n  | Europe (London)            | eu-west-2      |\n  | Europe (Frankfurt)         | eu-central-1   |\n  | Europe (Milan)             | eu-south-1     |\n  | Europe (Paris)             | eu-west-3      |\n  | Europe (Stockholm)         | eu-north-1     |\n  | US East (Ohio)             | us-east-2      |\n  | US East (N. Virginia)      | us-east-1      |\n  | US West (N. California)    | us-west-1      |\n  | US West (Oregon)           | us-west-2      |\n  | Canada (Central)           | ca-central-1   |\n  | Africa (Cape Town)         | af-south-1     |\n  | Asia Pacific (Hong Kong)   | ap-east-1      |\n  | Asia Pacific (Mumbai)      | ap-south-1     |\n  | Asia Pacific (Osaka-Local) | ap-northeast-3 |\n  | Asia Pacific (Seoul)       | ap-northeast-2 |\n  | Asia Pacific (Singapore)   | ap-southeast-1 |\n  | Asia Pacific (Sydney)      | ap-southeast-2 |\n  | Asia Pacific (Tokyo)       | ap-northeast-1 |\n  | China (Beijing)            | cn-north-1     |\n  | China (Ningxia)            | cn-northwest-1 |\n  | Middle East (Bahrain)      | me-south-1     |\n  | South America (São Paulo)  | sa-east-1      |\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eDeploy using Gitlab CI pipeline\u003c/summary\u003e\n\n\u003cbr /\u003e\n\n1. If you don't have one, create a new repository at https://gitlab.com/projects/new\n2. Create Gitlab repository secrets: https://docs.stacktape.com/user-guides/ci-cd/#2-create-gitlab-repository-secrets\n3. replace `\u003c\u003cstage\u003e\u003e` and `\u003c\u003cregion\u003e\u003e` in the .gitlab-ci.yml file.\n4. `git init --initial-branch=main`\n5. `git add .`\n6. `git commit -m \"setup stacktape project\"`\n7. `git remote add origin git@gitlab.com:\u003c\u003cnamespace-name\u003e\u003e/\u003c\u003crepo-name\u003e\u003e.git`\n8. `git push -u origin main`\n9. `To monitor the deployment progress, navigate to your gitlab project and select CI/CD-\u003ejobs`\n\n`stage` is an arbitrary name of your environment (for example **staging**, **production** or **dev-john**)\n\n`region` is the AWS region, where your stack will be deployed to. All the available regions are listed below.\n\n`projectName` is the name of your project. You can create it in the console or interactively using CLI.\n\n\u003cbr /\u003e\n\n| Region name \u0026 Location     | code           |\n  | -------------------------- | -------------- |\n  | Europe (Ireland)           | eu-west-1      |\n  | Europe (London)            | eu-west-2      |\n  | Europe (Frankfurt)         | eu-central-1   |\n  | Europe (Milan)             | eu-south-1     |\n  | Europe (Paris)             | eu-west-3      |\n  | Europe (Stockholm)         | eu-north-1     |\n  | US East (Ohio)             | us-east-2      |\n  | US East (N. Virginia)      | us-east-1      |\n  | US West (N. California)    | us-west-1      |\n  | US West (Oregon)           | us-west-2      |\n  | Canada (Central)           | ca-central-1   |\n  | Africa (Cape Town)         | af-south-1     |\n  | Asia Pacific (Hong Kong)   | ap-east-1      |\n  | Asia Pacific (Mumbai)      | ap-south-1     |\n  | Asia Pacific (Osaka-Local) | ap-northeast-3 |\n  | Asia Pacific (Seoul)       | ap-northeast-2 |\n  | Asia Pacific (Singapore)   | ap-southeast-1 |\n  | Asia Pacific (Sydney)      | ap-southeast-2 |\n  | Asia Pacific (Tokyo)       | ap-northeast-1 |\n  | China (Beijing)            | cn-north-1     |\n  | China (Ningxia)            | cn-northwest-1 |\n  | Middle East (Bahrain)      | me-south-1     |\n  | South America (São Paulo)  | sa-east-1      |\n\n\u003c/details\u003e\n\n## 4. Test your application\n\nAfter a successful deployment, some information about the stack will be printed to the terminal (**URLs** of the deployed services, links to **logs**, **metrics**, etc.).\n\n- This project includes a pre-made test script that creates 100 websocket connections and emits a message to all of\n  them. To run it, use\n\n```bash\nstacktape script:run --scriptName broadcastTest --stage \u003c\u003cyour-previously-deployed-stage\u003e\u003e --region \u003c\u003cyour-previously-used-region\u003e\u003e\n```\n\n\n## 5. Run the application in development mode\nTo run a container in the development mode (locally on your machine), you can use the\n[dev command](https://docs.stacktape.com/cli/commands/dev/).\n\n```bash\nstacktape dev --region \u003c\u003cyour-region\u003e\u003e --stage \u003c\u003cstage\u003e\u003e --resourceName websocketServer --container socketio-server\n```\n\nStacktape runs the container as closely to the deployed version as possible:\n\n- Maps all of the container ports specified in the `events` section to the host machine.\n- Injects parameters referenced in the environment variables by `$ResourceParam` and `$Secret` directives to the\n  running container.\n- Injects credentials of the [assumed role](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) to\n  the container. This means that your locally running container will have the exact same IAM permissions as the deployed\n  version.\n- Pretty-prints logs (stdout/stderr) produced by the container to the terminal.\n\n\u003cbr /\u003e\n\nThe container is rebuilt and restarted, when you either:\n\n- type `rs + enter` to the terminal\n- use the `--watch` option and one of your source code files changes\n\n## 6. Hotswap deploys\n- Stacktape deployments use [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) under the hood. It\n  brings a lot of guarantees and convenience, but can be slow for certain use-cases.\n\n- To speed up the deployment, you can use the `--hotSwap` flag which avoids using Cloudformation.\n- Hotswap deployments work only for source code changes (for lambda function, containers and batch jobs) and for content uploads to buckets.\n- If the update deployment is not hot-swappable, Stacktape will automatically fall back to using a Cloudformation deployment.\n```bash\nstacktape deploy --hotSwap --stage \u003c\u003cstage\u003e\u003e --region \u003c\u003cregion\u003e\u003e --projectName \u003c\u003cproject-name\u003e\u003e\n```\n\n## 7. Delete your stack\n\n- If you no longer want to use your stack, you can delete it.\n- Stacktape will automatically delete every infrastructure resource and deployment artifact associated with your stack.\n\n```bash\nstacktape delete --stage \u003c\u003cstage\u003e\u003e --region \u003c\u003cregion\u003e\u003e\n```\n\n# Stack description\n\n  Stacktape uses a simple `stacktape.yml` configuration file to describe infrastructure resources, packaging, deployment\n  pipeline and other aspects of your project.\n\n  You can deploy your project to multiple environments (stages) - for\n  example `production`, `staging` or `dev-john`. A stack is a running instance of an project. It consists of your application\n  code (if any) and the infrastructure resources required to run it.\n\n  The configuration for this project is described below.\n\n  ## 1. Resources\n\n  - Every resource must have an arbitrary, alphanumeric name (A-z0-9).\n  - Stacktape resources consist of multiple underlying AWS or 3rd party resources.\n### 1.1 Application load balancer\n\nThe application load balancer is responsible for maintaining and balancing websocket connections established between\nclients and the containers.\n\nIf there are multiple containers(i.e your workload scales) load balancer distributes connections evenly among these\ncontainers.\n\nYou can configure [more properties](https://docs.stacktape.com/resources/application-load-balancers/) on your load\nbalancer, including using custom domain names or enabling TLS. In this example, we are using the default setup.\n\n```yml\nresources:\n  mainLoadBalancer:\n    type: application-load-balancer\n```\n\n### 1.2 Upstash Redis database\n\nThe application uses Upstash serverless Redis database. It is used by\n[Socket.IO adapter](https://socket.io/docs/v4/redis-adapter/) to synchronize when scaling to multiple Socket.IO\ncontainer instances.\n\nIn this example, we are configuring redis to use `tls`. You can also configure\n[other properties](https://docs.stacktape.com/resources/upstash-redis-databases/) if desired.\n\n```yml\nredis:\n  type: upstash-redis\n  properties:\n    enableTls: true\n```\n\n### 1.3 Container workload\n\nSocket.IO server runs inside a container workload with a single container. The workload is configured as follows:\n\n- [Container](https://docs.stacktape.com/compute-resources/multi-container-workloads/#containers). This container\n  workload uses only a single container: `socketio-server`. The container is configured as follows:\n  - **Packaging** - determines how the Docker container image is built. The easiest and most optimized way to build the\n    image for a Typescript application is using `stacktape-image-buildpack`. We only need to configure `entryfilePath`.\n    Stacktape automatically transpiles and builds the application code with all of its dependencies, builds the Docker\n    image, and pushes it to a pre-created image repository on AWS. You can also use\n    [other types of packaging](https://docs.stacktape.com/configuration/packaging/#packaging-multi-container-workloads).\n  - **ConnectTo list** - we are adding redis database `redis` into `connectTo` list. By doing this, Stacktape will\n    automatically inject relevant environment variables into the compute resource's runtime (such as redis connection\n    url required for connecting to database)\n  - Events that reach the container. Load balancer event is configured to forward all incoming connections with path\n    `/`(used for load balancer healthcheck) or `/websockets*`(used for websocket connection) to the container's port\n    `3000`.\n- [Resources](https://docs.stacktape.com/compute-resources/multi-container-workloads#resources). Resources are shared\n  between containers of container workload (in this case, we only have one container). The cheapest available resource\n  configuration is `0.25` of virtual CPU and `512` MB of RAM.\n- [Scaling](https://docs.stacktape.com/compute-resources/multi-container-workloads#scaling). For the purposes of this\n  tutorial we are scaling the workload to two (parallel) instances, to showcase the \"synchronization\" through redis. I.e\n  that all websocket clients receive messages even if they are connected to different containers.\n\n```yml\nwebsocketServer:\n  type: multi-container-workload\n  properties:\n    resources:\n      cpu: 0.25\n      memory: 512\n    connectTo:\n      - redis\n    containers:\n      - name: socketio-server\n        packaging:\n          type: stacktape-image-buildpack\n          properties:\n            entryfilePath: src/server/index.ts\n        environment:\n          - name: PORT\n            value: 3000\n\n        events:\n          - type: application-load-balancer\n            properties:\n              containerPort: 3000\n              loadBalancerName: mainLoadBalancer\n              priority: 2\n              paths:\n                - \"/\"\n                - \"/websockets*\"\n    scaling:\n      minInstances: 2\n      maxInstances: 2\n```\n\n## 2. Test script\n\nTo simplify testing of the websocket app, the stacktape config also contains `broadcastTest`\n[script](https://docs.stacktape.com/configuration/scripts/).\n\nThe purpose of this script is to create multiple websocket client connections (connections are balanced between the 2\nsocket.io containers):\n\n- One of the clients sends a message.\n- After rest of the websockets receive the message, they gracefully disconnect and script exits.\n\n```yml\nscripts:\n  broadcastTest:\n    executeScript: scripts/broadcast-test.ts\n    environment:\n      - name: LOAD_BALANCER_DOMAIN\n        value: $ResourceParam('loadBalancer', 'domain')\n```\n\nYou can execute the test script after the deploy using\n\n```bash\nstp script:run --scriptName broadcastTet --stage \u003c\u003cpreviously-used-stage\u003e\u003e --region \u003c\u003cpreviously-used-region\u003e\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacktape%2Fstarter-socketio-websocket-api-redis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstacktape%2Fstarter-socketio-websocket-api-redis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstacktape%2Fstarter-socketio-websocket-api-redis/lists"}