README.md: init

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.