Spinning up a 3Box Ghost Pinbot server 👻
Boost your 3Box Ghost Threads messaging
Introduction
We’ve described the 3Box Ghost Threads API and its benefits in the previous blogpost Introducing 3Box Ghost Threads API. In order to provide you with better experience for using the Ghost Threads API we created a Ghost Pinbot service. This service lets you specify the one or more threads whose messages will be pinned, and in that way help you overcome the common issues in the decentralised realm of messaging such as peer discovery, the initial state sync time and others.
By serving as an equal thread participant the Ghost Pinbot server preserves previous messaging history and list of participants in the thread. Its purpose is to serve as a bootstrap peer and decrease the participants time for joining the thread and loading the most relevant thread state.
It should be noted that the thread state in the Ghost Pinbot is not persistent and will reside in the servers memory only. This is not an issue here since the whole purpose of Ghost Threads API is to provide a performant, in-memory, decentralised messaging. If persistence is crucial for the application you’re building you can find more information about persistent threads here.
Motivation
Decentralised architectures come with huge benefits opposed to the centralised ones in many cases. One of the most common cases is decentralised messaging. The benefits against the centralised solutions are the following:
- Censorship resistent
- More stable, more flexible, and safer
- No single point of failure.
There are some cons as well. The most significant one is the efficiency. Upon joining the chatroom the peer has to find other peers, exchange information about previous messages, etc. This really depends on the algorithms and data structures used for implementing the solution, but one fact is for certain — joining the chatroom can last.
That’s why we’ve provided the Ghost Pinbot. Once it’s deployed, it can listen to as many threads as you want and keep their state in sync. It can serve as a bootstrap node and provide the joining peer with the most recent state of the thread.
Deployment
The 3Box Ghost Pinbot Server provides a couple of templates to ease up the deployment on different providers. The server can be deployed in different modes as well:
APIservice for communicating with the Ghost Pinbot APIPEERservice for handling Ghost Thread functionalitiesBUNDLEDservice which bundles both theAPIandPEERservices.
The service itself does not imply any specific requirements. The following set of instructions describe how to deploy the Ghost Pinbot server on Heroku environment — easy and for free!
Instructions
The pre-requirements needed for this particular deployment are:
Deploying Ghost Pinbot on Heroku is easy. There are a couple of limitations though:
- One listening port per application
- Unique application names.
The following steps will deploy the Ghost Pinbot as a set of two services: API and PEER.
Note: please make sure that the API_APP_NAME and PEER_APP_NAME variables in the script are unique.
# Login to Heroku
$ heroku login
# Clone the 3box-ghostpinbot repo
$ git clone https://github.com/3box/3box-ghostpinbot.git
$ cd 3box-ghostpinbot
# Run the command to generate the deployment script
$ ./deploy/heroku/build.sh <API_APP_NAME> <PEER_APP_NAME>
# Run the script
$ ./deploy/heroku/build/deploy.shThe services should be deployed now. For example, if you ran:
$ ./deploy/heroku/build.sh ghostpinbot-api ghostpinbot-peerthe deployed services should be available at:
The PEER service registers on the API service upon bootstrap. You can query the API service in order to get the multiaddress of the peer node:
GET PEER INFO: https://ghostpinbot-api.herokuapp.com/api/v0/peer
The multiaddress will be listed in the response. This multiaddress can be used as a bootstrap address for future participants. You can swarm connect to it from your IPFS instance or just pass it as an option ghostPinbot while creating a 3Box instance.
Box.create(provider, { ghostPinbot: multiaddress }) That’s it! For more information about the Ghost Pinbot and available API(s) please visit 3box-ghostpinbot repository.
Want to learn more?
We’re always available on Discord to help answer your questions. Drop by if you have questions or if you need help integrating. Join us!
