Add basic documentation
This commit is contained in:
Izalia Mae
parent
d9e5b9b6d3
commit
1928bb1459
6 changed files with 344 additions and 55 deletions
54
README.md
54
README.md
|
|
@ -10,62 +10,14 @@ Affero General Public License version 3 (AGPLv3) license. You can find a copy o
|
|||
in this package as the `LICENSE` file.
|
||||
|
||||
|
||||
## Setup
|
||||
|
||||
You need at least Python 3.6 (latest version of 3.x recommended) to make use of this software.
|
||||
It simply will not run on older Python versions.
|
||||
|
||||
Download the project and install with pip (`pip3 install -r requirements.txt`).
|
||||
|
||||
Run `python3 -m relay setup` and answer the prompts or copy `relay.yaml.example` to `relay.yaml`
|
||||
and edit it as appropriate:
|
||||
|
||||
$ cp relay.yaml.example relay.yaml
|
||||
$ $EDITOR relay.yaml
|
||||
|
||||
Finally, you can launch the relay:
|
||||
|
||||
$ python3 -m relay run
|
||||
|
||||
It is suggested to run this under some sort of supervisor, such as runit, daemontools,
|
||||
s6 or systemd. Configuration of the supervisor is not covered here, as it is different
|
||||
depending on which system you have available.
|
||||
|
||||
The bot runs a webserver, internally, on localhost at port 8080. This needs to be
|
||||
forwarded by nginx or similar. The webserver is used to receive ActivityPub messages,
|
||||
and needs to be secured with an SSL certificate inside nginx or similar. Configuration
|
||||
of your webserver is not discussed here, but any guide explaining how to configure a
|
||||
modern non-PHP web application should cover it.
|
||||
|
||||
|
||||
## Getting Started
|
||||
|
||||
Normally, you would direct your LitePub instance software to follow the LitePub actor
|
||||
found on the relay. In Pleroma this would be something like:
|
||||
|
||||
$ MIX_ENV=prod mix relay_follow https://your.relay.hostname/actor
|
||||
$ MIX_ENV=prod mix relay_follow https://your.relay.hostname/actor
|
||||
|
||||
|
||||
## Performance
|
||||
## Documentation
|
||||
|
||||
Performance is very good, with all data being stored in memory and serialized to a
|
||||
JSON-LD object graph. Worker coroutines are spawned in the background to distribute
|
||||
the messages in a scatter-gather pattern. Performance is comparable to, if not
|
||||
superior to, the Mastodon relay software, with improved memory efficiency.
|
||||
|
||||
|
||||
## Management
|
||||
|
||||
You can perform a few management tasks such as peering or depeering other relays.
|
||||
|
||||
This will show the available management tasks:
|
||||
|
||||
$ python3 -m relay --help
|
||||
|
||||
When following remote relays, you should use the `/actor` endpoint as you would in
|
||||
Pleroma and other LitePub-compliant software.
|
||||
|
||||
## Docker
|
||||
|
||||
You can run ActivityRelay with docker via the docker management script: `docker.sh`.
|
||||
Run it without arguments to see the list of commands.
|
||||
To install or manage your relay, check the [documentation](https://git.pleroma.social/pleroma/relay/-/blob/master/docs/index.md)
|
||||
|
|
|
|||
157
docs/commands.md
Normal file
157
docs/commands.md
Normal file
|
|
@ -0,0 +1,157 @@
|
|||
# Commands
|
||||
|
||||
There are a number of commands to manage your relay's database and config. You can add `--help` to
|
||||
any category or command to get help on that specific option (ex. `activityrelay inbox --help`).
|
||||
|
||||
Note: Unless specified, it is recommended to run any commands while the relay is shutdown.
|
||||
|
||||
|
||||
## Run
|
||||
|
||||
Run the relay.
|
||||
|
||||
activityrelay run
|
||||
|
||||
|
||||
## Setup
|
||||
|
||||
Run the setup wizard to configure your relay.
|
||||
|
||||
activityrelay setup
|
||||
|
||||
|
||||
## Inbox
|
||||
|
||||
Manage the list of subscribed instances.
|
||||
|
||||
|
||||
### List
|
||||
|
||||
List the currently subscribed instances or relays.
|
||||
|
||||
activityrelay inbox list
|
||||
|
||||
|
||||
### Add
|
||||
|
||||
Add an inbox to the database. If a domain is specified, it will default to `https://{domain}/inbox`.
|
||||
If the added instance is not following the relay, expect errors when pushing messages.
|
||||
|
||||
activityrelay inbox add <inbox or domain>
|
||||
|
||||
|
||||
### Remove
|
||||
|
||||
Remove an inbox from the database. An inbox or domain can be specified.
|
||||
|
||||
activityrelay inbox remove <inbox or domain>
|
||||
|
||||
|
||||
### Follow
|
||||
|
||||
Follow an instance or relay actor and add it to the database. If a domain is specified, it will
|
||||
default to `https://{domain}/actor`.
|
||||
|
||||
activityrelay inbox follow <actor or domain>
|
||||
|
||||
Note: The relay must be running for this command to work.
|
||||
|
||||
|
||||
### Unfollow
|
||||
|
||||
Unfollow an instance or relay actor and remove it from the database. If the instance or relay does
|
||||
not exist anymore, use the `inbox remove` command instead.
|
||||
|
||||
activityrelay inbox unfollow <domain, actor, or inbox>
|
||||
|
||||
Note: The relay must be running for this command to work.
|
||||
|
||||
|
||||
## Whitelist
|
||||
|
||||
Manage the whitelisted domains.
|
||||
|
||||
|
||||
### List
|
||||
|
||||
List the current whitelist.
|
||||
|
||||
activityrelay whitelist list
|
||||
|
||||
|
||||
### Add
|
||||
|
||||
Add a domain to the whitelist.
|
||||
|
||||
activityrelay whitelist add <domain>
|
||||
|
||||
|
||||
### Remove
|
||||
|
||||
Remove a domain from the whitelist.
|
||||
|
||||
activityrelay whitelist remove <domain>
|
||||
|
||||
|
||||
## Instance
|
||||
|
||||
Manage the instance ban list.
|
||||
|
||||
|
||||
### List
|
||||
|
||||
List the currently banned instances
|
||||
|
||||
activityrelay instance list
|
||||
|
||||
|
||||
### Ban
|
||||
|
||||
Add an instance to the ban list. If the instance is currently subscribed, remove it from the
|
||||
database.
|
||||
|
||||
activityrelay instance ban <domain>
|
||||
|
||||
|
||||
### Unban
|
||||
|
||||
Remove an instance from the ban list.
|
||||
|
||||
activityrelay instance unban <domain>
|
||||
|
||||
|
||||
## Software
|
||||
|
||||
Manage the software ban list. To get the correct name, check the software's nodeinfo endpoint.
|
||||
You can find it at nodeinfo\['software']\['name'].
|
||||
|
||||
|
||||
### List
|
||||
|
||||
List the currently banned software.
|
||||
|
||||
activityrelay software list
|
||||
|
||||
|
||||
### Ban
|
||||
|
||||
Add a software name to the ban list.
|
||||
|
||||
If `-f` or `--fetch-nodeinfo` is set, treat the name as a domain and try to fetch the software
|
||||
name via nodeinfo.
|
||||
|
||||
If the name is `RELAYS` (case-sensitive), add all known relay software names to the list.
|
||||
|
||||
activityrelay software ban [-f/--fetch-nodeinfo] <name, domain, or RELAYS>
|
||||
|
||||
|
||||
### Unban
|
||||
|
||||
Remove a software name from the ban list.
|
||||
|
||||
If `-f` or `--fetch-nodeinfo` is set, treat the name as a domain and try to fetch the software
|
||||
name via nodeinfo.
|
||||
|
||||
If the name is `RELAYS` (case-sensitive), remove all known relay software names from the list.
|
||||
|
||||
activityrelay unban [-f/--fetch-nodeinfo] <name, domain, or RELAYS>
|
||||
110
docs/configuration.md
Normal file
110
docs/configuration.md
Normal file
|
|
@ -0,0 +1,110 @@
|
|||
# Configuration
|
||||
|
||||
## DB
|
||||
|
||||
The path to the database. It contains the relay actor private key and all subscribed
|
||||
instances. If the path is not absolute, it is relative to the working directory.
|
||||
|
||||
db: relay.jsonld
|
||||
|
||||
|
||||
## Listener
|
||||
|
||||
The address and port the relay will listen on. If the reverse proxy (nginx, apache, caddy, etc)
|
||||
is running on the same host, it is recommended to change `listen` to `localhost`
|
||||
|
||||
listen: 0.0.0.0
|
||||
port: 8080
|
||||
|
||||
|
||||
## Note
|
||||
|
||||
A small blurb to describe your relay instance. This will show up on the relay's home page.
|
||||
|
||||
note: "Make a note about your instance here."
|
||||
|
||||
|
||||
## Post Limit
|
||||
|
||||
The maximum number of messages to send out at once. For each incoming message, a message will be
|
||||
sent out to every subscribed instance minus the instance which sent the message. This limit
|
||||
is to prevent too many outgoing connections from being made, so adjust if necessary.
|
||||
|
||||
push_limit: 512
|
||||
|
||||
|
||||
## AP
|
||||
|
||||
Various ActivityPub-related settings
|
||||
|
||||
|
||||
### Host
|
||||
|
||||
The domain your relay will use to identify itself.
|
||||
|
||||
host: relay.example.com
|
||||
|
||||
|
||||
### Whitelist Enabled
|
||||
|
||||
If set to `true`, only instances in the whitelist can follow the relay. Any subscribed instances
|
||||
not in the whitelist will be removed from the inbox list on startup.
|
||||
|
||||
whitelist_enabled: false
|
||||
|
||||
|
||||
### Whitelist
|
||||
|
||||
A list of domains of instances which are allowed to subscribe to your relay.
|
||||
|
||||
whitelist:
|
||||
- bad-instance.example.com
|
||||
- another-bad-instance.example.com
|
||||
|
||||
|
||||
### Blocked Instances
|
||||
|
||||
A list of instances which are unable to follow the instance. If a subscribed instance is added to
|
||||
the block list, it will be removed from the inbox list on startup.
|
||||
|
||||
blocked_instances:
|
||||
- bad-instance.example.com
|
||||
- another-bad-instance.example.com
|
||||
|
||||
|
||||
### Blocked Software
|
||||
|
||||
A list of ActivityPub software which cannot follow your relay. This list is empty by default, but
|
||||
setting this to the above list will block all other relays and prevent relay chains
|
||||
|
||||
blocked_software:
|
||||
- activityrelay
|
||||
- aoderelay
|
||||
- social.seattle.wa.us-relay
|
||||
- unciarelay
|
||||
|
||||
|
||||
## Cache
|
||||
|
||||
These are object limits for various caches. Only change if you know what you're doing.
|
||||
|
||||
|
||||
### Objects
|
||||
|
||||
The urls of messages which have been processed by the relay.
|
||||
|
||||
objects: 1024
|
||||
|
||||
|
||||
### Actors
|
||||
|
||||
The ActivityPub actors of incoming messages.
|
||||
|
||||
actors: 1024
|
||||
|
||||
|
||||
### Actors
|
||||
|
||||
The base64 encoded hashes of messages.
|
||||
|
||||
digests: 1024
|
||||
7
docs/index.md
Normal file
7
docs/index.md
Normal file
|
|
@ -0,0 +1,7 @@
|
|||
# ActivityRelay Documentation
|
||||
|
||||
ActivityRelay is a small ActivityPub server that relays messages to subscribed instances.
|
||||
|
||||
[Installation](installation.md)
|
||||
[Configuration](configuration.md)
|
||||
[Commands](commands.md)
|
||||
67
docs/installation.md
Normal file
67
docs/installation.md
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
# Installation
|
||||
|
||||
There are a few ways to install ActivityRelay. Follow one of the methods below, setup a reverse
|
||||
proxy, and setup the relay to run via a supervisor. Example configs for caddy, nginx, and systemd
|
||||
in `installation/`
|
||||
|
||||
|
||||
## Pipx
|
||||
|
||||
Pipx uses pip and a custom venv implementation to automatically install modules into a Python
|
||||
environment and is the recommended method. Install pipx if it isn't installed already. Check out
|
||||
the [official pipx docs](https://pypa.github.io/pipx/installation/) for more in-depth instructions.
|
||||
|
||||
python3 -m pip install pipx
|
||||
|
||||
Now simply install ActivityRelay directly from git
|
||||
|
||||
pipx install git+https://git.pleroma.social/pleroma/relay@0.2.0
|
||||
|
||||
Or from a cloned git repo.
|
||||
|
||||
pipx install .
|
||||
|
||||
Once finished, you can set up the relay via the setup command. It will ask a few questions to fill
|
||||
out config options for your relay
|
||||
|
||||
activityrelay setup
|
||||
|
||||
Finally start it up with the run command.
|
||||
|
||||
activityrelay run
|
||||
|
||||
Note: Pipx requires python 3.7+. If your distro doesn't have a compatible version of python, it can
|
||||
be installed via
|
||||
|
||||
|
||||
## Pip
|
||||
|
||||
The instructions for installation via pip are very similar to pipx. Installation can be done from
|
||||
git
|
||||
|
||||
python3 -m pip install git+https://git.pleroma.social/pleroma/relay@0.2.0
|
||||
|
||||
or a cloned git repo.
|
||||
|
||||
python3 -m pip install .
|
||||
|
||||
Now run the configuration wizard
|
||||
|
||||
activityrelay setup
|
||||
|
||||
And start the relay when finished
|
||||
|
||||
activityrelay run
|
||||
|
||||
|
||||
## Docker
|
||||
|
||||
Installation and management via Docker can be handled with the `docker.sh` script. To install
|
||||
ActivityRelay, run the install command. Once the image is built and the container is created,
|
||||
your will be asked to fill out some config options for your relay.
|
||||
|
||||
./docker.sh install
|
||||
|
||||
Finally start it up. It will be listening on TCP port 8080.
|
||||
|
||||
./docker.sh start
|
||||
|
|
@ -91,10 +91,6 @@ def cli_inbox_add(inbox):
|
|||
click.echo(f'Error: Inbox already in database: {inbox}')
|
||||
return
|
||||
|
||||
if database.get_inbox(inbox):
|
||||
click.echo(f'Error: Already added inbox: {inbox}')
|
||||
return
|
||||
|
||||
if config.is_banned(inbox):
|
||||
click.echo(f'Error: Refusing to add banned inbox: {inbox}')
|
||||
return
|
||||
|
|
|
|||
Loading…
Reference in a new issue