2023-04-15 09:41:42 +09:00
|
|
|
|
# akyuu – a twtxt server that never forgets
|
2016-02-07 01:05:26 +09:00
|
|
|
|
|
2016-02-10 10:22:34 +09:00
|
|
|
|
## Rationale
|
2016-02-07 01:05:26 +09:00
|
|
|
|
|
2016-02-10 07:28:42 +09:00
|
|
|
|
[*twtxt*](https://github.com/buckket/twtxt) is a protocol and client for
|
2016-02-08 00:28:08 +09:00
|
|
|
|
decentralized microblogging. Users are expected to provide their feeds as plain
|
2016-02-10 07:28:42 +09:00
|
|
|
|
text files with URLs accessible over the Internet. *htwtxt* is a web server to
|
2016-02-08 00:28:08 +09:00
|
|
|
|
host and grow such text files for users without trivial access to their own web
|
|
|
|
|
space.
|
2016-02-07 01:05:26 +09:00
|
|
|
|
|
2016-02-13 08:46:03 +09:00
|
|
|
|
## Features
|
2016-02-13 05:25:26 +09:00
|
|
|
|
|
2016-02-13 08:41:21 +09:00
|
|
|
|
- individual twtxt feeds mapped to user accounts with password-protected write
|
|
|
|
|
access
|
2016-02-13 05:25:26 +09:00
|
|
|
|
- no sessions, no cookies: few POST-writable resources (feeds, account data)
|
2016-02-13 08:41:21 +09:00
|
|
|
|
expect credentials, which to store between requests if desired is up to the
|
|
|
|
|
user / browser
|
2016-02-17 05:44:31 +09:00
|
|
|
|
- twtxt messages can be written via a HTML form in a web browser or via an API
|
2016-02-13 08:48:20 +09:00
|
|
|
|
- account registration may be open to the public, or (default) closed (with the
|
|
|
|
|
site operator adding new accounts manually)
|
2016-02-13 08:41:21 +09:00
|
|
|
|
- users may add e-mail addresses and optional security questions to their
|
|
|
|
|
accounts to use for a password reset mechanism (if enabled by site operator)
|
2016-02-13 05:30:30 +09:00
|
|
|
|
- HTTPS / TLS support (if paths to key and certificate files are provided)
|
2016-02-13 08:41:21 +09:00
|
|
|
|
- all HTML+CSS is read from a templates directory, which can be freely chosen at
|
|
|
|
|
server start so as to ease customization of the interface
|
2016-02-13 05:25:26 +09:00
|
|
|
|
|
2016-02-10 10:25:15 +09:00
|
|
|
|
## Setup and run
|
2016-02-10 10:22:34 +09:00
|
|
|
|
|
2016-02-10 10:25:15 +09:00
|
|
|
|
### Setup Go build environment
|
2016-02-10 10:22:34 +09:00
|
|
|
|
|
|
|
|
|
With htwtxt written in Go, the setup instructions below expect a Go development
|
|
|
|
|
environment – with a somewhat current [go tool](https://golang.org/cmd/go/)
|
2016-02-13 05:25:26 +09:00
|
|
|
|
installed, and a `$GOPATH` set. (Note that the golang package of version 1.3.3
|
|
|
|
|
that is part of Debian Jessie is a bit too old already.) If your system does not
|
|
|
|
|
have such an environment, here's some hints on how to set it up:
|
2016-02-10 10:22:34 +09:00
|
|
|
|
|
|
|
|
|
wget https://storage.googleapis.com/golang/go1.5.3.linux-amd64.tar.gz
|
|
|
|
|
sudo tar -C /usr/local -xzf go1.5.3.linux-amd64.tar.gz
|
|
|
|
|
export GOPATH=~/go
|
|
|
|
|
export PATH=$PATH:/usr/local/go/bin
|
|
|
|
|
|
|
|
|
|
(You might want to add the last two lines to your `.bashrc` or whatever usually
|
|
|
|
|
initializes your environment variables. And you might want to replace the
|
|
|
|
|
package pulled by wget by whatever is the newest stable release of Go
|
|
|
|
|
available.)
|
|
|
|
|
|
|
|
|
|
### Clone, build, run
|
2016-02-07 01:05:26 +09:00
|
|
|
|
|
2016-02-10 10:25:15 +09:00
|
|
|
|
Once your Go build environment is ready, do this:
|
2016-02-07 01:05:26 +09:00
|
|
|
|
|
2023-04-15 09:41:42 +09:00
|
|
|
|
go install marisa.chaotic.ninja/akyuu@latest
|
|
|
|
|
$GOPATH/bin/akyuu [options]
|
2016-02-07 01:05:26 +09:00
|
|
|
|
|
2016-02-10 07:18:05 +09:00
|
|
|
|
This will build and start the server, which will store login and feed data below
|
2023-04-15 09:41:42 +09:00
|
|
|
|
`~/akyuu`. An alternate directory may be specified with the `--dir` flag.
|
2016-02-07 01:05:26 +09:00
|
|
|
|
|
2016-02-17 05:46:26 +09:00
|
|
|
|
### Writing twtxt messages via API
|
|
|
|
|
|
2023-04-15 09:41:42 +09:00
|
|
|
|
Using akyuu from a web browser for purposes such as writing a twtxt message
|
2016-02-17 05:46:26 +09:00
|
|
|
|
should be self-explanatory (just use the HTML form on the start page). But it's
|
|
|
|
|
also possible to write new messages directly to a twtxt feed via a `POST`
|
|
|
|
|
request to `/feeds`. Just provide appropriate values for the data fields `name`
|
|
|
|
|
and `password` (your login) and `twt` (the message to append). Here's a command
|
|
|
|
|
line example utilizing the curl tool:
|
|
|
|
|
|
|
|
|
|
curl -X POST -d 'name=foo' -d 'password=bar' -d 'twt=Hi there.' \
|
|
|
|
|
http://test.plomlompom.com:8000/feeds
|
|
|
|
|
|
2016-02-10 10:22:34 +09:00
|
|
|
|
## Tweaking
|
|
|
|
|
|
2016-02-12 22:18:59 +09:00
|
|
|
|
### Configure port number and TLS
|
2016-02-07 01:05:26 +09:00
|
|
|
|
|
2023-04-15 09:41:42 +09:00
|
|
|
|
By default, akyuu serves unencrypted HTTP over port 8000. But the executable
|
2016-02-10 07:37:10 +09:00
|
|
|
|
accepts the flag `--port` to provide an alternate port number, and the flags
|
|
|
|
|
`--cert` and `--key` to provide paths to an SSL certificate and key file to run
|
2023-04-15 09:41:42 +09:00
|
|
|
|
akyuu as an HTTPS server.
|
2016-02-07 01:05:26 +09:00
|
|
|
|
|
2016-02-10 10:22:34 +09:00
|
|
|
|
You might encounter the following issue when trying to set a low port number
|
|
|
|
|
(such as the HTTP standard 80, or the HTTPS standard 443):
|
|
|
|
|
|
|
|
|
|
ListenAndServe: listen tcp :80: bind: permission denied
|
|
|
|
|
|
|
|
|
|
This is [a common privilege problem](http://stackoverflow.com/q/413807) and
|
|
|
|
|
[might be solved](http://stackoverflow.com/a/414258) bis this:
|
|
|
|
|
|
2023-04-15 09:41:42 +09:00
|
|
|
|
sudo setcap 'cap_net_bind_service=+ep' $GOPATH/bin/akyuu
|
2016-02-10 10:22:34 +09:00
|
|
|
|
|
2016-02-13 07:51:15 +09:00
|
|
|
|
### Public or closed sign-up
|
2016-02-10 10:22:34 +09:00
|
|
|
|
|
2016-02-13 07:51:15 +09:00
|
|
|
|
By default, sign up / account creation is not open to the web-browsing public.
|
|
|
|
|
The `--signup` flag must be set explicitely to change that. Alternatively, new
|
|
|
|
|
accounts can be added by starting the program with the `--adduser` flag,
|
|
|
|
|
followed by an argument of the form `NAME:PASSWORD`.
|
2016-02-10 10:22:34 +09:00
|
|
|
|
|
2016-02-12 22:18:59 +09:00
|
|
|
|
### Set site owner contact info
|
2016-02-11 09:19:22 +09:00
|
|
|
|
|
|
|
|
|
The server serves a `/info` page (from the `info.html` template) that may
|
2016-03-03 00:04:01 +09:00
|
|
|
|
include the site owner's contact info, as given with the `--contact` flag.
|
2016-02-11 09:19:22 +09:00
|
|
|
|
|
2016-02-12 22:18:59 +09:00
|
|
|
|
### Activate password reset mails
|
|
|
|
|
|
|
|
|
|
Feed owners may add e-mail addresses to their login data to authenticate
|
|
|
|
|
themselves to the site operator and receive password reset links when requested.
|
|
|
|
|
The password reset mechanism by mail is inactive by default. To activate it, a
|
2016-02-12 22:21:46 +09:00
|
|
|
|
set of flags `--mailserver`, `--mailport`, `--mailuser` must be set to describe
|
|
|
|
|
a SMTP server and its login from which to send password reset mails to users'
|
|
|
|
|
mail addresses. (The site operator will be prompted for his SMTP login password
|
2016-02-12 22:24:22 +09:00
|
|
|
|
on program start.) Whether this mechanism is trustworthy or not is up to the
|
2016-02-13 08:46:03 +09:00
|
|
|
|
site operator's imagination. Users may set up optional security questions to be
|
|
|
|
|
posed on the password reset links they enable by setting their mail address.
|
2016-02-12 22:18:59 +09:00
|
|
|
|
|
2016-02-12 22:21:46 +09:00
|
|
|
|
### Change HTML templates
|
2016-02-11 09:45:05 +09:00
|
|
|
|
|
2023-04-15 09:41:42 +09:00
|
|
|
|
By default, HTML templates are read out of `$GOPATH/src/akyuu/templates/`. An
|
2016-02-11 09:45:05 +09:00
|
|
|
|
alternate directory can be given with the flag `--templates` (it should contain
|
|
|
|
|
template files of the same names as the default ones, however).
|
|
|
|
|
|
2016-02-13 08:56:22 +09:00
|
|
|
|
## Copyright, license, version
|
2016-02-07 01:05:26 +09:00
|
|
|
|
|
2016-02-13 05:30:30 +09:00
|
|
|
|
htwtxt (c) 2016 Christian Heller a.k.a. [plomlompom](http://www.plomlompom.de),
|
|
|
|
|
with template design input by [Kai Kubasta](http://kaikubasta.de).
|
2016-02-08 00:28:08 +09:00
|
|
|
|
|
2023-04-15 09:41:42 +09:00
|
|
|
|
akyuu (c) 2023-present Izuru Yakumo.
|
|
|
|
|
|
2016-02-10 07:43:33 +09:00
|
|
|
|
License: Affero GPL version 3, see `./LICENSE`
|
2016-02-13 08:56:22 +09:00
|
|
|
|
|
2016-07-28 03:40:15 +09:00
|
|
|
|
Current version number: 1.0.7
|