diff options
| -rw-r--r-- | README.md | 107 |
1 files changed, 107 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..be18318 --- /dev/null +++ b/README.md @@ -0,0 +1,107 @@ +# Kittybox + +Kittybox is an IndieWeb-centric blogging solution designed for easy +self-hosting in any environment from a single-board computer in your +closet to a PaaS platform or a public cloud. + +## Implementation status +Kittybox is currently is not fully suitable for production, however, +there is a deployment at https://fireburn.ru/ used as my personal +blog. + +Some things aren't currently fully implemented. The non-exhaustive +list is: + - Logging in via IndieAuth + - Using your website as an IndieAuth endpoint (polyfilled via an + external service) + - Sending Webmentions (though you can send them manually!) + - Receiving Webmentions + - Syndicating + - File uploads + - Token management (polyfilled via an external service) + - Changing settings beyond what was filled in at the onboarding + +Some planned features also include: + - An interactive (and customizable) widget on the main page + - Custom CSS + - Custom syndication locations + - A built-in fully featured admin interface + +## Building +### Using Nix +If you happen to have Nix installed: + +```console +$ nix build +``` + +You can optionally use the [binary cache][1] provided by +[nix-community][2] and backed by their [Hydra][3]. + +[1]: https://nix-community.cachix.org +[2]: https://github.com/nix-community +[3]: https://hydra.nix-community.org/jobset/kittybox/main + +### Using Cargo +First, make sure you have stable Rust installed. Kittybox doesn't use +any C libraries for building, preferring to use their Rust equivalents +for memory safety and ease of building. + +```console +$ cargo build +``` + +For tests, you will need development files for OpenSSL and zlib +installed. Consult with your distribution's manual on how to install +them. These are only used for building httpmock, a mock server for web +requests. + +```console +$ cargo check +``` + +## Deployment +### Using NixOS +```nix +{ config, pkgs, lib, ...}: let + # Included as an example. You should probably use `flake.nix` instead. + # You will get version pinning and you will probably be happier. + kittybox-flake = (builtins.getFlake "git+https://git.sr.ht/~vikanezrimaya/kittybox?ref=main"); +in { + imports = [ + kittybox-flake.nixosModule + ]; + + services.kittybox = { + enable = true; + # These will not be required in future versions. + authorizationEndpoint = "https://indieauth.com/auth"; + tokenEndpoint = "https://tokens.indieauth.com/token"; + }; +} +``` + +### Manually +Currently Kittybox requires several external components for +deployment. In the future, these will be fully reimplemented within +Kittybox to preserve your privacy and security. + +Set the following environment variables: + - `AUTHORIZATION_ENDPOINT`: Your IndieAuth authorization endpoint. If + unsure, use `https://indieauth.com/auth` + - `TOKEN_ENDPOINT`: Your IndieAuth token endpoint. If unsure, use + `https://tokens.indieauth.com/token` + - `BACKEND_URI`: Your storage backend URI, used to store post + content. + - To use flat files, use `file://` and append an absolute path to + your folder like this: `file:///var/lib/kittybox/data` + - To use Redis (currently not working) use `redis://` and append + either an URI or a path to the Unix socket for your Redis + instance. + +Additionally you can customize the `SERVE_AT` environment variable to +customize where Kittybox will listen to requests. + +Note: it is heavily recommended to deploy Kittybox behind a reverse +proxy, since it is currently unable to handle TLS by itself. +Recommended reverse proxies are Caddy and/or nginx. |