mirror of https://github.com/kitsune-soc/kitsune
Use `oranda` for our website (#425)
* init oranda structure * switch to non-workspace mode * generate changelogs from github releases * port docs to mdbook * fix opentelemetry docs * add clacks overhead docs * fix oidc config * add other repository
This commit is contained in:
aumetra
GitHub
parent
3c78e75905
commit
c97209214c
|
|
@ -0,0 +1,99 @@
|
|||
# Workflow to build your docs with oranda (and mdbook)
|
||||
# and deploy them to Github Pages
|
||||
name: Web
|
||||
|
||||
# We're going to push to the gh-pages branch, so we need that permission
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
# What situations do we want to build docs in?
|
||||
# All of these work independently and can be removed / commented out
|
||||
# if you don't want oranda/mdbook running in that situation
|
||||
on:
|
||||
# Check that a PR didn't break docs!
|
||||
#
|
||||
# Note that the "Deploy to Github Pages" step won't run in this mode,
|
||||
# so this won't have any side-effects. But it will tell you if a PR
|
||||
# completely broke oranda/mdbook. Sadly we don't provide previews (yet)!
|
||||
pull_request:
|
||||
|
||||
# Whenever something gets pushed to main, update the docs!
|
||||
# This is great for getting docs changes live without cutting a full release.
|
||||
#
|
||||
# Note that if you're using cargo-dist, this will "race" the Release workflow
|
||||
# that actually builds the Github Release that oranda tries to read (and
|
||||
# this will almost certainly complete first). As a result you will publish
|
||||
# docs for the latest commit but the oranda landing page won't know about
|
||||
# the latest release. The workflow_run trigger below will properly wait for
|
||||
# cargo-dist, and so this half-published state will only last for ~10 minutes.
|
||||
#
|
||||
# If you only want docs to update with releases, disable this, or change it to
|
||||
# a "release" branch. You can, of course, also manually trigger a workflow run
|
||||
# when you want the docs to update.
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
# Whenever a workflow called "Release" completes, update the docs!
|
||||
#
|
||||
# If you're using cargo-dist, this is recommended, as it will ensure that
|
||||
# oranda always sees the latest release right when it's available. Note
|
||||
# however that Github's UI is wonky when you use workflow_run, and won't
|
||||
# show this workflow as part of any commit. You have to go to the "actions"
|
||||
# tab for your repo to see this one running (the gh-pages deploy will also
|
||||
# only show up there).
|
||||
workflow_run:
|
||||
workflows: [ "Release" ]
|
||||
types:
|
||||
- completed
|
||||
|
||||
# Alright, let's do it!
|
||||
jobs:
|
||||
web:
|
||||
name: Build and deploy site and docs
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
# Setup
|
||||
- uses: actions/checkout@v3
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
- uses: swatinem/rust-cache@v2
|
||||
|
||||
# If you use any mdbook plugins, here's the place to install them!
|
||||
|
||||
# Install and run oranda (and mdbook)
|
||||
# This will write all output to ./public/ (including copying mdbook's output to there)
|
||||
- name: Install and run oranda
|
||||
run: |
|
||||
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/oranda/releases/latest/download/oranda-installer.sh | sh
|
||||
oranda build
|
||||
|
||||
- name: Prepare HTML for link checking
|
||||
# untitaker/hyperlink supports no site prefixes, move entire site into
|
||||
# a subfolder
|
||||
run: mkdir /tmp/public/ && cp -R public /tmp/public/oranda
|
||||
|
||||
- name: Check HTML for broken internal links
|
||||
uses: untitaker/hyperlink@0.1.29
|
||||
with:
|
||||
args: /tmp/public/
|
||||
|
||||
# Deploy to our gh-pages branch (creating it if it doesn't exist)
|
||||
# the "public" dir that oranda made above will become the root dir
|
||||
# of this branch.
|
||||
#
|
||||
# Note that once the gh-pages branch exists, you must
|
||||
# go into repo's settings > pages and set "deploy from branch: gh-pages"
|
||||
# the other defaults work fine.
|
||||
- name: Deploy to Github Pages
|
||||
uses: JamesIves/github-pages-deploy-action@v4.4.1
|
||||
# ONLY if we're on main (so no PRs or feature branches allowed!)
|
||||
if: ${{ github.ref == 'refs/heads/main' }}
|
||||
with:
|
||||
repository-name: "kitsune-soc/kitsune-soc.github.io"
|
||||
branch: gh-pages
|
||||
# Gotta tell the action where to find oranda's output
|
||||
folder: public
|
||||
token: ${{ secrets.GITHUB_TOKEN }}
|
||||
single-commit: true
|
||||
|
|
@ -1,3 +1,7 @@
|
|||
# Documentation builds
|
||||
/dist
|
||||
/docs/book
|
||||
|
||||
# Rust target directories
|
||||
target
|
||||
target-analyzer
|
||||
|
|
|
|||
|
|
@ -1,7 +1,11 @@
|
|||
<div align="center">
|
||||
|
||||
<div class="oranda-hide">
|
||||
|
||||
# kitsune
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
[](https://deps.rs/repo/github/kitsune-soc/kitsune)
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,6 @@
|
|||
[book]
|
||||
authors = ["aumetra"]
|
||||
language = "en"
|
||||
multilingual = false
|
||||
src = "src"
|
||||
title = "Kitsune documentation"
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
# Summary
|
||||
|
||||
- [Introduction](./introduction.md)
|
||||
- [Running]()
|
||||
- [Installation](./running/installation.md)
|
||||
- [Basic configuration](./running/basic-configuration.md)
|
||||
- [Configuring]()
|
||||
- [Cache](./configuring/cache.md)
|
||||
- [Captcha](./configuring/captcha.md)
|
||||
- [Clacks Overhead](./configuring/clacks-overhead.md)
|
||||
- [Database](./configuring/database.md)
|
||||
- [Emailing](./configuring/email.md)
|
||||
- [Federation filter](./configuring/federation-filter.md)
|
||||
- [Instance](./configuring/instance.md)
|
||||
- [Job Scheduler](./configuring/job-scheduler.md)
|
||||
- [Link embedding](./configuring/link-embedding.md)
|
||||
- [Messaging](./configuring/messaging.md)
|
||||
- [OIDC (OpenID Connect)](./configuring/oidc.md)
|
||||
- [OpenTelemetry](./configuring/opentelemetry.md)
|
||||
- [Search](./configuring/search.md)
|
||||
- [Storage](./configuring/storage.md)
|
||||
- [Specification]()
|
||||
- [HTTP signatures](./spec/http-signatures.md)
|
||||
- [Webfinger](./spec/webfinger.md)
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
# Cache
|
||||
|
||||
Computing things from scratch can be pretty expensive, that's where caching comes in.
|
||||
To best fit for your specific setup, Kitsune has multiple caching backends:
|
||||
|
||||
## No Cache
|
||||
|
||||
```toml
|
||||
[cache]
|
||||
type = "none"
|
||||
```
|
||||
|
||||
This is the simplest of all caching modes. It just doesn't cache anything at all and utilises Kitsune's no-op cache.
|
||||
Pretty much only desirable if you are debugging other caches for invalidation issues (or if you have *heavy* memory constraints and no way to get your hands on a Redis instance).
|
||||
|
||||
## In-Memory Cache
|
||||
|
||||
```toml
|
||||
[cache]
|
||||
type = "in-memory"
|
||||
```
|
||||
|
||||
This tells Kitsune to cache data directly into its memory. The cache is bounded so it doesn't make you run out of memory.
|
||||
|
||||
## Redis Cache
|
||||
|
||||
```toml
|
||||
[cache]
|
||||
type = "redis"
|
||||
redis-url = "redis://[Your Redis instance]"
|
||||
```
|
||||
|
||||
This tells Kitsune to cache data via expiring keys into the configured Redis instance.
|
||||
This is the optimal configuration for setups where you have multiple Kitsune nodes running at the same time.
|
||||
|
|
@ -0,0 +1,35 @@
|
|||
# Captcha
|
||||
|
||||
Kitsune offers the ability to require captchas on sign-up to protect your service against spam waves.
|
||||
|
||||
We offer different implementations to fit your specific needs
|
||||
|
||||
## hCaptcha
|
||||
|
||||
The rather well-known [hCaptcha service](https://www.hcaptcha.com/) advertises itself as a more privacy-oriented alternative to Google's reCaptcha.
|
||||
|
||||
To use it to protect your instance, add the following to your configuration:
|
||||
|
||||
```toml
|
||||
[captcha]
|
||||
type = "hcaptcha"
|
||||
verify-url = "[Verify URL]"
|
||||
site-key = "[Your site key]"
|
||||
secret-key = "[Your secret key]"
|
||||
```
|
||||
|
||||
## mCaptcha
|
||||
|
||||
[mCaptcha](https://mcaptcha.org/) is a lesser known open-source self-hostable captcha service.
|
||||
Technically it isn't a "captcha" and more of a "proof-of-work verification system", but it should defend your service against large spam attacks.
|
||||
|
||||
To use mCaptcha, add the following to your configuration:
|
||||
|
||||
```toml
|
||||
[captcha]
|
||||
type = "mcaptcha"
|
||||
widget-link = "[Widget link]"
|
||||
site-key = "[Your site key]"
|
||||
secret-key = "[Your secret key]"
|
||||
verify-url = "[Verify URL]"
|
||||
```
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
# Clacks Overhead
|
||||
|
||||
Clacks Overhead is a non-standard HTTP header used for as something like a silent memorial.
|
||||
The header is appended to each response via a middleware.
|
||||
|
||||
The header looks something like this:
|
||||
|
||||
```
|
||||
X-Clacks-Overhead: GNU [Name 1 here], [Name 2 here]
|
||||
```
|
||||
|
||||
[More info about this header](https://xclacksoverhead.org/home/about)
|
||||
|
||||
---
|
||||
|
||||
The names for the header can be configured like so:
|
||||
|
||||
```toml
|
||||
[server]
|
||||
clacks-overhead = [
|
||||
"Natalie Nguyen",
|
||||
"John \"Soap\" MacTavish"
|
||||
]
|
||||
```
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
# Database
|
||||
|
||||
Kitsune requires a PostgreSQL installation that it can connect to since we make usage of Postgres-specific features, such as their full-text search.
|
||||
|
||||
You can find instructions on creating a database (along with password-protected user) [here](https://medium.com/coding-blocks/creating-user-database-and-adding-access-on-postgresql-8bfcd2f4a91e).
|
||||
|
||||
> We supported SQLite in the past (before v0.0.1-pre.1), but the support has been dropped due to a high maintenance burden and rather little expected usage.
|
||||
|
||||
## Database URL structure
|
||||
|
||||
```
|
||||
postgres://[Username]:[Password]@[DBMS host]:[Port]/[Database name]
|
||||
```
|
||||
### Example URL
|
||||
|
||||
```
|
||||
postgres://database-user:password-here@localhost:5432/db-name-here
|
||||
```
|
||||
|
||||
## Maximum connections
|
||||
|
||||
The `max-connections` setting defines how many connections the globally shared connection pool will open to the database server *at maximum*.
|
||||
What you should set this value to depends on many factors.
|
||||
|
||||
> We currently do not report any pool metrics via the Prometheus endpoint. This might be added in the future.
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
# Emailing
|
||||
|
||||
Configuring an Email server for Kitsune automatically enables account confirmation via Email.
|
||||
|
||||
The mailer currently only supports SMTP, no provider-specific REST APIs.
|
||||
|
||||
## Example
|
||||
|
||||
```toml
|
||||
[email]
|
||||
from-address = "kitsunemailer@joinkitsune.org"
|
||||
host = "your.smtp.host"
|
||||
username = "admin"
|
||||
password = "password"
|
||||
starttls = false
|
||||
```
|
||||
|
||||
There is also an option config you can place in front of "from_address" if your email service provider does not do TLS over 465 and instead uses 587 (STARTTLS).
|
||||
|
||||
Here is an example configuration utilizing STARTTLS:
|
||||
|
||||
```toml
|
||||
[email]
|
||||
from_address = "kitsunemailer@joinkitsune.org"
|
||||
host = "your.smtp-host.example"
|
||||
username = "admin"
|
||||
password = "password"
|
||||
starttls = true
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
```starttls``` :
|
||||
|
||||
By default Kitsune users the port 465 to send mail.
|
||||
|
||||
Most service providers use this port, but some (for example Postmark) need to have their TLS usage bootstrapped via STARTTLS over port 587.
|
||||
|
||||
```from-address``` :
|
||||
|
||||
This is the address Kitsune puts into the `From` field of the Email
|
||||
|
||||
```host``` :
|
||||
|
||||
This is the domain that your SMTP server is reachable under.
|
||||
|
||||
```username, password``` :
|
||||
|
||||
The credentials to your SMTP server. Which values to put here vary from provider to provider.
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
# Federation filter
|
||||
|
||||
Kitsune has a basic federation filter. It has two main modes of operation:
|
||||
|
||||
- Allowlist-based
|
||||
- Denylist-based
|
||||
|
||||
The domain list supports [globbing](https://en.wikipedia.org/wiki/Glob_(programming)), so can, among other things, define wildcard blocks.
|
||||
|
||||
## Allowlist
|
||||
|
||||
As the name might suggests, this mode allows instance administrators to define a set list of domains the server is allowed to interact with.
|
||||
Federation attempts from any other server are rejected.
|
||||
|
||||
### Configuration example
|
||||
|
||||
```toml
|
||||
[instance.federation-filter]
|
||||
type = "allow"
|
||||
domains = ["*.myfriends.com", "cool-instan.ce"]
|
||||
```
|
||||
|
||||
## Denylist
|
||||
|
||||
This is the opposite of the allowlist-based federation. In this mode, Kitsune generally accepts federation attempts from any instance *except* the ones defined in the domain list.
|
||||
|
||||
### Configuration example
|
||||
|
||||
```toml
|
||||
[instance.federation-filter]
|
||||
type = "deny"
|
||||
domains = ["*.badstuff.com", "mean-people.biz"]
|
||||
```
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
# Instance
|
||||
|
||||
Kitsune has a number of configurations that change how your instance works.
|
||||
|
||||
```toml
|
||||
[instance]
|
||||
name = "Kitsune"
|
||||
description = "https://www.youtube.com/watch?v=6lnnPnr_0SU"
|
||||
character-limit = 5000
|
||||
registrations-open = true
|
||||
```
|
||||
|
||||
## `name`
|
||||
|
||||
This changes the name of the instance displayed on the landing page and returned via instance metadata endpoints (such as Mastodon's `/api/v1/instance`).
|
||||
|
||||
## `description`
|
||||
|
||||
Similar to `name`, this setting adjusts the description on the landing page and the one returned via the metadata endpoints.
|
||||
|
||||
> **Note**: This field is interpreted as raw HTML
|
||||
|
||||
## `character-limit`
|
||||
|
||||
This setting sets the character limit specific to your instance.
|
||||
|
||||
## `registrations-open`
|
||||
|
||||
Determines whether your instance accepts new users or not. When set to `false`, the registration APIs will return a failure code.
|
||||
|
||||
## `webfinger-domain`
|
||||
|
||||
This enables you to host your `.well-known/webfinger` resource on your main domain (i.e. `example.com`) and the web UI and inboxes on a subdomain (i.e. `kitsune.example.com`).
|
||||
The advantage of this configuration is that your handle can be `@me@example.com`, while the account is hosted on `fedi.example.com`.
|
||||
|
||||
### Example value
|
||||
|
||||
```toml
|
||||
webfinger-domain = "example.com"
|
||||
```
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
# Job Scheduler
|
||||
|
||||
Kitsune uses the database to store and retrieve jobs that have to be run.
|
||||
There are options to tune the job scheduler to your specific needs.
|
||||
|
||||
```toml
|
||||
[job-queue]
|
||||
redis-url = "redis://localhost"
|
||||
num-workers = 20
|
||||
```
|
||||
|
||||
## `redis-url`
|
||||
|
||||
This option configures the Redis instance that the jobs are put on.
|
||||
|
||||
We utilize Redis streams and transactional Lua scripting to ensure no jobs are lost even in the case of a crash.
|
||||
|
||||
## `job-workers`
|
||||
|
||||
This option configures how many jobs are run concurrently at the same time.
|
||||
|
||||
Each job is a lightweight task inside Kitsune's async runtime, so you can raise this well above what you'd raise a thread limit to.
|
||||
|
||||
> **Caution**: Each activity delivery is a job, and each of the delivery jobs run multiple connections concurrently.
|
||||
> Raising this job worker limit too high without also increasing the maximum file descriptors might lead to weird issues.
|
||||
|
|
@ -0,0 +1,11 @@
|
|||
# Link embedding
|
||||
|
||||
Kitsune has the ability to show link previews as so-called "embed cards".
|
||||
We use [Lantern Chat's `embed-service`](https://github.com/Lantern-chat/embed-service/) to provide this functionality.
|
||||
|
||||
To use it with Kitsune, run the `embed-service` and add the following configuration to Kitsune's configuration file:
|
||||
|
||||
```toml
|
||||
[embed]
|
||||
service-url = "[URL to the embed service]"
|
||||
```
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
# Messaging
|
||||
|
||||
Kitsune uses messaging services to exchange events for cache invalidation, notification delivery, etc.
|
||||
To offer flexibility and to make self-hosting as easy as possible, we have multiple such backends.
|
||||
|
||||
## Redis backend
|
||||
|
||||
This is backend you should choose when running multiple nodes in parallel. This then uses Redis' PubSub feature to exchange messages.
|
||||
|
||||
### Configuration example
|
||||
|
||||
```toml
|
||||
[messaging]
|
||||
type = "redis"
|
||||
redis-url = "redis://localhost:6379"
|
||||
```
|
||||
|
||||
## In-process
|
||||
|
||||
This backend is optimal for small self-contained installations. It uses Tokio's broadcast channel internally.
|
||||
|
||||
### Configuration example
|
||||
|
||||
```toml
|
||||
[messaging]
|
||||
type = "in-process"
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
# OIDC (OpenID Connect)
|
||||
|
||||
> This feature is gated behind the `oidc` compile-time feature
|
||||
|
||||
OpenID Connect (OIDC) is a technology to provide Single Sign-On (SSO) that it shared across multiple services.
|
||||
This is useful if you, for example, want to run Kitsune together with a bunch of other services and don't want to maintain multiple logins.
|
||||
|
||||
In order to enable OIDC for your Kitsune instance, find the `oidc` parameter inside the `server` configuration section.
|
||||
Set this parameter to the following value:
|
||||
|
||||
```toml
|
||||
[server.oidc]
|
||||
server-url = "[Issuer URL]"
|
||||
client-id = "[Kitsune's Client ID]"
|
||||
client-secret = "[Kitsune's Client Secret]"
|
||||
|
||||
[server.oidc.store]
|
||||
type = "in-memory" # "in-memory" or "redis"
|
||||
#url = "redis://localhost" # If the configured type is "redis"
|
||||
```
|
||||
|
||||
## Server URL
|
||||
|
||||
This is the URL of the issuer; this setting differs between OIDC solutions. Don't worry, Kitsune won't start up if this value is invalid.
|
||||
|
||||
## Client ID and Secret
|
||||
|
||||
These values are created on the dashboard of the OIDC solution you are using.
|
||||
Kitsune needs these to obtain an access token from the OIDC server to do introspection and obtain some information about the user.
|
||||
|
||||
## Store
|
||||
|
||||
The store is where the login state is stored in temporarily until the sign-in has completed.
|
||||
|
||||
### Supported backends
|
||||
|
||||
- `in-memory`: The state is stored in an in-memory LRU structure
|
||||
- `redis`: The state is stored in a Redis instance
|
||||
|
||||
If you run multiple nodes, you should use Redis. Otherwise sign-ins can randomly fail.
|
||||
|
||||
## Kitsune-specific OIDC requirements
|
||||
|
||||
The OIDC server **must** return the following values in the claim:
|
||||
|
||||
- `preferred_username`
|
||||
- `email`
|
||||
|
||||
> Keep the preferred username field unique. The username is used to identify the user inside Kitsune's database that's getting registered.
|
||||
> This might change in the future.
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
# OpenTelemetry
|
||||
|
||||
Kitsune can export its traces and metrics via the OpenTelemetry Protocol (or OTLP, for short).
|
||||
|
||||
To push the data to an endpoint, add the following to your configuration:
|
||||
|
||||
```toml
|
||||
[opentelemetry]
|
||||
# Where Kitsune pushes metrics (eg. Prometheus)
|
||||
metrics-transport = "http" # "http" or "grpc"
|
||||
metrics-endpoint = "https://localhost:5050/metrics-endpoint"
|
||||
# Where Kitsune pushes traces (eg. Jaeger)
|
||||
tracing-transport = "http" # "http" or "grpc"
|
||||
tracing-endpoint = "https://localhost:5050/tracing-endpoint"
|
||||
```
|
||||
|
|
@ -0,0 +1,36 @@
|
|||
# Search
|
||||
|
||||
Kitsune has a number of search backends, each different from the other, to best fit your specific needs.
|
||||
We want to give you a brief overview over the available backends.
|
||||
|
||||
## No Search
|
||||
|
||||
```toml
|
||||
[search]
|
||||
type = "none"
|
||||
```
|
||||
|
||||
This completely disables the search on your instance. Finding posts and accounts is now only possible via direct links and handles.
|
||||
|
||||
## SQL-based Search
|
||||
|
||||
```toml
|
||||
[search]
|
||||
type = "sql"
|
||||
```
|
||||
|
||||
This runs searches on your database directly. The quality is actually not too bad and uses automatic language detection to make full-text searches relevant.
|
||||
|
||||
## Meilisearch
|
||||
|
||||
> You need to compile Kitsune with the `meilisearch` feature flag to enable this feature
|
||||
|
||||
```toml
|
||||
[search]
|
||||
type = "meilisearch"
|
||||
instance-url = "[URL of your Meilisearch instance]"
|
||||
api-key = "[API key to access your Meilisearch instance]"
|
||||
```
|
||||
|
||||
This instructs Kitsune to use [Meilisearch](https://www.meilisearch.com/) as the search engine. Meilisearch provides incredibly fast, high-quality full-text search.
|
||||
Meilisearch also has a cloud offering, making this the easiest high-quality search to use with Kitsune.
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
# Storage
|
||||
|
||||
As a microblogging platform, Kitsune also offers users the ability to attach images, videos, and audio to their posts.
|
||||
We offer multiple different storage backends to store the attachments to.
|
||||
|
||||
> **Note**: You might want to increase the upload limit by tweaking the `max-upload-size` parameter in your configuration; the number is the upload limit in bytes.
|
||||
> The default set by the example configuration is 5MiB.
|
||||
|
||||
## File System
|
||||
|
||||
This is recommended for small instances.
|
||||
Kitsune simply stores the media inside a user-defined directory on the local file system.
|
||||
|
||||
In order to enable this, add this to your configuration:
|
||||
|
||||
```toml
|
||||
[storage]
|
||||
type = "fs"
|
||||
upload-dir = "path/to/upload/directory"
|
||||
```
|
||||
|
||||
This will then place all the uploads into the specified directory.
|
||||
|
||||
## S3-compatible storage
|
||||
|
||||
When your user count increases (or your requirements change), you might want to consider using an S3-compatible storage solution to store all your media attachments.
|
||||
|
||||
In order to make this happen, add this to your configuration:
|
||||
|
||||
```toml
|
||||
[storage]
|
||||
type = "s3"
|
||||
bucket-name = "[Name of your bucket]"
|
||||
endpoint-url = "[Name of the endpoint]"
|
||||
region = "[Region of your S3 storage]"
|
||||
force-path-style = false
|
||||
access-key = "[Access key]"
|
||||
secret-access-key = "[Secret access key]"
|
||||
```
|
||||
|
||||
### Bucket Name
|
||||
|
||||
This setting is pretty self-explanatory. It's the name of the bucket you created and want your attachments to be put in.
|
||||
|
||||
### Endpoint URL
|
||||
|
||||
The URL of the S3 endpoint. You can either get this from your storage provider's dashboard or documentation; really depends on the provider.
|
||||
|
||||
### Region
|
||||
|
||||
The S3 region in which you created the bucket. The value of this might be different from provider to provider.
|
||||
|
||||
### Force Path Style
|
||||
|
||||
Some S3 storage providers don't support the virtual-hosted request style. If your provider is one of those, set this setting to `true` to instruct Kitsune to use the legacy path style.
|
||||
|
||||
### (Secret) Access Key
|
||||
|
||||
These keys are given to you when creating your bucket. Make sure you keep these private!
|
||||
|
||||
### Notes on "get_object" requests
|
||||
|
||||
Currently Kitsune proxies all the S3 accesses, meaning each media access results in a "get object" request.
|
||||
For example, Cloudflare R2 has a "no egress fee policy" which, due to this implementation detail, doesn't apply to Kitsune.
|
||||
|
||||
> This is not final, we might change how S3 uploads are handled
|
||||
|
||||
### Migrating from file-system storage to S3
|
||||
|
||||
The migration is pretty simple. Upload all the files from your upload directory into the S3 bucket (while preserving the same file hirearchy) and change the configuration.
|
||||
Kitsune should then serve the files without any problems.
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
# Introduction
|
||||
|
||||
Kitsune is a decentralised microblogging platform built on the ActivityPub protocol.
|
||||
This means that anyone can run their own Kitsune on their own hardware and seamlessly interact with each other.
|
||||
|
||||
Of course you can also sign up on an existing instance to try it out, no strings attached.
|
||||
If you are interested in running your own instance, head over to our installation guide.
|
||||
|
||||
## Chat
|
||||
|
||||
Feel free to join our chat if you have any problems or if you want to contribute.
|
||||
We have channels on Matrix and Discord which are bridged with each other, so join whichever you are more comfortable with.
|
||||
|
||||
[](https://matrix.to/#/#kitsune-space:matrix.org)
|
||||
[](https://discord.gg/YGAtX7nfrG)
|
||||
|
||||
(The side-panel links to the Matrix room since Matrix is the more open and privacy-respecting solution out of the both)
|
||||
|
|
@ -0,0 +1,80 @@
|
|||
# Basic configuration
|
||||
|
||||
Kitsune is using the [TOML configuration format](https://toml.io) to configure the main application and the job runner.
|
||||
The syntax itself is easy to grasp and is essentially and extended INI format.
|
||||
|
||||
> The auxiliary services/CLI tools are using environment variables at the moment.
|
||||
> Note that this might change in the future.
|
||||
|
||||
> Example configurations for external programs can be found in `kitsune/contrib`.
|
||||
|
||||
> The example config for Kitsune can be found in the root directory titled "config.example.toml", move it wherever you like, and feel free to rename it.
|
||||
|
||||
The simplest Kitsune configuration looks like this:
|
||||
|
||||
```toml
|
||||
[cache]
|
||||
type = "in-memory"
|
||||
|
||||
[database]
|
||||
url = "postgres://localhost/kitsune"
|
||||
max-connections = 20
|
||||
|
||||
[instance]
|
||||
name = "Kitsune"
|
||||
description = "https://www.youtube.com/watch?v=6lnnPnr_0SU"
|
||||
character-limit = 5000
|
||||
registrations-open = true
|
||||
|
||||
[instance.federation-filter]
|
||||
type = "deny"
|
||||
domains = []
|
||||
|
||||
[job-queue]
|
||||
redis-url = "redis://localhost"
|
||||
num-workers = 20
|
||||
|
||||
[messaging]
|
||||
type = "in-process"
|
||||
|
||||
[server]
|
||||
frontend-dir = "./kitsune-fe/dist"
|
||||
max-upload-size = 20242880 # 5MB
|
||||
media-proxy-enabled = false
|
||||
port = 5000
|
||||
request-timeout-secs = 60
|
||||
|
||||
[search]
|
||||
type = "sql"
|
||||
|
||||
[storage]
|
||||
type = "fs"
|
||||
upload-dir = "./uploads"
|
||||
|
||||
[url]
|
||||
scheme = "https"
|
||||
domain = "kitsune.example.com"
|
||||
```
|
||||
|
||||
To successfully deploy the application, make sure you **at least** change the following sections to your own:
|
||||
|
||||
- `domain`
|
||||
|
||||
- Domain of your instance. Used to build the URLs of your activities.
|
||||
- This is a *very important* setting and **cannot** be changed after the first setup.
|
||||
|
||||
- `database`
|
||||
|
||||
- Specifically the `url` parameter. Refer to [database section](../configuring/database) page for the expected format.
|
||||
|
||||
- `job-queue`
|
||||
|
||||
- Specifically the `redis-url` parameter. Refer to the [job scheduler](../configuring/job-scheduler) page for the expected format.
|
||||
|
||||
To run the application use the following command:
|
||||
|
||||
```bash
|
||||
./kitsune -c [path-to-config-file]
|
||||
```
|
||||
|
||||
In order to read up on all the possible configurations, check out the "Configuration" section.
|
||||
|
|
@ -0,0 +1,65 @@
|
|||
# Installation
|
||||
|
||||
At the moment, the only way to install Kitsune is to compile it from source.
|
||||
Don't worry, that sounds way more scary than it actually is. In this guide we will step you through it.
|
||||
|
||||
## Dependencies
|
||||
|
||||
In order to build Kitsune, need a few dependencies. These are:
|
||||
|
||||
1. The Rust toolchain ([recommended installation](https://rustup.rs/))
|
||||
2. PostgreSQL as a dedicated DBMS
|
||||
3. Redis for the job queue
|
||||
4. [NodeJS](https://nodejs.org/en) v16+
|
||||
5. [Yarn](https://classic.yarnpkg.com/en/docs/install)
|
||||
6. Reverse Proxy (recommended: [Caddy](https://caddyserver.com/docs/install))
|
||||
|
||||
Yes, that's really it. We don't need more. Kitsune is designed to use as few native dependencies as possible to make building from source easy!
|
||||
|
||||
### Note on C/C++ compiler requirement
|
||||
|
||||
Rust needs a C/C++ compiler to invoke the linker and potentially build some native libraries to statically link to, so make sure you have one installed.
|
||||
|
||||
To install it under Debian and Ubuntu, run the following command:
|
||||
|
||||
```bash
|
||||
sudo apt install build-essential
|
||||
```
|
||||
|
||||
The name of the package(s) containing these tools might differ between distributions.
|
||||
|
||||
## Building
|
||||
|
||||
First, grab yourself a copy of the source code. You can either download the [main branch ZIP archive](https://github.com/kitsune-soc/kitsune/archive/refs/heads/main.zip) or clone it via Git. Both ways will work just fine.
|
||||
|
||||
> The recommended way to download the source is via Git since it makes updating and doing a rollback way easier.
|
||||
|
||||
To download a Git repository, just run the following command (this assumes you have [Git](https://git-scm.com/) installed):
|
||||
|
||||
```bash
|
||||
git clone https://github.com/kitsune-soc/kitsune.git
|
||||
```
|
||||
|
||||
> If you downloaded the ZIP, just unzip the archive
|
||||
|
||||
Next, move into the newly created directory and then into the `kitsune-fe` directory and build the frontend.
|
||||
To do this run:
|
||||
|
||||
```bash
|
||||
yarn install && yarn build
|
||||
```
|
||||
|
||||
Now move out of the directory and back into the main one. Then build the binaries in release mode.
|
||||
To do this run the following command:
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
After the command finished there should be the following three binaries inside the `target/release` directory:
|
||||
|
||||
- `kitsune`: The main Kitsune application. This is the heart of the whole application.
|
||||
- `kitsune-cli`: The Kitsune CLI utility. Used to give users roles and clear the job scheduler table.
|
||||
- `kitsune-job-runner`: The dedicated Kitsune job runner
|
||||
|
||||
That's it for the building part but before we can actually run our instance, we need to configure it first.
|
||||
|
|
@ -0,0 +1,19 @@
|
|||
# HTTP signatures
|
||||
|
||||
HTTP signatures are used by Kitsune to validate that the Activity/Object actually originates from the user it claims to.
|
||||
We implement a subset of [`draft-cavage-http-signatures-12`](https://datatracker.ietf.org/doc/html/draft-cavage-http-signatures-12) to do this.
|
||||
|
||||
Only asymmetric cryptographic algorithms are implemented since the symmetric ones:
|
||||
|
||||
1. Could lead to potential key-confusion attacks
|
||||
2. Aren't useful in the context of ActivityPub
|
||||
|
||||
We make use of the `keyId` field by looking up the public key material via this ID. The ID is sourced from the ActivityPub actor.
|
||||
The signature scheme used is inferred by the OID embedded in the public key material. The material is expected to be an X.509 SPKI structure.
|
||||
|
||||
At the moment, Kitsune uses RSA keys but has support for implementations that use Ed25519 for signatures.
|
||||
|
||||
> We use RSA because Mastodon doesn't support anything else. So if you want compatibility with Mastodon, you have to use RSA.
|
||||
> As soon as a mainline Mastodon release gets support for Ed25519 signatures, we will release an update that allows to rekey all the users.
|
||||
|
||||
But if you are happy to just federate with Kitsune users, you can use Ed25519!
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
# Webfinger
|
||||
|
||||
Kitsune uses Webfinger for resolving mentions and such. For example, when mentioning a user in a post in the form `@user@instance.org`, the mention is interpreted as a Webfinger `acct` query.
|
||||
We then connect to the remote server and send an HTTP GET request on the path `/.well-known/webfinger` with the query parameter `resource` set to `acct:user@instance.org`.
|
||||
|
||||
The server is then expected to return a Webfinger resource containing a link with the `rel` property set to `self` and the `href` attribute pointing to the ActivityPub actor.
|
||||
|
||||
Example Webfinger resource:
|
||||
|
||||
```json
|
||||
{
|
||||
"subject": "acct:user@instance.org",
|
||||
"aliases": [],
|
||||
"links": [
|
||||
{
|
||||
"rel": "self",
|
||||
"href": "https://instance.org/users/user"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
{
|
||||
"build": {
|
||||
"dist_dir": "dist"
|
||||
},
|
||||
"components": {
|
||||
"artifacts": {
|
||||
"cargo_dist": true
|
||||
},
|
||||
"changelog": {
|
||||
"read_changelog_file": false
|
||||
}
|
||||
},
|
||||
"project": {
|
||||
"name": "Kitsune",
|
||||
"license": "MIT",
|
||||
"repository": "https://github.com/kitsune-soc/kitsune"
|
||||
},
|
||||
"styles": {
|
||||
"theme": "hacker"
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue