Create an ActivityPub server
Purpose
ActivityPub is a W3C Recommendation that defines a protocol that provides a client to server API for creating, updating and deleting content, as well as delivering notifications and content.
In this guide you will
- Setup a SemApps-powered ActivityPub server;
- Create an actor;
- Make this actor communicate with another Mastodon actor.
Prerequisites
You need to have NodeJS installed on your computer.
You also need docker and docker-compose installed on your machine.
Setup a new Moleculer project
First install the moleculer-cli tool globally.
Then initialize a new project based on this template with this command:
Choose Yes to all questions:
You can now go to the newly-created directory:
Launch your local Jena Fuseki instance
Jena Fuseki is a semantic triple store. It is where your app's data will be stored.
Jena Fuseki is now available at the URL http://localhost:3030.
Please login - by default, the login is admin and the password is also admin.
Start by creating a new dataset and name it localData (case sensitive). Your data will be stored there.
You should get something like this:
Create a HTTPS tunnel to your localhost
Since we will want to communicate with a Mastodon instance later on this guide, we need to provide a publicly-accessible server, and we need it to handle HTTPS.
Luckily, this can be done easily with the localhost.run service. All you need to do is run the following command:
This will create a publicly-accessible URL like https://alice-d57621c5.localhost.run which will point to port 3000 of your local computer.
note
You could also use a software like Ngrok, but the free version generates a different domain name on every session, which can make federated testing more difficult.
Now, to ensure all the URLs generated by your server will use this domain, edit the SEMAPPS_HOME_URL variable in the .env file at the root of your repository:
caution
Make sure to use the HTTPS URL, and not the HTTP one, it is required by the ActivityPub protocol !
Run Moleculer in dev mode
All the configurations are done, you can launch the server:
Your instance of SemApps is now available at http://localhost:3000, and of course also at https://alice-d57621c5.localhost.run
Create an ActivityPub actor
On the first start, the ActivityPub service will create 3 LDP container in the /activities, /actors and /objects path.
You can create an ActivityPub actor by POSTing to the /actors container with a tool like Insomnia, Postman or the RESTClient add-on for Firefox.
The Slug header allows you to specify the URI of the actor.
In return, you will receive informations about the created actor:
The ActivityPub service (or rather, the ActorService) has appended all the required properties for actors: the outbox, the inbox, the list of followers and following, as well as a publicKey object which will be used to verify messages sent by this actor.
note
If you look inside the /actors subdirectory, you should see two files: alice.key and alice.key.pub. The first one is the private key used to sign messages; it should never leave your server. The second is the public key that we saw just before.
Create a Mastodon user
Mastodon is federated social network to exchange Twitter-like short communications. Unlike Twitter, Mastodon can be installed on many different servers, which use the ActivityPub protocol to communicate with each others. And since ActivityPub is an universal protocol, many different softwares can exchange with Mastodon instances.
This is what we will do now: exchange informations with a Mastodon user. To do that, create an account on any of the instances that you can find on the Mastodon homepage.
For this guide, we will create an user bob on the Framapiaf instance.
Make the two actors follow each others
Send a POST request to Alice's outbox with the following informations.
note
We use https://framapiaf.org/users/bob to identify Bob's account, because that's the standard URL for Mastodon actors. However we could have found this information through the Webfinger protocol.
If you fetch this URL with an Accept: application/json header, you should receive all the informations about Bob.
Follow activities must usually be followed by an Accept activity to confirm that the remote actor has accepted the request. If the magic happened, you should see it on Alice's inbox: https://alice-d57621c5.localhost.run/actors/alice/inbox. Furthermore, Bob should appear here: https://alice-d57621c5.localhost.run/actors/alice/following
If you now go to Bob's Mastodon account, you should see a notification that the user @alice@alice-d57621c5.localhost.run wants to follow him. Click on the icon on the right to follow her back.
Send a Note to your followers
You're almost there ! Since the two users follow each others, you can post a message as Alice, and Bob should receive it on his Mastodon feed.
The message is not sent directly to Bob (otherwise it would appear as a direct message), but to all of Alice's followers. If everything went well, this message should appear right at the top of Bob's Mastodon feed !
note
Mastodon, being a Twitter "clone", only accept two types of objects: Note and Question. Other types of ActivityPub objects are converted but you cannot be sure of the result. For more information, see this page.
Much more could be done, but with this little guide, we hope you had a taste of what it is like to own an ActivityPub server !