about summary refs log tree commit diff
path: root/README.md
blob: 85f0e704c6164cc8824cfc2bc5c61391861e84ef (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
# 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
 - 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
$ cd ./kittybox-rs/
$ 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 = (builtins.getFlake "git+https://git.sr.ht/~vikanezrimaya/kittybox?ref=main");
in {
  imports = [
    kittybox.nixosModules.default
  ];
  
  services.kittybox.enable = true;
}
```

### 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:
 - `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.-->
 - `BLOBSTORE_URI`: Your media endpoint storage URI, used to store
   files uploaded via the media endpoint.
   - To use flat files, use `file://` and append an absolute path to
     your folder like this: `file:///var/lib/kittybox/media`
 - `AUTH_STORE_URI`: Storage for authentication-related data (tokens,
   authorization codes etc.)
   - To use flat files, use `file://` and append an absolute path to
     your folder like this: `file:///var/lib/kittybox/auth`

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.