{"id":15147039,"url":"https://github.com/sama-communications/sama-server","last_synced_at":"2025-04-05T14:08:10.116Z","repository":{"id":142924392,"uuid":"538482828","full_name":"SAMA-Communications/sama-server","owner":"SAMA-Communications","description":"SAMA - Simple but Advanced Messaging Alternative chat server, powered by uWebsockets.js","archived":false,"fork":false,"pushed_at":"2024-12-10T14:40:30.000Z","size":1363,"stargazers_count":113,"open_issues_count":5,"forks_count":9,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-10T22:31:05.352Z","etag":null,"topics":["chat","chat-application","chat-server","chatserver","nodejs","websocket","xmpp","xmpp-server"],"latest_commit_sha":null,"homepage":"https://samacloud.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SAMA-Communications.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":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-19T12:07:22.000Z","updated_at":"2024-12-02T09:40:55.000Z","dependencies_parsed_at":"2024-03-21T17:28:17.037Z","dependency_job_id":"a35d94c4-c61c-4022-84ab-ce38ecb0db5f","html_url":"https://github.com/SAMA-Communications/sama-server","commit_stats":{"total_commits":276,"total_committers":9,"mean_commits":"30.666666666666668","dds":0.6086956521739131,"last_synced_commit":"26d3eb76ec1da72b6cdabc8a78892dba2fe547c8"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAMA-Communications%2Fsama-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAMA-Communications%2Fsama-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAMA-Communications%2Fsama-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SAMA-Communications%2Fsama-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SAMA-Communications","download_url":"https://codeload.github.com/SAMA-Communications/sama-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247345854,"owners_count":20924102,"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":["chat","chat-application","chat-server","chatserver","nodejs","websocket","xmpp","xmpp-server"],"created_at":"2024-09-26T12:21:35.530Z","updated_at":"2025-04-05T14:08:10.011Z","avatar_url":"https://github.com/SAMA-Communications.png","language":"JavaScript","funding_links":["https://www.buymeacoffee.com/khomenkoigor"],"categories":[],"sub_categories":[],"readme":"# SAMA - Simple but Advanced Messaging Alternative - Chat server\n\n\n#### Powered by [`uWebSockets.js`](https://github.com/uNetworking/uWebSockets.js/)\n\n\u003cdiv align=\"left\"\u003e\n  \n[![Last commit](https://img.shields.io/github/last-commit/SAMA-Communications/sama-server)](https://github.com/SAMA-Communications/sama-server/commits/main)\n[![GitHub issues](https://img.shields.io/github/issues/SAMA-Communications/sama-server)](https://github.com/SAMA-Communications/sama-server/issues)\n[![GitHub stars](https://img.shields.io/github/stars/SAMA-Communications/sama-server)](https://github.com/SAMA-Communications/sama-server/stargazers)\n[![GitHub license](https://img.shields.io/github/license/SAMA-Communications/sama-server)](https://github.com/SAMA-Communications/sama-server/blob/master/LICENSE)\n![GitHub language count](https://img.shields.io/github/languages/count/SAMA-Communications/sama-server) \n![GitHub top language](https://img.shields.io/github/languages/top/SAMA-Communications/sama-server)\n\n![NodeJS](https://img.shields.io/badge/Node.js-43853D?style=for-the-badge\u0026logo=node.js\u0026logoColor=white)\n![MongoDB](https://img.shields.io/badge/MongoDB-4EA94B?style=for-the-badge\u0026logo=mongodb\u0026logoColor=white)\n![Redis](https://img.shields.io/badge/redis-%23DD0031.svg?\u0026style=for-the-badge\u0026logo=redis\u0026logoColor=white)\n![AWS](https://img.shields.io/badge/Amazon_AWS-232F3E?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)\n\n\u003c/div\u003e\n\n\u003cimg width=\"597\" alt=\"Screenshot 2022-12-31 at 14 15 04\" src=\"https://user-images.githubusercontent.com/70977170/210136404-b1811eaa-b058-4fd4-a7db-14b8d059a118.png\"\u003e\n\n## Motivation\n\nThe intention of our messaging protocol and chat server, which are different from others, is to provide an alternative solution to the wide spread XMPP messaging protocol (and to be honest — the only wide spread ‘standard’ these days).\n\nRead complete medium posts **Introducing SAMA** and **What is SAMA** about what is SAMA and what problems we are trying to solve with it:\n\n- https://medium.com/sama-communications/introducing-sama-simple-but-advanced-messaging-alternative-chat-server-524a532e2040\n- https://medium.com/sama-communications/what-is-sama-a6d9045fd69a\n\n\nClients:\n- Frontend Web app https://github.com/SAMA-Communications/sama-client\n- Flutter app https://github.com/SAMA-Communications/sama-client-flutter\n\n## Local development\n\n- Make sure you have latest `Node 18` installed.\n- Copy `.env.example` to `.env`.\n- Run `docker-compose -f docker-compose.yml -f docker-compose.development.yml up` to run dependant services (MongoDB, Minio, Redis)\n- `npm install` to install dependencies\n- `npm run migrate-mongo-up` to run DB migrations\n- `npm run start` to run server (in a case of running under Windows - see https://github.com/SAMA-Communications/sama-server/issues/128)\n- Now the server will be listening for incoming connections at `ws://localhost:9001`\n\nThere are also other components available in SAMA stack - check it out [Deploying SAMA chat server stack: a comprehensive guide](https://medium.com/sama-communications/deploying-sama-chat-server-stack-a-comprehensive-guide-294ddb9a2d78)\n\n\n## Deployment\n\nDeploying the SAMA application can be done easily with Docker, whether you want a complete setup with all dependencies or a local environment with the main applications. Below are the steps to follow:\n\n### Docker one-command deployment\n\nThis approach builds and runs the entire SAMA application, including all dependencies, in a single command. It is ideal for setting up the full environment quickly.\n\nTo deploy using this method, run:\n\n```\ndocker-compose -f docker-compose-full.yml up --build\n```\n\n### Docker local deployment\n\nTo run the dependency services along with the main `SAMA` applications (`sama-client`, `sama-server`, and `sama-push-daemon`), use:\n\n```\ndocker-compose up --build\n```\n\n:warning: If you are using MacOS or Windows, and want run `SAMA` apps, add these two variables before the launch command:\n\nMacOS\n\n```\nMINIO_ENDPOINT=$(ipconfig getifaddr en0) MINIO_PORT=9010\n```\n\nWindows\n\n```\n$env:MINIO_ENDPOINT = (Get-NetIPAddress | Where-Object { $_.AddressFamily -eq 'IPv4' -and $_.IPAddress -match '^192\\.168\\.|^10\\.|^172\\.(1[6-9]|2[0-9]|3[0-1])\\.' } | Select-Object -ExpandProperty IPAddress)[1]; $env:MINIO_PORT = 9010;\n```\n\nIf you are encountering issues with attachments in the web client, it suggests that an error occurred in the first variable. To resolve this, you can simply update the code segment with the private IP address of your machine.\n\nNow you can access apps at the following addresses:\n\n- [Server-API](http://localhost:9000)\n- [Web-Client](http://localhost:10000)\n- [Minio-API](http://localhost:9010)\n- [Minio-Client](http://localhost:9011)\n- [Push-dashboard](http://localhost:3001/ui)\n- [Server-dashboard](http://localhost:9002)\n- [Redis-commander](http://localhost:8081)\n\n### Docker e2e tests\n\nRun migrations:\n\n```\ndocker-compose exec sama-server sh -c \"MONGODB_URL=mongodb://172.25.0.4/samatests npm run migrate-mongo-up\"\n```\n\nRun e2e tests:\n\n```\ndocker-compose exec sama-server sh -c \"MONGODB_URL=mongodb://172.25.0.4/samatests npm run test\"\n```\n\n## Public cloud DEMO\n\nThe whole SAMA stack can be tested using https://app.samacloud.io public cloud.\n\n## API\n\n[API reference](docs/API.md)\n\nAlso, there is a set of detailed articles for each API:\n\n- [Users API](https://medium.com/sama-communications/sama-chat-server-api-users-edf65ea6a341)\n- [Conversations API](https://medium.com/sama-communications/sama-chat-server-api-conversations-1ae505b07d17)\n- [Messages API](https://medium.com/sama-communications/sama-chat-server-api-messages-dc00e9684dc0)\n- [Activities API](https://medium.com/sama-communications/sama-chat-server-api-activities-97b712b88671)\n- [Address Book API](https://medium.com/sama-communications/sama-chat-server-api-address-book-f297ce25faa1)\n- [Push Notifications API](https://medium.com/sama-communications/sama-chat-server-api-push-notifications-7e904eb04a0c)\n\n## Custom DI container\n\nAn example how to create and use provider:\n\n1. Create folder `app/providers/services/my_provider` with 2 files `index.js` and `Provider.js`\n\n2. `index.js` should contain the implementation of the service itself:\n\n```js\nexport default class MyProvider {\n  constructor(redisConnection, userRepo) {\n    this.redisConnection = redisConnection\n    this.userRepo = userRepo\n  }\n\n  async updateAction(ws, fields) {\n    const id = await this.redisConnection.client ...\n    const updatedUser = await this.userRepo.update ....\n    ....\n    return updatedUser\n  }\n}\n```\n\n3. `Provider.js` should export an instance of RegisterProvider which contains instructions how to create an instance of `index.js` class with dependencies:\n\n```js\nimport RegisterProvider from \"@sama/common/RegisterProvider.js\"\nimport MyProvider from \"./index.js\"\n\nconst name = \"MyProvider\"\n\nclass MyProviderRegistration extends RegisterProvider {\n  register(slc) {\n    const redisConnection = slc.use(\"RedisClient\")\n    const userRepo = slc.use(\"UserRepository\")\n\n    return new MyProvider(redisConnection, userRepo)\n  }\n}\n\nexport default new MyProviderRegistration({ name, implementationName: MyProvider.name })\n```\n\n4. Then, add export of `Provider.js` to `app/providers/index.js`\n\n```js\nimport UserRepoProvider from \"./repositories/user/Provider.js\"\n...\n...\nimport MyProviderRegistration from \"./services/my_provider/Provider.js\"\n\nconst providers = [\n  UserRepoProvider,\n\n  ...\n  ...\n\n  MyProviderRegistration\n]\n\nexport default providers\n```\n\n5. For any custom APIs providers - use `/APIs/[API_NAME]/providers/index.js` file:\n\n6. And now yiou can use `MyProvider` class where needed, e.g. in controller:\n\n```js\nimport ServiceLocatorContainer from \"@sama/common/ServiceLocatorContainer.js\"\n\nclass Controller {\n  async edit(ws, data) {\n    const myProvider = ServiceLocatorContainer.use(\"MyProvider\")\n    const updatedUser = await myProvider.updateAction(ws, data)\n    ....\n  }\n}\n```\n\n## Community and Support\n\nJoin our community for support and discussions:\n- [GitHub Issues - SAMA server](https://github.com/SAMA-Communications/sama-server/issues), [GitHub Issues - SAMA client](https://github.com/SAMA-Communications/sama-client/issues), [GitHub Issues - SAMA Flutter client](https://github.com/SAMA-Communications/sama-client-flutter/issues)\n- [SAMA on Medium](https://medium.com/sama-communications)\n- Get help - [Discord 💬](https://discord.gg/bHSm9a7DpC)\n\n## Roadmap\n\n[Roadmap](docs/ROADMAP.md)\n\n## License\n\n[GPL-3.0](LICENSE)\n\n## Help us!\n\nAny thoughts, feedback is welcome! Please create a GitHub issue for any feedback you have.\n\nWant to support us?\n\n\u003ca href=\"https://www.buymeacoffee.com/khomenkoigor\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-blue.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsama-communications%2Fsama-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsama-communications%2Fsama-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsama-communications%2Fsama-server/lists"}