diff --git a/README.md b/README.md index cbe4b90..233c5cd 100644 --- a/README.md +++ b/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) diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..a92e784 --- /dev/null +++ b/docs/commands.md @@ -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 + + +### Remove + +Remove an inbox from the database. An inbox or domain can be specified. + + activityrelay inbox remove + + +### 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 + +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 + +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 + + +### Remove + +Remove a domain from the whitelist. + + activityrelay whitelist remove + + +## 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 + + +### Unban + +Remove an instance from the ban list. + + activityrelay instance unban + + +## 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] + + +### 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] diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..b76b931 --- /dev/null +++ b/docs/configuration.md @@ -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 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..43882ca --- /dev/null +++ b/docs/index.md @@ -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) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..7445f58 --- /dev/null +++ b/docs/installation.md @@ -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 diff --git a/relay/manage.py b/relay/manage.py index 336be3c..3765ff5 100644 --- a/relay/manage.py +++ b/relay/manage.py @@ -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