From 4acdfdbfc10e9fa79a2bea750d417f2cffe74580 Mon Sep 17 00:00:00 2001 From: Izalia Mae Date: Tue, 20 Dec 2022 08:00:18 -0500 Subject: [PATCH] update docs --- docs/commands.md | 49 ++++++++++-- docs/configuration.md | 177 +++++++++++++++++++++++++----------------- docs/installation.md | 13 ++++ 3 files changed, 161 insertions(+), 78 deletions(-) diff --git a/docs/commands.md b/docs/commands.md index aea0a82..aa4c033 100644 --- a/docs/commands.md +++ b/docs/commands.md @@ -3,9 +3,9 @@ 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. +A config file can be specified by adding `--config [path/to/config.yaml]`. -Note 2: `activityrelay` is only available via pip or pipx if `~/.local/bin` is in `$PATH`. If it +Note: `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 @@ -24,26 +24,35 @@ Run the setup wizard to configure your relay. activityrelay setup +## Convert + +Convert an old `relay.yaml` and `relay.jsonld` to the newer formats. + + activityrelay convert [--old-config relay.yaml] + + ## Config -Manage the relay config +Manage the relay config. activityrelay config ### List -List the current config key/value pairs +List the current config key/value pairs. activityrelay config list ### Set -Set a value for a config option +Set a value for a config option. activityrelay config set +note: The relay must be restarted if setting `log_level`, `workers`, `push_limit`, or `http_timeout` + ## Inbox @@ -92,6 +101,32 @@ not exist anymore, use the `inbox remove` command instead. Note: The relay must be running for this command to work. +## Request + +Manage instance follow requests. + + +### List + +List all instances asking to follow the relay. + + activityrelay request list + + +### Approve + +Allow an instance to join the relay. + + activityrelay request approve + + +### Deny + +Disallow an instance to join the relay. + + activityrelay request deny + + ## Whitelist Manage the whitelisted domains. @@ -120,7 +155,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,7 +167,7 @@ Manage the instance ban list. ### List -List the currently banned instances +List the currently banned instances. activityrelay instance list diff --git a/docs/configuration.md b/docs/configuration.md index d52ca9e..8d843d6 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,14 +2,6 @@ ## General -### 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) @@ -19,46 +11,6 @@ is running on the same host, it is recommended to change `listen` to `localhost` 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 -necessary, but bigger ones (>100 instances) will want to set this to the number of available cpu -threads. - - workers: 0 - - -### JSON GET cache limit - -JSON objects (actors, nodeinfo, etc) will get cached when fetched. This will set the max number of -objects to keep in the cache. - - json_cache: 1024 - - -## AP - -Various ActivityPub-related settings - - ### Host The domain your relay will use to identify itself. @@ -66,40 +18,123 @@ The domain your relay will use to identify itself. host: relay.example.com -### Whitelist Enabled +## Database -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. +### Type - whitelist_enabled: false +The type of SQL database to use. Options: + +* sqlite (default) +* postgresql +* mysql + + type: sqlite -### Whitelist +### Minimum Connections -A list of domains of instances which are allowed to subscribe to your relay. +The minimum number of database connections to keep open (does nothing at the moment) - whitelist: - - bad-instance.example.com - - another-bad-instance.example.com + min_connections: 0 -### Blocked Instances +### Maximum Connections -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. +The maximum number of database connections to open (does nothing at the moment) - blocked_instances: - - bad-instance.example.com - - another-bad-instance.example.com + max_connections: 10 -### Blocked Software +## Sqlite -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 +### Database - blocked_software: - - activityrelay - - aoderelay - - social.seattle.wa.us-relay - - unciarelay +The path to the database file. + + database: relay.sqlite3 + +If the path is relative, it will be relative to the directory the config file is located. For +instance, if the config is located at `/home/izalia/.config/activityrelay/config.yaml`, the +following: + + relay.sqlite3 + +will resolve to: + + /home/izalia/.config/activityrelay/relay.sqlite3 + + +## PostgreSQL + +### Database + +Name of the database to use. + + database: activityrelay + + +### Hostname + +The address to use when connecting to the database. A value of `null` will use the default of +`/var/run/postgresql` + + hostname: null + + +### Port + +The port to use when connecting to the database. A value of `null` will use the default of `5432` + + port: null + + +### Username + +The user to use when connecting to the database. A value of `null` will use the current system +username. + + username: null + + +### Password + +The password for the database user. + + password: null + + +## MySQL + +### Database + +Name of the database to use. + + database: activityrelay + + +### Hostname + +The address to use when connecting to the database. A value of `null` will use the default of +`/var/run/mysqld/mysqld.sock` + + +### Port + +The port to use when connecting to the database. A value of `null` will use the default of `3306` + + port: null + + +### Username + +The user to use when connecting to the database. A value of `null` will use the current system +username. + + username: null + + +### Password + +The password for the database user. + + password: null diff --git a/docs/installation.md b/docs/installation.md index 8363faa..6090c82 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -5,6 +5,19 @@ proxy, and setup the relay to run via a supervisor. Example configs for caddy, n in `installation/` +## Pre-build Executables + +All in one executables can be downloaded from `https://git.pleroma.social/pleroma/relay/-/releases` +under the `Other` section of `Assets`. They don't require any extra setup and can be placed +anywhere. Run the setup wizard + + ./activityrelay setup + +and start it up when done + + ./activityrelay run + + ## Pipx Pipx uses pip and a custom venv implementation to automatically install modules into a Python