SAMA - Simple but Advanced Messaging Alternative - Chat server

Powered by uWebSockets.js

Motivation

The 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).

Read complete medium posts Introducing SAMA and What is SAMA about what is SAMA and what problems we are trying to solve with it:

• https://medium.com/sama-communications/introducing-sama-simple-but-advanced-messaging-alternative-chat-server-524a532e2040
• https://medium.com/sama-communications/what-is-sama-a6d9045fd69a

Frontend app (web + mobile) is available at https://github.com/SAMA-Communications/sama-client

Development

• Make sure you have Node 18.20.x installed.
• Copy .env.example to .env.
• Run docker-compose up to run dependant services (MongoDB, Minio, Redis)
• npm install to install dependencies
• npm run migrate-mongo-up to run DB migrations
• npm run start to run server (in a case of running under Windows - see https://github.com/SAMA-Communications/sama-server/issues/128)

There are also other components. Make sure to check Deploying SAMA chat server stack: a comprehensive guide

Docker one-command deployment

To build and run the SAMA with all dependencies, you can use the following command:

docker-compose -f docker-compose-full.yml up --build

If you only want to run dependency services (for local development without Docker), use this command:

docker-compose up

Run dependency services with SAMA main apps (sama-client, sama-server, sama-push-daemon):

RUN_SAMA=true docker-compose up --build

⚠️ If you are using MacOS or Windows, and want run SAMA apps, add these two variables before the launch command:
MacOS

MINIO_ENDPOINT=$(ipconfig getifaddr en0) MINIO_PORT=9010

Windows

$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;

If 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.

Now you can access apps at the following addresses:

• Server-API
• Web-Client
• Minio-API
• Minio-Client
• Push-dashboard
• Server-dashboard
• Redis-commander

Docker e2e tests

Run migrations:

docker-compose exec sama-server sh -c "MONGODB_URL=mongodb://172.25.0.4/samatests npm run migrate-mongo-up"

Run e2e tests:

docker-compose exec sama-server sh -c "MONGODB_URL=mongodb://172.25.0.4/samatests npm run test"

Public cloud DEMO

The whole SAMA stack can be tested using https://app.samacloud.io public cloud.

API

API reference

Also, there is a set of detailed articles for each API:

• Users API
• Conversations API
• Messages API
• Activities API
• Address Book API
• Push Notifications API

Custom DI container

An example how to create and use provider:

1. Create folder app/providers/services/my_provider with 2 files index.js and Provider.js

2. index.js should contain the implementation of the service itself:

export default class MyProvider {
  constructor(redisConnection, userRepo) {
    this.redisConnection = redisConnection
    this.userRepo = userRepo
  }

  async updateAction(ws, fields) {
    const id = await this.redisConnection.client ...
    const updatedUser = await this.userRepo.update ....
    ....
    return updatedUser
  }
}

1. Provider.js should export an instance of RegisterProvider which contains instructions how to create an instance of index.js class with dependencies:

import RegisterProvider from "@sama/common/RegisterProvider.js"
import MyProvider from "./index.js"

const name = "MyProvider"

class MyProviderRegistration extends RegisterProvider {
  register(slc) {
    const redisConnection = slc.use("RedisClient")
    const userRepo = slc.use("UserRepository")

    return new MyProvider(redisConnection, userRepo)
  }
}

export default new MyProviderRegistration({ name, implementationName: MyProvider.name })

1. Then, add export of Provider.js to app/providers/index.js

import UserRepoProvider from "./repositories/user/Provider.js"
...
...
import MyProviderRegistration from "./services/my_provider/Provider.js"

const providers = [
  UserRepoProvider,

  ...
  ...

  MyProviderRegistration
]

export default providers

1. For any custom APIs providers - use /APIs/[API_NAME]/providers/index.js file:

2. And now yiou can use MyProvider class where needed, e.g. in controller:

import ServiceLocatorContainer from "@sama/common/ServiceLocatorContainer.js"

class Controller {
  async edit(ws, data) {
    const myProvider = ServiceLocatorContainer.use("MyProvider")
    const updatedUser = await myProvider.updateAction(ws, data)
    ....
  }
}

Community and Support

Join our community for support and discussions:
- GitHub Issues - SAMA server, GitHub Issues - SAMA client
- SAMA on Medium
- Get help - Discord 💬

Roadmap

Roadmap

License

GPL-3.0

Help us!

Any thoughts, feedback is welcome! Please create a GitHub issue for any feedback you have.

Want to support us with some coffee?. Will be much appreciated!