128 行
5.4 KiB
Markdown
128 行
5.4 KiB
Markdown
# akyuu – a twtxt server that never forgets
|
||
|
||
## Rationale
|
||
|
||
[*twtxt*](https://github.com/buckket/twtxt) is a protocol and client for
|
||
decentralized microblogging. Users are expected to provide their feeds as plain
|
||
text files with URLs accessible over the Internet. *htwtxt* is a web server to
|
||
host and grow such text files for users without trivial access to their own web
|
||
space.
|
||
|
||
## Features
|
||
|
||
- individual twtxt feeds mapped to user accounts with password-protected write
|
||
access
|
||
- no sessions, no cookies: few POST-writable resources (feeds, account data)
|
||
expect credentials, which to store between requests if desired is up to the
|
||
user / browser
|
||
- twtxt messages can be written via a HTML form in a web browser or via an API
|
||
- account registration may be open to the public, or (default) closed (with the
|
||
site operator adding new accounts manually)
|
||
- 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)
|
||
- HTTPS / TLS support (if paths to key and certificate files are provided)
|
||
- 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
|
||
|
||
## Setup and run
|
||
|
||
### Setup Go build environment
|
||
|
||
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/)
|
||
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:
|
||
|
||
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
|
||
|
||
Once your Go build environment is ready, do this:
|
||
|
||
go install marisa.chaotic.ninja/akyuu@latest
|
||
$GOPATH/bin/akyuu [options]
|
||
|
||
This will build and start the server, which will store login and feed data below
|
||
`~/akyuu`. An alternate directory may be specified with the `--dir` flag.
|
||
|
||
### Writing twtxt messages via API
|
||
|
||
Using akyuu from a web browser for purposes such as writing a twtxt message
|
||
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
|
||
|
||
## Tweaking
|
||
|
||
### Configure port number and TLS
|
||
|
||
By default, akyuu serves unencrypted HTTP over port 8000. But the executable
|
||
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
|
||
akyuu as an HTTPS server.
|
||
|
||
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:
|
||
|
||
sudo setcap 'cap_net_bind_service=+ep' $GOPATH/bin/akyuu
|
||
|
||
### Public or closed sign-up
|
||
|
||
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`.
|
||
|
||
### Set site owner contact info
|
||
|
||
The server serves a `/info` page (from the `info.html` template) that may
|
||
include the site owner's contact info, as given with the `--contact` flag.
|
||
|
||
### 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
|
||
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
|
||
on program start.) Whether this mechanism is trustworthy or not is up to the
|
||
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.
|
||
|
||
### Change HTML templates
|
||
|
||
By default, HTML templates are read out of `$GOPATH/src/akyuu/templates/`. An
|
||
alternate directory can be given with the flag `--templates` (it should contain
|
||
template files of the same names as the default ones, however).
|
||
|
||
## Copyright, license, version
|
||
|
||
htwtxt (c) 2016 Christian Heller a.k.a. [plomlompom](http://www.plomlompom.de),
|
||
with template design input by [Kai Kubasta](http://kaikubasta.de).
|
||
|
||
akyuu (c) 2023-present Izuru Yakumo.
|
||
|
||
License: Affero GPL version 3, see `./LICENSE`
|
||
|
||
Current version number: 1.0.7
|