27 Commits

Author SHA1 Message Date
J. King 59c5c2eb14 Oops 3 weeks ago
J. King 3cd3ac4a51 Correct filename conflict 3 weeks ago
J. King 837895fd6a Adapt dist files for Debian 3 weeks ago
J. King b4c9413130 Update README 3 weeks ago
J. King bafb788b02 Correct errors in manual 3 weeks ago
J. King 68e3cd82ca Don't include section number in title 3 weeks ago
J. King c3fa4788d6 Use proper metadata block for manpage 3 weeks ago
J. King 3567f294a6 Merge branch 'manpage' 3 weeks ago
J. King 8c0f047747 Update HTML manual to mention man page 3 weeks ago
J. King fd76b1b611 Add examples to manual page 3 weeks ago
J. King 4317a96db1 Work around double spacing 3 weeks ago
J. King 62d49e0d3c Fill out most of the manual page 3 weeks ago
J. King 88487d27a2 Expand manual page 3 weeks ago
J. King 46c88f584f Fix copying of man page in PKGBUILDs 3 weeks ago
J. King 92823d5bc2 Create directories before executing Pandoc 3 weeks ago
J. King 3e55ab3849 Move man pages to their own directory 3 weeks ago
J. King 2ec7acc50b Turn off "smart" character substitution in Pandoc 3 weeks ago
J. King d3a983e7f0 Move the markdown manpage 3 weeks ago
J. King 176aac0ad7 Fix stupid typo properly 3 weeks ago
J. King e439dd8277 Fix manpage in Arch PKGBUILD 3 weeks ago
J. King 6cc9f96728 Prototype manual page 3 weeks ago
J. King d4569c77a9 Add database location to tmpfiles 3 weeks ago
J. King add1acc87a Fix more lintian complaints 3 weeks ago
J. King 14d3cdfe58 Hopefully fix some Debian problems 3 weeks ago
J. King 281760be71 Address some lintian complaints 3 weeks ago
J. King 758a02d667 Move generic configuration file 3 weeks ago
J. King 18846c19cb Add install list for Debian package 3 weeks ago
  1. 8
      .gitignore
  2. 6
      CHANGELOG
  3. 21
      README.md
  4. 67
      RoboFile.php
  5. 7
      dist/arch/PKGBUILD
  6. 8
      dist/arch/PKGBUILD-git
  7. 2
      dist/arsse
  8. 0
      dist/config.php
  9. 13
      dist/debian/.gitignore
  10. 17
      dist/debian/arsse.install
  11. 8
      dist/debian/control
  12. 4
      dist/debian/lintian-overrides
  13. 1
      dist/debian/rules
  14. 2
      dist/debian/source/lintian-overrides
  15. 2
      dist/systemd/arsse-fetch.service
  16. 7
      dist/tmpfiles.conf
  17. 1
      docs/en/020_Getting_Started/020_Download_and_Installation/020_On_Debian_and_Ubuntu.md
  18. 2
      docs/en/025_Using_The_Arsse/index.md
  19. 211
      lib/CLI.php
  20. 224
      manpages/en.md

8
.gitignore

@ -1,11 +1,13 @@
# Temporary files
/temp/
/documentation/
/manual/
/tests/coverage/
/dist/arch/arsse
/dist/arch/src
/dist/arch/pkg
/dist/arch/arsse/
/dist/arch/src/
/dist/arch/pkg/
/dist/man/
/arsse.db*
/config.php
/.php_cs.cache

6
CHANGELOG

@ -1,3 +1,9 @@
Version 0.9.3 (2021-??-??)
==========================
New features:
- Complete UNIX manual page
Version 0.9.2 (2021-05-25)
==========================

21
README.md

@ -8,7 +8,7 @@ Information on how to install and use the software can be found in [the manual](
The main repository for The Arsse can be found at [code.mensbeam.com](https://code.mensbeam.com/MensBeam/arsse/), with a mirror also available [at GitHub](https://github.com/mensbeam/arsse/). The GitHub mirror does not accept bug reports, but the two should otherwise be equivalent.
[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running `composer install --no-dev` is recommended.
[Composer](https://getcomposer.org/) is required to manage PHP dependencies. After cloning the repository or downloading a source code tarball, running `composer install` will download all the required dependencies, and will advise if any PHP extensions need to be installed. If not installing as a programming environment, running `composer install -o --no-dev --no-scripts` is recommended.
# Repository structure
@ -34,13 +34,15 @@ Also necessary to the functioning of the application is the `/vendor/` directory
The `/locale/` and `/sql/` directories contain human-language files and database schemata, both of which are occasionally used by the application in the course of execution. The `/www/` directory serves as a document root for a few static files to be made available to users by a Web server.
The `/dist/` directory, on the other hand, contains samples of configuration for Web servers and init systems. These are not used by The Arsse itself, but are merely distributed with it for reference.
The `/dist/` directory, on the other hand, contains general and system-specific build files, and samples of configuration for Web servers and other system integration. These are not used by The Arsse itself, but are used during the process of preparing new releases for supported operating systems.
## Documentation
The source text for The Arsse's manual can be found in `/docs/`, with pages written in [Markdown](https://spec.commonmark.org/current/) and converted to HTML [with Daux](#building-the-manual). If a static manual is generated its files will appear under `/manual/`.
In addition to the manual the files `/README.md` (this file), `/CHANGELOG`, `/UPGRADING`, `/LICENSE`, and `/AUTHORS` also document various things about the software, rather than the software itself.
The Arsse also has a UNIX manual page, also written in Markdown, which can be found under `/manpages/`. [Pandoc](https://pandoc.org/) is needed to convert it to the appropriate format, with the results stored under `/dist/man/`.
In addition to the manuals the files `/README.md` (this file), `/CHANGELOG`, `/UPGRADING`, `/LICENSE`, and `/AUTHORS` also document various things about the software, rather than the software itself.
## Tests
@ -50,7 +52,7 @@ The `/tests/` directory contains everything related to automated testing. It is
|--------------------|------------------------------------------------------------------------------------|
| `cases/` | The test cases themselves, organized in roughly the same structure as the code |
| `coverage/` | (optional) Generated code coverage reports |
| `docroot/` | Sample documents used in some tests, to be returned by the PHP's basic HTTP server |
| `docroot/` | Sample documents used in some tests, to be returned by PHP's basic HTTP server |
| `lib/` | Supporting classes which do not contain test cases |
| `bootstrap.php` | Bootstrap script, equivalent to `/arsse.php`, but for tests |
| `phpunit.dist.xml` | PHPUnit configuration file |
@ -74,7 +76,7 @@ The `/vendor-bin/` directory houses the files needed for the tools used in The A
| `/robo` | Simple wrapper for executing Robo on POSIX systems |
| `/robo.bat` | Simple wrapper for executing Robo on Windows |
In addition the files `/package.json`, `/yarn.lock`, and `/postcss.config.js` as well as the `/node_modules/` directory are used by [Yarn](https://yarnpkg.com/) and [PostCSS](https://postcss.org/) when modifying the stylesheet for The Arsse's manual.
In addition the files `/package.json` and `/postcss.config.js` as well as the `/node_modules/` directory are used by [Yarn](https://yarnpkg.com/) and [PostCSS](https://postcss.org/) when modifying the stylesheet for The Arsse's manual.
# Common tasks
@ -105,15 +107,20 @@ The Arsse's user manual, made using [Daux](https://daux.io/), can be compiled by
The manual employs a custom theme derived from the standard Daux theme. If the standard Daux theme receives improvements, the custom theme can be rebuilt by running `./robo manual:theme`. This requires that [NodeJS](https://nodejs.org) and [Yarn](https://yarnpkg.com/) be installed, but JavaScript tools are not required to modify The Arsse itself, nor the content of the manual.
## Building the man page
The Arsse's UNIX manual page is authored in Markdown, and must be converted to the native roff format using [Pandoc](https://pandoc.org/). This can be done by running `./robo manpage`, which will output appropriate files to `/dist/man/`. The conversion should not be done manually as there is post-processing required for optimal output.
## Packaging a release
Producing a release package is done by running `./robo package`. This performs the following operations:
- Duplicates a working tree with the commit (usually a release tag) to package
- Generates the manual
- Generates UNIX manual pages with Pandoc
- Generates the HTML manual
- Installs runtime Composer dependencies with an optimized autoloader
- Deletes numerous unneeded files
- Exports the default configuration of The Arsse to a file
- Compresses the remaining files into a tarball
Due to the first step, [Git](https://git-scm.com/) is required to package a release.
Due to the first two steps, [Git](https://git-scm.com/) and [Pandoc](https://pandoc.org/) are required in PATH to package a release.

67
RoboFile.php

@ -1,5 +1,6 @@
<?php
use Robo\Collection\CollectionBuilder;
use Robo\Result;
const BASE = __DIR__.\DIRECTORY_SEPARATOR;
@ -173,19 +174,19 @@ class RoboFile extends \Robo\Tasks {
$archVersion = preg_replace('/^([^-]+)-(\d+)-(\w+)$/', "$1.r$2.$3", $version);
// name the generic release tarball
$tarball = "arsse-$version.tar.gz";
// generate the Debian changelog; this also validates our original changelog
$debianChangelog = $this->changelogDebian($this->changelogParse(file_get_contents($dir."CHANGELOG"), $version), $version);
// save commit description to VERSION file for use by packaging
// save commit description to VERSION file for reference
$t->addTask($this->taskWriteToFile($dir."VERSION")->text($version));
// save the Debian changelog
$t->addTask($this->taskWriteToFile($dir."dist/debian/changelog")->text($debianChangelog));
// patch the Arch PKGBUILD file with the correct version string
$t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^pkgver=.*$/m')->to("pkgver=$archVersion"));
// patch the Arch PKGBUILD file with the correct source file
$t->addTask($this->taskReplaceInFile($dir."dist/arch/PKGBUILD")->regex('/^source=\("arsse-[^"]+"\)$/m')->to('source=("'.basename($tarball).'")'));
// Prepare Debian-related files
$this->prepDebian($t, $dir, $version);
// perform Composer installation in the temp location with dev dependencies
$t->addTask($this->taskComposerInstall()->arg("-q")->dir($dir));
// generate the manual
// generate manpages
$t->addTask($this->taskExec("./robo manpage")->dir($dir));
// generate the HTML manual
$t->addTask($this->taskExec("./robo manual -q")->dir($dir));
// perform Composer installation in the temp location for final output
$t->addTask($this->taskComposerInstall()->dir($dir)->noDev()->optimizeAutoloader()->arg("--no-scripts")->arg("-q"));
@ -194,6 +195,7 @@ class RoboFile extends \Robo\Tasks {
$dir.".git",
$dir.".gitignore",
$dir.".gitattributes",
$dir."dist/debian/.gitignore",
$dir."composer.json",
$dir."composer.lock",
$dir.".php_cs.dist",
@ -202,6 +204,7 @@ class RoboFile extends \Robo\Tasks {
$dir."RoboFile.php",
$dir."CONTRIBUTING.md",
$dir."docs",
$dir."manpages",
$dir."tests",
$dir."vendor-bin",
$dir."vendor/bin",
@ -211,6 +214,16 @@ class RoboFile extends \Robo\Tasks {
$dir."yarn.lock",
$dir."postcss.config.js",
]));
$t->addCode(function() use ($dir) {
// Remove files which lintian complains about; they're otherwise harmless
$files = [];
foreach (new \CallbackFilterIterator(new \RecursiveIteratorIterator(new \RecursiveDirectoryIterator($dir."vendor", \FilesystemIterator::CURRENT_AS_PATHNAME | \FilesystemIterator::SKIP_DOTS)), function($v, $k, $i) {
return preg_match('/\/\.git(?:ignore|attributes|modules)$/', $v);
}) as $f) {
$files[] = $f;
}
return $this->taskFilesystemStack()->remove($files)->run();
});
// generate a sample configuration file
$t->addTask($this->taskExec(escapeshellarg(\PHP_BINARY)." arsse.php conf save-defaults config.defaults.php")->dir($dir));
// remove any existing archive
@ -254,7 +267,7 @@ class RoboFile extends \Robo\Tasks {
}
// start a task collection and create a temporary directory
$t = $this->collectionBuilder();
$dir = $t->tmpDir().\DIRECTORY_SEPARATOR;
$dir = $t->workDir(BASE."temp").\DIRECTORY_SEPARATOR;
$base = $dir."arsse-$version".\DIRECTORY_SEPARATOR;
// start by extracting the tarball
$t->addCode(function() use ($tarball, $dir, $base) {
@ -266,7 +279,7 @@ class RoboFile extends \Robo\Tasks {
$t->addTask($this->taskPack($dir."arsse_$version.orig.tar.gz")->addDir("arsse-$version", $base));
// copy Debian files to lower down in the tree
$t->addTask($this->taskFilesystemStack()->mirror($base."dist/debian", $base."debian"));
$t->addTask($this->taskExec("deber")->dir($dir));
//$t->addTask($this->taskExec("deber")->dir($base));
return $t->run();
}
@ -314,6 +327,26 @@ class RoboFile extends \Robo\Tasks {
return $t->run();
}
/** Generates the "arsse" command's manual page (UNIX man page)
*
* This requires that the Pandoc document converter be installed and
* available in $PATH.
*/
public function manpage(): Result {
$t = $this->collectionBuilder();
$man = [
'en' => "man1/arsse.1",
];
foreach($man as $src => $out) {
$src = BASE."manpages/$src.md";
$out = BASE."dist/man/$out";
$t->addTask($this->taskFilesystemStack()->mkdir(dirname($out), 0755));
$t->addTask($this->taskExec("pandoc -s -f markdown-smart -t man -o ".escapeshellarg($out)." ".escapeshellarg($src)));
$t->addTask($this->taskReplaceInFile($out)->regex('/\.\n(?!\.)/s')->to(". "));
}
return $t->run();
}
protected function changelogParse(string $text, string $targetVersion): array {
$lines = preg_split('/\r?\n/', $text);
$version = "";
@ -429,4 +462,22 @@ class RoboFile extends \Robo\Tasks {
}
return $out;
}
protected function prepDebian(CollectionBuilder $t, string $dir, string $version): void {
// generate the Debian changelog; this also validates our original changelog
$debianChangelog = $this->changelogDebian($this->changelogParse(file_get_contents($dir."CHANGELOG"), $version), $version);
// save the Debian changelog
$t->addTask($this->taskWriteToFile($dir."dist/debian/changelog")->text($debianChangelog));
// adapt the systemd unit for Debian: this involves using only the "arsse-fetch" unit (renamed to "arsse"), removing the "PartOf" directive, and changing the user and group to "www-data"
$t->addTask($this->taskFilesystemStack()->copy($dir."dist/systemd/arsse-fetch.service", $dir."dist/debian/arsse.service"));
$t->addTask($this->taskReplaceInFile($dir."/dist/debian/arsse.service")->regex('/^PartOf=.*$/m')->to(""));
$t->addTask($this->taskReplaceInFile($dir."/dist/debian/arsse.service")->regex('/^(User|Group)=.*$/m')->to("$1=www-data"));
// change the user and group references in tmpfiles
$t->addTask($this->taskFilesystemStack()->copy($dir."dist/tmpfiles.conf", $dir."dist/debian/arsse.tmpfiles"));
$t->addTask($this->taskReplaceInFile($dir."dist/debian/arsse.tmpfiles")->regex('/(?<= )arsse(?= )/')->to("www-data"));
// change the user reference in the executable file
$t->addTask($this->taskFilesystemStack()->mkdir($dir."dist/debian/bin"));
$t->addTask($this->taskFilesystemStack()->copy($dir."dist/arsse", $dir."dist/debian/bin/arsse"));
$t->addTask($this->taskReplaceInFile($dir."dist/debian/bin/arsse")->from('posix_getpwnam("arsse"')->to('posix_getpwnam("www-data"'));
}
}

7
dist/arch/PKGBUILD

@ -32,8 +32,8 @@ package() {
depends=("php>=7.1" "php-intl>=7.1" "php-sqlite>=7.1" "php-fpm>=7.1")
# create most directories necessary for the final package
cd "$pkgdir"
mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "etc/php/php-fpm.d/" "etc/webapps/arsse" "etc/webapps/arsse/nginx"
#copy requisite files
mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "etc/php/php-fpm.d" "etc/webapps/arsse"
# copy requisite files
cd "$srcdir/arsse"
cp -r lib locale sql vendor www CHANGELOG UPGRADING README.md arsse.php "$pkgdir/usr/share/webapps/arsse"
cp -r manual/* "$pkgdir/usr/share/doc/arsse"
@ -42,12 +42,13 @@ package() {
cp dist/sysuser.conf "$pkgdir/usr/lib/sysusers.d/arsse.conf"
cp dist/tmpfiles.conf "$pkgdir/usr/lib/tmpfiles.d/arsse.conf"
cp dist/php-fpm.conf "$pkgdir/etc/php/php-fpm.d/arsse.conf"
cp -r dist/man "$pkgdir/usr/share"
cp -r dist/nginx dist/apache config.defaults.php "$pkgdir/etc/webapps/arsse"
cd "$pkgdir"
# copy files requiring special permissions
cd "$srcdir/arsse"
install -Dm755 dist/arsse "$pkgdir/usr/bin/arsse"
install -Dm640 dist/arch/config.php "$pkgdir/etc/webapps/arsse"
install -Dm640 dist/config.php "$pkgdir/etc/webapps/arsse"
# patch generic configuration files to use Arch-specific paths and identifiers
sed -i -se 's/\/\(etc\|usr\/share\)\/arsse\//\/\1\/webapps\/arsse\//g' "$pkgdir/etc/webapps/arsse/nginx/"* "$pkgdir/etc/webapps/arsse/apache/"* "$pkgdir/usr/lib/tmpfiles.d/arsse.conf" "$pkgdir/usr/lib/systemd/system/"* "$pkgdir/usr/bin/"*
sed -i -se 's/\/var\/run\/php\//\/run\/php-fpm\//g' "$pkgdir/etc/webapps/arsse/nginx/"* "$pkgdir/etc/webapps/arsse/apache/"* "$pkgdir/etc/php/php-fpm.d/arsse.conf"

8
dist/arch/PKGBUILD-git

@ -37,6 +37,7 @@ pkgver() {
build() {
cd "$srcdir/arsse"
composer install
./robo manpage
./robo manual
composer install --no-dev -o --no-scripts
php arsse.php conf save-defaults config.defaults.php
@ -48,8 +49,8 @@ package() {
depends=("php>=7.1" "php-intl>=7.1" "php-sqlite>=7.1" "php-fpm>=7.1")
# create most directories necessary for the final package
cd "$pkgdir"
mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "etc/php/php-fpm.d/" "etc/webapps/arsse" "etc/webapps/arsse/nginx"
#copy requisite files
mkdir -p "usr/share/webapps/arsse" "usr/share/doc/arsse" "usr/share/licenses/arsse" "usr/lib/systemd/system" "usr/lib/sysusers.d" "usr/lib/tmpfiles.d" "etc/php/php-fpm.d" "etc/webapps/arsse"
# copy requisite files
cd "$srcdir/arsse"
cp -r lib locale sql vendor www CHANGELOG UPGRADING README.md arsse.php "$pkgdir/usr/share/webapps/arsse"
cp -r manual/* "$pkgdir/usr/share/doc/arsse"
@ -58,12 +59,13 @@ package() {
cp dist/sysuser.conf "$pkgdir/usr/lib/sysusers.d/arsse.conf"
cp dist/tmpfiles.conf "$pkgdir/usr/lib/tmpfiles.d/arsse.conf"
cp dist/php-fpm.conf "$pkgdir/etc/php/php-fpm.d/arsse.conf"
cp -r dist/man "$pkgdir/usr/share"
cp -r dist/nginx dist/apache config.defaults.php "$pkgdir/etc/webapps/arsse"
cd "$pkgdir"
# copy files requiring special permissions
cd "$srcdir/arsse"
install -Dm755 dist/arsse "$pkgdir/usr/bin/arsse"
install -Dm640 dist/arch/config.php "$pkgdir/etc/webapps/arsse"
install -Dm640 dist/config.php "$pkgdir/etc/webapps/arsse"
# patch generic configuration files to use Arch-specific paths and identifiers
sed -i -se 's/\/\(etc\|usr\/share\)\/arsse\//\/\1\/webapps\/arsse\//g' "$pkgdir/etc/webapps/arsse/nginx/"* "$pkgdir/etc/webapps/arsse/apache/"* "$pkgdir/usr/lib/tmpfiles.d/arsse.conf" "$pkgdir/usr/lib/systemd/system/"* "$pkgdir/usr/bin/"*
sed -i -se 's/\/var\/run\/php\//\/run\/php-fpm\//g' "$pkgdir/etc/webapps/arsse/nginx/"* "$pkgdir/etc/webapps/arsse/apache/"* "$pkgdir/etc/php/php-fpm.d/arsse.conf"

2
dist/arsse

@ -1,4 +1,4 @@
#! /usr/bin/php
#! /usr/bin/env php
<?php
if (posix_geteuid() == 0) {
$info = posix_getpwnam("arsse");

0
dist/arch/config.php → dist/config.php

13
dist/debian/.gitignore

@ -0,0 +1,13 @@
*
!.gitignore
!arsse.install
!compat
!control
!copyright
!lintian-overrides
!rules
!source/
source/*
!source/lintian-overrides
!source/format

17
dist/debian/arsse.install

@ -0,0 +1,17 @@
lib usr/share/arsse/
locale usr/share/arsse/
sql usr/share/arsse/
vendor usr/share/arsse/
www usr/share/arsse/
CHANGELOG usr/share/arsse/
UPGRADING usr/share/arsse/
README.md usr/share/arsse/
arsse.php usr/share/arsse/
dist/debian/bin/arsse usr/bin/
manual usr/share/doc/arsse/
dist/man/* usr/share/man/
dist/nginx etc/arsse/
dist/apache etc/arsse/
dist/config.php etc/arsse
config.defaults.php etc/arsse/

8
dist/debian/control

@ -6,6 +6,7 @@ Standards-Version: 4.5.1
Homepage: https://thearsse.com/
Vcs-Browser: https://code.mensbeam.com/MensBeam/arsse/
Vcs-Git: https://code.mensbeam.com/MensBeam/arsse/
Build-Depends: debhelper
Package: arsse
Architecture: all
@ -17,16 +18,15 @@ Description: Multi-protocol RSS/Atom newsfeed synchronization server
client protocols such as Tiny Tiny RSS, Nextcloud News and Miniflux,
allowing you to use compatible clients for many protocols with a single
server.
Build-Depends: debhelper
Depends: ${misc:Depends},
dbconfig-mysql | dbconfig-pgsql | dbconfig-sqlite3 | dbconfig-no-thanks,
dbconfig-sqlite3 | dbconfig-pgsql | dbconfig-no-thanks,
php (>= 7.1.0),
php-cli,
php-intl,
php-json,
php-xml,
php-sqlite3 | php-mysql | php-pgsql
Recommends: apache2 | nginx,
php-sqlite3 | php-pgsql
Recommends: nginx | apache2,
php-fpm,
php-curl,
ca-certificates

4
dist/debian/lintian-overrides

@ -0,0 +1,4 @@
# We make reference to "Tiny Tiny RSS"
spelling-error-in-description Tiny Tiny (duplicate word) Tiny
# The manual for DrUUID (a dependency) includes a harmless "up" link
privacy-breach-generic usr/share/arsse/vendor/jkingweb/druuid/documentation/manual.html [<link rel="up" href="http://jkingweb.ca/code/">] (http://jkingweb.ca/code/)

1
dist/debian/rules

@ -4,4 +4,3 @@ DH_VERBOSE = 1
%:
dh $@

2
dist/debian/source/lintian-overrides

@ -0,0 +1,2 @@
# Development environment is slightly out of date
newer-standards-version

2
dist/systemd/arsse-fetch.service

@ -33,4 +33,4 @@ RestartPreventStatus=
#ReadOnlyPaths=/
#ReadWriePaths=/var/lib/arsse
#NoExecPaths=/
#ExecPaths=/usr/bin/php /usr/bin/php7
#ExecPaths=/usr/bin/php

7
dist/tmpfiles.conf

@ -1,3 +1,4 @@
z /usr/bin/arsse 0755 root arsse - -
z /etc/arsse/config.php 0640 root arsse - -
L /usr/share/arsse/config.php - root arsse - /etc/arsse/config.php
z /usr/bin/arsse 0755 root arsse - -
z /etc/arsse/config.php 0640 root arsse - -
L /usr/share/arsse/config.php - root arsse - /etc/arsse/config.php
d /var/lib/arsse 0750 arsse arsse - -

1
docs/en/020_Getting_Started/020_Download_and_Installation/020_On_Debian_and_Ubuntu.md

@ -35,6 +35,7 @@ sudo mv sysusers.conf /etc/sysusers.d/arsse.conf
sudo mv tmpfiles.conf /etc/tmpfiles.d/arsse.conf
sudo mv config.php nginx apache /etc/arsse/
sudo mv php-fpm.conf /etc/php/$php_ver/fpm/pool.d/arsse.conf
sudo mv man/man1/* /usr/shame/man/man1/
# Move the administration executable
sudo mv arsse /usr/bin/
```

2
docs/en/025_Using_The_Arsse/index.md

@ -2,7 +2,7 @@
This section details a few administrative tasks which may need to be performed after installing The Arsse. As no Web-based administrative interface is included, these tasks are generally performed via command line interface.
Though this section describes some commands briefly, complete documentation of The Arsse's command line interface is not included in this manual. Documentation for CLI commands can instead be viewed with the CLI itself by executing `arsse --help`.
Though this section describes some commands briefly, complete documentation of The Arsse's command line interface is not included in this manual. Documentation for CLI commands can instead be viewed using the system manual service by executing `man arsse`.
# A Note on Command Invocation

211
lib/CLI.php

@ -13,223 +13,34 @@ use JKingWeb\Arsse\REST\Miniflux\Token as Miniflux;
class CLI {
public const USAGE = <<<USAGE_TEXT
Usage:
arsse.php daemon
arsse.php feed refresh-all
arsse.php feed refresh <n>
arsse.php conf save-defaults [<file>]
arsse.php user [list]
arsse.php user add <username> [<password>] [--admin]
arsse.php user remove <username>
arsse.php user show <username>
arsse.php user set <username> <property> <value>
arsse.php user unset <username> <property>
arsse.php user set-pass <username> [<password>]
[--oldpass=<pass>] [--fever]
arsse.php user unset-pass <username>
[--oldpass=<pass>] [--fever]
arsse.php user set-pass <username> [<password>] [--fever]
arsse.php user unset-pass <username> [--fever]
arsse.php user auth <username> <password> [--fever]
arsse.php token list <username>
arsse.php token create <username> [<label>]
arsse.php token revoke <username> [<token>]
arsse.php import <username> [<file>]
[-f | --flat] [-r | --replace]
arsse.php export <username> [<file>]
[-f | --flat]
arsse.php import <username> [<file>] [-f|--flat] [-r|--replace]
arsse.php export <username> [<file>] [-f|--flat]
arsse.php daemon
arsse.php feed refresh-all
arsse.php feed refresh <n>
arsse.php conf save-defaults [<file>]
arsse.php --version
arsse.php -h | --help
arsse.php -h|--help
The Arsse command-line interface can be used to perform various administrative
tasks such as starting the newsfeed refresh service, managing users, and
importing or exporting data.
Commands:
daemon
Starts the newsfeed refreshing service, which will refresh stale feeds at
the configured interval automatically.
feed refresh-all
Refreshes any stale feeds once, then exits. This performs the same
function as the daemon command without looping; this is useful if use of
a scheduler such a cron is preferred over a persitent service.
feed refresh <n>
Refreshes a single feed by numeric ID. This is principally for internal
use as the feed ID numbers are not usually exposed to the user.
conf save-defaults [<file>]
Prints default configuration parameters to standard output, or to <file>
if specified. Each parameter is annotated with a short description of its
purpose and usage.
user [list]
Prints a list of all existing users, one per line.
user add <username> [<password>] [--admin]
Adds the user specified by <username>, with the provided password
<password>. If no password is specified, a random password will be
generated and printed to standard output. The --admin option will make
the user an administrator, which allows them to manage users via the
Miniflux protocol, among other things.
user remove <username>
Removes the user specified by <username>. Data related to the user,
including folders and subscriptions, are immediately deleted. Feeds to
which the user was subscribed will be retained and refreshed until the
configured retention time elapses.
user show <username>
Displays the metadata of a user in a basic tabular format. See below for
details on the various properties displayed.
user set <username> <property> <value>
Sets a user's metadata property to the supplied value. See below for
details on the various properties available.
user unset <username> <property>
Sets a user's metadata property to its default value. See below for
details on the various properties available. What the default value
for a property evaluates to depends on which protocol is used.
user set-pass <username> [<password>]
Changes <username>'s password to <password>. If no password is specified,
a random password will be generated and printed to standard output.
The --oldpass=<pass> option can be used to supply a user's exiting
password if this is required by the authentication driver to change a
password. Currently this is not used by any existing driver.
The --fever option sets a user's Fever protocol password instead of their
general password. As Fever requires that passwords be stored insecurely,
users do not have Fever passwords by default, and logging in to the Fever
protocol is disabled until a password is set. It is highly recommended
that a user's Fever password be different from their general password.
user unset-pass <username>
Unsets a user's password, effectively disabling their account. As with
password setting, the --oldpass and --fever options may be used.
user auth <username> <password>
Tests logging in as <username> with password <password>. This only checks
that the user's password is correctly recognized; it has no side effects.
The --fever option may be used to test the user's Fever protocol password,
if any.
token list <username>
Lists available tokens for <username> in a simple tabular format. These
tokens act as an alternative means of authentication for the Miniflux
protocol and may be required by some clients. They do not expire.
token create <username> [<label>]
Creates a new login token for <username> and prints it. These tokens act
as an alternative means of authentication for the Miniflux protocol and
may be required by some clients. An optional label may be specified to
give the token a meaningful name.
token revoke <username> [<token>]
Deletes the specified token from the database. The token itself must be
supplied, not its label. If it is omitted all tokens are revoked.
import <username> [<file>]
Imports the feeds, folders, and tags found in the OPML formatted <file>
into the account of <username>. If no file is specified, data is instead
read from standard input.
The --replace option interprets the OPML file as the list of all desired
feeds, folders and tags, performing any deletion or moving of existing
entries which do not appear in the flle. If this option is not specified,
the file is assumed to list desired additions only.
The --flat option can be used to ignore any folder structures in the file,
importing any feeds only into the root folder.
export <username> [<file>]
Exports <username>'s feeds, folders, and tags to the OPML file specified
by <file>, or standard output if none is provided. Note that due to a
limitation of the OPML format, any commas present in tag names will not be
retained in the export.
The --flat option can be used to omit folders from the export. Some OPML
implementations may not support folders, or arbitrary nesting; this option
may be used when planning to import into such software.
User metadata:
User metadata are primarily used by the Miniflux protocol, and most
properties have identical or similar names to those used by Miniflux.
Properties may also affect other protocols, or conversely may have no
effect even when using the Miniflux protocol; this is noted below when
appropriate.
Booleans accept any of the values true/false, 1/0, yes/no, on/off.
The following metadata properties exist for each user:
See the manual page for more details:
num
Integer. The numeric identifier of the user. This is assigned at user
creation and is read-only.
admin
Boolean. Whether the user is an administrator. Administrators may
manage other users via the Miniflux protocol, and also may trigger
feed updates manually via the Nextcloud News protocol.
lang
String. The preferred language of the user, as a BCP 47 language tag
e.g. "en-ca". Note that since The Arsse currently only includes
English text it is not used by The Arsse itself, but clients may
use this metadatum in protocols which expose it.
tz
String. The time zone of the user, as a tzdata identifier e.g.
"America/Los_Angeles".
root_folder_name
String. The name of the root folder, in protocols which allow it to
be renamed.
sort_asc
Boolean. Whether the user prefers ascending sort order for articles.
Descending order is usually the default, but explicitly setting this
property false will also make a preference for descending order
explicit.
theme
String. The user's preferred theme. This is not used by The Arsse
itself, but clients may use this metadatum in protocols which expose
it.
page_size
Integer. The user's preferred page size when listing articles. This is
not used by The Arsse itself, but clients may use this metadatum in
protocols which expose it.
shortcuts
Boolean. Whether to enable keyboard shortcuts. This is not used by
The Arsse itself, but clients may use this metadatum in protocols which
expose it.
gestures
Boolean. Whether to enable touch gestures. This is not used by
The Arsse itself, but clients may use this metadatum in protocols which
expose it.
reading_time
Boolean. Whether to calculate and display the estimated reading time
for articles. Currently The Arsse does not calculate reading time, so
changing this will likely have no effect.
stylesheet
String. A user CSS stylesheet. This is not used by The Arsse itself,
but clients may use this metadatum in protocols which expose it.
man 1 arsse
USAGE_TEXT;
protected function usage($prog): string {

224
manpages/en.md

@ -0,0 +1,224 @@
---
title: "ARSSE"
section: 1
date: 2021-05-30
footer: "arsse 0.9.3"
header: "User Commands"
---
# NAME
arsse - manage an instance of The Advanced RSS Environment (The Arsse)
# SYNOPSIS
**arsse** user [list]\
**arsse** user add <_username_> [<_password_>] [--admin]\
**arsse** user remove <_username_>\
**arsse** user show <_username_>\
**arsse** user set <_username_> <_property_> <_value_>\
**arsse** user unset <_username_> <_property_>\
**arsse** user set-pass <_username_> [<_password_>] [--fever]\
**arsse** user unset-pass <_username_> [--fever]\
**arsse** user auth <_username_> <_password_> [--fever]\
**arsse** token list <_username_>\
**arsse** token create <_username_> [<_label_>]\
**arsse** token revoke <_username_> [<_token_>]\
**arsse** import <_username_> [<_file_>] [-f|--flat] [-r|--replace]\
**arsse** export <_username_> [<_file_>] [-f|--flat]\
**arsse** daemon\
**arsse** feed refresh-all\
**arsse** feed refresh <_n_>\
**arsse** conf save-defaults [<_file_>]\
**arsse** --version\
**arsse** -h|--help
# DESCRIPTION
**arsse** allows a sufficiently privileged user to perform various administrative operations related to The Arsse, including:
- Adding and removing users and managing their metadata
- Managing passwords and authentication tokens
- Importing and exporting OPML newsfeed-lists
These are documented in the next section **PRIMARY COMMANDS**. Further, seldom-used commands are documented in the following section **ADDITIONAL COMMANDS**.
# PRIMARY COMMANDS
## Managing users and metadata
**arsse user [list]**
: Displays a simple list of user names with one entry per line
**arsse user add** <_username_> [<_password_>] [--admin]
: Adds a new user to the database with the specified username and password. If <_password_> is omitted a random password will be generated and printed.
The **--admin** flag may be used to mark the user as an administrator. This has no meaning within the context of The Arsse as a whole, but it is used control access to certain features in the Miniflux and Nextcloud News protocols.
**arsse user remove** <_username_>
: Immediately removes a user from the database. All associated data (folders, subscriptions, etc.) are also removed.
**arsse user show** <_username_>
: Displays a table of metadata properties and their assigned values for <_username_>. These properties are primarily used by the Miniflux protocol. Consult the section **USER METADATA** for details.
**arsse user set** <_username_> <_property_> <_value_>
: Sets a metadata property for a user. These properties are primarily used by the Miniflux protocol. Consult the section **USER METADATA** for details.
**arsse user unset** <_username_> <_property_>
: Clears a metadata property for a user. The property is thereafter set to its default value, which is protocol-dependent.
## Managing passwords and authentication tokens
**arsse user set-pass** <_username_> [<_password_>] [--fever]
: Changes a user's password to the specified value. If no password is specified, a random password will be generated and printed.
The **--fever** option sets a user's Fever protocol password instead of their general password. As the Fever protocol requires that passwords be stored insecurely, users do not have Fever passwords by default, and logging in to the Fever protocol is disabled until a suitable password is set. It is highly recommended that a user's Fever password be different from their general password.
**arsse user unset-pass** <_username_> [--fever]
: Unsets a user's password, effectively disabling their account. As with password setting, the **--fever** option may be used to operate on a user's Fever password instead of their general password.
**arsse user auth** <_username_> <_password_> [--fever]
: Tests logging a user in. This only checks that the user's password is correctly recognized; it has no side effects.
The **--fever** option may be used to test the user's Fever protocol password, if any.
**arsse token list** <_username_>
: Displays a user's authentication tokens in a simple tabular format. These tokens act as an alternative means of authentication for the Miniflux protocol and may be required by some clients. They do not expire.
**arsse token create** <_username_> [<_label_>]
: Creates a new random login token and prints it. These tokens act as an alternative means of authentication for the Miniflux protocol and may be required by some clients. An optional <_label_> may be specified to give the token a meaningful name.
**arsse token revoke** <_username_> [<_token_>]
: Deletes the specified token from the database. The token itself must be supplied, not its label. If it is omitted all tokens are revoked.
## Importing and exporting data
**arsse import** <_username_> [<_file_>] [-r|--replace] [-f|--flat]
: Imports the newsfeeds, folders, and tags found in the OPML formatted <_file_> into the account of the specified user. If no file is specified, data is instead read from standard input. Import operations are atomic: if any of the newsfeeds listed in the input cannot be retrieved, the entire import operation will fail.
The **--replace** (or **-r**) option interprets the OPML file as the list of **all** desired newsfeeds, folders and tags, performing any deletion or moving of existing entries which do not appear in the flle. If this option is not specified, the file is assumed to list desired **additions** only.
The **--flat** (or **-f**) option can be used to ignore any folder structures in the file, importing any newsfeeds directly into the root folder. Combining this with the **--replace** option is possible.
**arsse export** <_username_> [<_file_>] [-f|--flat]
: Exports a user's newsfeeds, folders, and tags to the OPML file specified by <_file_>, or standard output if no file is specified. Note that due to a limitation of the OPML format, any commas present in tag names will not be retained in the export.
The **--flat** (or **-f**) option can be used to omit folders from the export. Some OPML implementations may not support folders, or arbitrary nesting; this option may be used when planning to import into such software.
# ADDITIONAL COMMANDS
**arsse daemon**
: Starts the newsfeed fetching service. Normally this command is only invoked by systemd.
**arsse feed refresh-all**
: Performs a one-time fetch of all stale feeds. This command can be used as the basis of a **cron** job to keep newsfeeds up-to-date.
**arsse feed refresh** <_n_>
: Performs a one-time fetch of the feed (not subscription) identified by integer <_n_>. This is used internally by the fetching service and should not normally be needed.
**arsse conf save-defaults** [<_file_>]
: Prints default configuration parameters to standard output, or to <_file_> if specified. Each parameter is annotated with a short description of its purpose and usage.
# USER METADATA
User metadata are primarily used by the Miniflux protocol, and most properties have identical or similar names to those used by Miniflux. Properties may also affect other protocols, or conversely may have no effect even when using the Miniflux protocol; this is noted below when appropriate.
Booleans accept any of the values **true**/**false**, **1**/**0**, **yes**/**no**, or **on**/**off**.
The following metadata properties exist for each user:
**num**
: Integer. The numeric identifier of the user. This is assigned at user creation and is read-only.
**admin**
: Boolean. Whether the user is an administrator. Administrators may manage other users via the Miniflux protocol, and also may trigger feed updates manually via the Nextcloud News protocol.
**lang**
: String. The preferred language of the user, as a BCP 47 language tag e.g. "en-ca". Note that since The Arsse currently only includes English text it is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
**tz**
: String. The time zone of the user, as a tzdata identifier e.g. "America/Los_Angeles".
**root_folder_name**
: String. The name of the root folder, in protocols which allow it to be renamed.
**sort_asc**
: Boolean. Whether the user prefers ascending sort order for articles. Descending order is usually the default, but explicitly setting this property false will also make a preference for descending order explicit.
**theme**
: String. The user's preferred theme. This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
**page_size**
: Integer. The user's preferred page size when listing articles. This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
**shortcuts**
: Boolean. Whether to enable keyboard shortcuts. This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
**gestures**
: Boolean. Whether to enable touch gestures. This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
**reading_time**
: Boolean. Whether to calculate and display the estimated reading time for articles. Currently The Arsse does not calculate reading time, so changing this will likely have no effect.
**stylesheet**
: String. A user CSS stylesheet. This is not used by The Arsse itself, but clients may use this metadatum in protocols which expose it.
# EXAMPLES
- Add an administrator to the database with an explicit password
$ arsse user add --admin alice "Curiouser and curiouser!"
- Add a regular user to the database with a random password
$ arsse user add "Bob the Builder"
bLS!$_UUZ!iN2i_!^IC6
- Make Bob the Builder an administrator
$ arsse user set "Bob the Builder" admin true
- Disable Alice's account by clearing her password
$ arsse user unset-pass alice
- Move all of Foobar's newsfeeds to the root folder
$ arsse export foobar -f | arsse import -r foobar
- Fail to log in as Alice
$ arsse user auth alice "Oh, dear!"
Authentication failed
$ echo $?
1
# REPORTING BUGS
Any bugs found in The Arsse may be reported on the Web at [https://code.mensbeam.com/MensBeam/arsse](). Reports may also be directed to the authors (below) by e-mail.
# AUTHORS
J. King\
[https://jkingweb.ca/]()
Dustin Wilson\
[https://dustinwilson.com/]()
Loading…
Cancel
Save