update readme
This commit is contained in:
Will Murphy
parent
8d3c5d2b13
commit
958951aa4b
1 changed files with 7 additions and 99 deletions
106
README.md
106
README.md
|
|
@ -1,109 +1,17 @@
|
|||
# Express ActivityPub Server
|
||||
# Gup.pe
|
||||
|
||||
A very simple standalone ActivityPub server that supports:
|
||||
Social groups for the fediverse - making it easy to connect and meet new people based on shared interests without the maniuplation of your attention to maximize ad revenue nor the walled garden lock-in of capitalist social media.
|
||||
|
||||
* creation of new Actors via API
|
||||
* discovery of our Actors via webfinger (so you can find these accounts from other instances)
|
||||
* notifying followers of new posts (so new posts show up in their timeline)
|
||||
This server-2-server ActivityPub implementation adds decentralized, federaded "groups" support across all ActivityPub compliant social media networks. Users join groups by following group-type actors on Guppe servers and contribute to groups by mentioning those same actors in a post. Guppe group actors will automatically forward posts they receive to all group members so that everyone in the group sees any post made to the group. Guppe group actors' profiles (e.g. outboxes) also serve as a group discussion history.
|
||||
|
||||
_This is meant as a reference implementation!_ This code implements a very small subset of ActivityPub and is supposed to help you get your bearings when it comes to making your own barebones ActivityPub support in your own projects. (Of course you can still fork this and start building on it as well, but it's not exactly hardened production code.)
|
||||
## Tech stack
|
||||
|
||||
Example use case: I own tinysubversions.com. I can have this server run on bots.tinysubversions.com. All of my bots are stored and published and discoverable there. If I want to create a new bot, I go to bots.tinysubversions.com/admin and enter an account name, enter my admin user/pass on prompt, and it creates an account record and it gives me back an API key. I then make POST calls to the API passing the API key in a header and it publishes those things to followers.
|
||||
|
||||
## Requirements
|
||||
|
||||
This requires Node.js v10.10.0 or above.
|
||||
Node.js, ExpressJS, MongoDB
|
||||
|
||||
## Installation
|
||||
|
||||
Clone the repository, then `cd` into its root directory. Install dependencies:
|
||||
|
||||
`npm i`
|
||||
|
||||
Copy `config-template.json` to `config.json`.
|
||||
|
||||
`cp config-template.json config.json`
|
||||
|
||||
Update your `config.json` file:
|
||||
|
||||
```js
|
||||
{
|
||||
"USER": "pickAUsername",
|
||||
"PASS": "pickAPassword",
|
||||
"DOMAIN": "mydomain.com", // your domain! this should be a discoverable domain of some kind like "example.com"
|
||||
"PORT": "3000", // the port that Express runs on
|
||||
"PRIVKEY_PATH": "/path/to/your/ssl/privkey.pem", // point this to your private key you got from Certbot or similar
|
||||
"CERT_PATH": "/path/to/your/ssl/cert.pem" // point this to your cert you got from Certbot or similar
|
||||
}
|
||||
```
|
||||
|
||||
Run the server!
|
||||
|
||||
`node index.js`
|
||||
|
||||
Go to the admin page and create an account:
|
||||
|
||||
`http://yourdomain.com/admin`
|
||||
|
||||
Enter "test" in the "Create Account" section and hit the "Create Account" button. It will prompt you for the user/pass you just set in your config file, and then you should get a message with some verification instructions, pointing you to some URLs that should be serving some ActivityPub JSON now.
|
||||
|
||||
## Local testing
|
||||
|
||||
You can use a service like [ngrok](https://ngrok.com/) to test things out before you deploy on a real server. All you need to do is install ngrok and run `ngrok http 3000` (or whatever port you're using if you changed it). Then go to your `config.json` and update the `DOMAIN` field to whatever `abcdef.ngrok.io` domain that ngrok gives you and restart your server. *For local testing you do not need to specify `PRIVKEY_PATH` or `CERT_PARTH`.*
|
||||
|
||||
## Admin Page
|
||||
|
||||
For your convenience, if you go to the `/admin` endpoint in a browser, you will see an admin page. Don't worry, nothing is possible here unless either your admin user/pass (for creating accounts) or a valid API key (for sending messages as an account). This page provides a simple web form for both creating accounts and sending messages to followers.
|
||||
|
||||
## API
|
||||
|
||||
### Create Account
|
||||
|
||||
Create a new account. This is a new ActivityPub Actor, along with its webfinger record. This creates a new row in the `accounts` table in the database.
|
||||
|
||||
Send a POST to `/api/admin/create` using basic HTTP auth with the admin username/password. The form body needs an "account" field. An example CURL request:
|
||||
|
||||
```
|
||||
curl -u adminUsername:adminPassword -d "account=test" -H "Content-Type: application/x-www-form-urlencoded" -X POST http://example.com/api/admin/create
|
||||
```
|
||||
|
||||
This will return a 200 status and `{msg: "ok", apikey: "yourapikey"}` if all goes well.
|
||||
|
||||
### Send Message to Followers
|
||||
|
||||
Send a message to followers. This is NOT a direct message or an @-mention. This simply means that the message you post via this endpoint will appear in the timelines (AKA inboxes) of every one of the account's followers.
|
||||
|
||||
Send a POST to `api/sendMessage` with the form fields `acct`, `apikey`, and `message`.
|
||||
|
||||
* `acct`: the account name in the form "myAccountName" (no domain or @'s needed)
|
||||
* `apikey`: your hex API key
|
||||
* `message`: the message you want to send -- for Mastodon-compatible posts this might be plain text or simple HTML, but ActivityPub is a lot more flexible than just Mastodon! In theory, according to the [ActivityPub spec](https://www.w3.org/TR/activitypub/#create-activity-outbox) it can be any [ActivityStreams object](https://www.w3.org/TR/activitystreams-core/#object)
|
||||
|
||||
## Database
|
||||
|
||||
This server uses a SQLite database to keep track of all the data. There is one table in the database: `accounts`.
|
||||
|
||||
### `accounts`
|
||||
|
||||
This table keeps track of all the data needed for the accounts. Columns:
|
||||
|
||||
* `name` `TEXT PRIMARY KEY`: the account name, in the form `thename@example.com`
|
||||
* `privkey` `TEXT`: the RSA private key for the account
|
||||
* `pubkey` `TEXT`: the RSA public key for the account
|
||||
* `webfinger` `TEXT`: the entire contents of the webfinger JSON served for this account
|
||||
* `actor` `TEXT`: the entire contents of the actor JSON served for this account
|
||||
* `apikey` `TEXT`: the API key associated with this account
|
||||
* `followers` `TEXT`: a JSON-formatted array of the URL for the Actor JSON of all followers, in the form `["https://remote.server/users/somePerson", "https://another.remote.server/ourUsers/anotherPerson"]`
|
||||
* `messages` `TEXT`: not yet used but will eventually store all messages so we can render them on a "profile" page
|
||||
|
||||
### `messages`
|
||||
|
||||
This table holds all messages sent by the server, which are served at the url `/m/some-id-number/`.
|
||||
|
||||
* `guid` `TEXT PRIMARY KEY`: an id for the message
|
||||
* `message` `TEXT`: a JSON object encoding the full message
|
||||
Instructions coming soon.
|
||||
|
||||
## License
|
||||
|
||||
Copyright (c) 2018 Darius Kazemi. Licensed under the MIT license.
|
||||
|
||||
Copyright (c) 2019 William Murphy. Licensed under the AGPL-3
|
||||
|
|
|
|||
Loading…
Reference in a new issue