From 09e7a8f404fbd30141ac6b6868002f9e72a75ccc Mon Sep 17 00:00:00 2001 From: Izalia Mae Date: Wed, 24 Jan 2024 00:48:15 -0500 Subject: [PATCH] update docs for new commands and config file --- docs/commands.md | 50 +++++++++++++++++----- docs/configuration.md | 97 +++++++++++++++++-------------------------- 2 files changed, 78 insertions(+), 69 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index aea0a82..f56d24c 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -3,11 +3,8 @@ 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. - -Note 2: `activityrelay` is only available via pip or pipx if `~/.local/bin` is in `$PATH`. If it -isn't, use `python3 -m relay` if installed via pip or `~/.local/bin/activityrelay` if installed -via pipx +Note: `activityrelay` is only available via pip or pipx if `~/.local/bin` is in `$PATH`. If not, +use `python3 -m relay` if installed via pip or `~/.local/bin/activityrelay` if installed via pipx. ## Run @@ -24,6 +21,22 @@ Run the setup wizard to configure your relay. activityrelay setup +## Convert + +Convert the old config and jsonld to the new config and SQL backend. If the old config filename is +not specified, the config will get backed up as `relay.backup.yaml` before converting. + + activityrelay convert --old-config relaycfg.yaml + + +## Edit Config + +Open the config file in a text editor. If an editor is not specified with `--editor`, the default +editor will be used. + + activityrelay edit-config --editor micro + + ## Config Manage the relay config @@ -120,7 +133,7 @@ Remove a domain from the whitelist. ### Import -Add all current inboxes to the whitelist +Add all current inboxes to the whitelist. activityrelay whitelist import @@ -132,15 +145,15 @@ Manage the instance ban list. ### List -List the currently banned instances +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. +Add an instance to the ban list. If the instance is currently subscribed, it will be removed from +the inbox list. activityrelay instance ban @@ -152,10 +165,17 @@ Remove an instance from the ban list. activityrelay instance unban +### Update + +Update the ban reason or note for an instance ban. + + activityrelay instance update bad.example.com --reason "the baddest reason" + + ## 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']. +You can find it at `nodeinfo['software']['name']`. ### List @@ -186,4 +206,12 @@ name via nodeinfo. If the name is `RELAYS` (case-sensitive), remove all known relay software names from the list. - activityrelay unban [-f/--fetch-nodeinfo] + activityrelay software unban [-f/--fetch-nodeinfo] + + +### Update + +Update the ban reason or note for a software ban. Either `--reason` and/or `--note` must be +specified. + + activityrelay software update relay.example.com --reason "begone relay" diff --git a/docs/configuration.md b/docs/configuration.md index d52ca9e..bef0799 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,41 +2,23 @@ ## General -### DB +### Domain -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. +Hostname the relay will be hosted on. - db: relay.jsonld + domain: relay.example.com ### 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` +is running on the same host, it is recommended to change `listen` to `localhost` if the reverse +proxy is on the same host. 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. - -Note: If the `workers` option is set to anything above 0, this limit will be per worker. - - push_limit: 512 - - ### Push Workers The relay can be configured to use threads to push messages out. For smaller relays, this isn't @@ -46,60 +28,59 @@ threads. workers: 0 -### JSON GET cache limit +### Database type -JSON objects (actors, nodeinfo, etc) will get cached when fetched. This will set the max number of -objects to keep in the cache. +SQL database backend to use. Valid values are `sqlite` or `postgres`. - json_cache: 1024 + database_type: sqlite -## AP +### Sqlite File Path -Various ActivityPub-related settings +Path to the sqlite database file. If the path is not absolute, it is relative to the config file. +directory. + + sqlite_path: relay.jsonld + + +## Postgresql + +In order to use the Postgresql backend, the user and database need to be created first. + + sudo -u postgres psql -c "CREATE USER activityrelay" + sudo -u postgres psql -c "CREATE DATABASE activityrelay OWNER activityrelay" + + +### Database Name + +Name of the database to use. + + name: activityrelay ### Host -The domain your relay will use to identify itself. +Hostname, IP address, or unix socket the server is hosted on. - host: relay.example.com + host: /var/run/postgresql -### Whitelist Enabled +### Port -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. +Port number the server is listening on. - whitelist_enabled: false + port: 5432 -### Whitelist +### Username -A list of domains of instances which are allowed to subscribe to your relay. +User to use when logging into the server. - whitelist: - - bad-instance.example.com - - another-bad-instance.example.com + user: null -### Blocked Instances +### Password -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. +Password for the specified user. - 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 below list will block all other relays and prevent relay chains - - blocked_software: - - activityrelay - - aoderelay - - social.seattle.wa.us-relay - - unciarelay + pass: null