Sign inSign up

ortuman/jackal

By ortuman

•Updated over 3 years ago

An XMPP server written in Go.

Image
2

6.9K

ortuman/jackal repository overview

⁠jackal

An XMPP server written in Go.

CI Status Go Report Card Godoc Releases LICENSE Docker Pulls Join the chat at https://gitter.im/jackal-im/jackal

⁠About

jackal is a free, open-source, high performance XMPP server which aims to be known for its stability, simple configuration and low resource consumption.

⁠Features

jackal supports the following features:

  • Customizable
  • Enforced SSL/TLS
  • Stream compression (zlib)
  • Database connectivity for storing offline messages and user settings (PostgreSQL 9.5+, BoltDB)
  • Caching (Redis 6.2+)
  • Clustering capabilities (ectd 3.4+)
  • Expose prometheus⁠ metrics
  • Cross-platform (OS X, Linux)

⁠Installing

⁠Getting Started

To start using jackal, install Go 1.17+ and run the following commands:

$ go get -d github.com/ortuman/jackal
$ cd $GOPATH/src/github.com/ortuman/jackal
$ make install installctl

This will fetch the code and install jackal and jackalctl binaries into your $GOPATH/bin path.

By default the application will try to locate service configuration at config.yaml, but alternatively you can specify a custom configuration path either through command line.

$ jackal --config=/your-custom-path/your-config.yaml

or environment variable:

$ env JACKAL_CONFIG_FILE=/your-custom-path/your-config.yaml jackal
⁠Helm chart

To make it easy to install jackal via Helm in Kubernetes a chart has been included into this repository.

After customizing your own values.yaml⁠ file run the following command to install and configure all required components under jackal namespace.

sh ./helm/scripts/install <your_custom_values>.yaml

In turn, an active chart can be updated by running the upgrade script as follows:

sh ./helm/scripts/upgrade <your_custom_values>.yaml

On the other hand, you can also remove the jackal chart from your Kubernetes cluster by running the uninstall script:

sh ./helm/scripts/uninstall
⁠PostgreSQL database creation

Create a user and a database for that user:

CREATE ROLE jackal WITH LOGIN PASSWORD 'password';
CREATE DATABASE jackal;
GRANT ALL PRIVILEGES ON DATABASE jackal TO jackal;

Download lastest version of the PostgreSQL schema⁠ from jackal Github repository.

wget https://raw.githubusercontent.com/ortuman/jackal/master/sql/postgres.up.psql

Run the postgres script file to create database schema:

psql --user jackal --password -f sql/postgres.up.psql

Configure jackal to use PostgreSQL by editing the configuration file:

storage:
  type: pgsql
  pgsql:
    host: 127.0.0.1:5432
    user: jackal
    password: password
    database: jackal

That's it!

Your database is now ready to connect with jackal.

⁠Creating jackal user

After completing database setup and starting jackal service you'll have to register a new user to be able to login. To do so, you can use jackal command-line tool to create a new user proving name and password.

make installctl && jackalctl user add <user>:<password>

⁠Clustering

The purpose of clustering is to be able to use several servers for fault-tolerance and scalability.

Since jackal is a distributed system, it needs a distributed data store like etcd⁠ to share its state across the entire cluster.

To properly run jackal in clustering mode make sure to add a cluster section configuration in each of your service nodes.

Here's an example of how this section should look like:

cluster:
  etcd:
    endpoints:
      - http://<etcd-host1>:<etcd-port1>
      - http://<etcd-host2>:<etcd-port2>
      ...
  port: your-cluster-node-port # default is 14369

Note the defined port value will be used to perform cluster node communication, so make sure is reachable within your internal network.

⁠Server extensibility

The purpose of the extensibility framework is to provide an interface between jackal server and third-party external modules, thus offering the possibility of extending the functionality of the service for particular use cases. Extensibility gRPC⁠ API proto files can be found at jackal proto definitions repository⁠.

⁠Run jackal in Docker

The Docker deployment framework supports easy installation and configuration of jackal server.

You need to have Docker installed on your system before you can use a jackal Docker image. See Install Docker⁠ for instructions.

Download the jackal Docker image from the official Docker Hub library with this command:

docker pull ortuman/jackal:latest

Start a new jackal Docker container with custom configuration.

docker run --name=jackal \
   --mount type=bind,src=/path-on-host-machine/my-custom-config.yaml,dst=/jackal/config.yaml \
   -d ortuman/jackal:latest
⁠Docker compose

Alternatively, and with the purpose of facilitating service mounting, you can make use of docker-compose as follows:

docker-compose -f dockerfiles/docker-compose.yml up

This command will spin up a jackal server along with its dependencies on a docker network and start listening for incoming connections on port 5222.

Once up and running, don't forget to register one or more users⁠ using jackalctl.

⁠Supported Specifications

⁠Join and Contribute

The jackal developer community⁠ is vital to improving jackal future releases.

Contributions of all kinds are welcome: reporting issues, updating documentation, fixing bugs, improving unit tests, sharing ideas, and any other tips that may help the jackal community.

⁠Code of Conduct

Help us keep jackal open and inclusive. Please read and follow our Code of Conduct⁠.

⁠Licensing

jackal is licensed under the Apache 2 License. See LICENSE⁠ for the full license text.

⁠Contact

If you have any suggestion or question:

Miguel Ángel Ortuño, JID: [email protected]⁠, email: [email protected]⁠

Tag summary

Content type

Image

Digest

sha256:57bf238ef…

Size

53.5 MB

Last updated

over 3 years ago

docker pull ortuman/jackal