diff --git a/README.md b/README.md index 525aa513..e1586963 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ -The Advanced RSS Environment -=============================== +# The Advanced RSS Environment -The Arsse is a news aggregator server which implements [version 1.2](https://github.com/nextcloud/news/blob/master/docs/externalapi/Legacy.md) of [NextCloud News](https://github.com/nextcloud/news)'s client-server synchronization protocol. Unlike most other aggregator servers, the Arsse does not include a Web front-end (though one is planned as a separate project), and it relies on existing protocols to maximize compatibility with existing clients. +The Arsse is a news aggregator server which implements [version 1.2](https://github.com/nextcloud/news/blob/master/docs/externalapi/Legacy.md) of [NextCloud News](https://github.com/nextcloud/news)' client-server synchronization protocol. Unlike most other aggregator servers, the Arsse does not include a Web front-end (though one is planned as a separate project), and it relies on existing protocols to maximize compatibility with existing clients. At present the software should be considered in an "alpha" state: though its core subsystems are covered by unit tests and should be free of major bugs, not everything has been rigorously tested. Additionally, though the NextCloud News protocol is fully supported, many features one would expect from other similar software have yet to be implemented. Areas of future work include: @@ -10,8 +9,7 @@ At present the software should be considered in an "alpha" state: though its cor - Tools for managing users (manual insertion into the database is currently required) - Better packaging and configuration samples -Requirements ------------- +## Requirements Arsse has the following requirements: @@ -22,24 +20,49 @@ Arsse has the following requirements: - [sqlite3](http://php.net/manual/en/book.sqlite3.php) - The ability to run daemon processes on the server -Installation ------------- +## Installation -TODO: Work out how the system should be installed +At present, installation of The Arsse is rather manual. We hope to improve this in the future, but for now the steps below should help get you started. The instructions and configuration samples assume you will be using Ubuntu 16.04 (or equivalent Debian) and Nginx; we hope to expand official support for different configurations in the future as well. -If installing from the Git repository rather than a download package, you will need [Composer](https://getcomposer.org/) to fetch required PHP libraries. Once Composer is installed, dependencies may be downloaded with the following command: +### Initial setup + +1. Extract the tar archive to `/usr/share` +2. If desired, create `/usr/share/arsse/config.php` using `config.defaults.php` as a guide. The file you create only needs to contain non-default settings. The `userPreAuth` setting may be of particular interest +3. Copy `/usr/share/arsse/dist/arsse.service` to `/lib/systemd/system` +4. In a terminal, execute the following to start the feed fetching service: +``` sh +sudo systemctl enable arsse +sudo systemctl start arsse +``` + +### Configuring the Web server + +A sample configuration file for Nginx can be found in `arsse/dist/nginx.conf` + +FIXME: stub + + +## Installation from source + +If installing from the Git repository rather than a download package, you will need to follow extra steps before the instructions in the section above. + +First, you must install [Composer](https://getcomposer.org/) to fetch required PHP libraries. Once Composer is installed, dependencies may be downloaded with the following command: ``` sh php composer.phar install -o --no-dev ``` -License -------- +Second, you may wish to create an example configuration file using the following command: + +``` sh +php ./arsse.php conf save-defaults "./config.defaults.php" +``` + +## License Arsse is made available under the permissive MIT license. See the LICENSE file included with the distribution or source code for exact legal text. Dependencies included in the distribution may be governed by other licenses. -Running tests -------------- +## Running tests To run the test suite, you must have [Composer](https://getcomposer.org/) installed as well as the command-line PHP interpreter (this is normally required to use Composer). Port 8000 must also be available for use by the built-in PHP Web server. diff --git a/dist/arsse.service b/dist/arsse.service new file mode 100644 index 00000000..4abea754 --- /dev/null +++ b/dist/arsse.service @@ -0,0 +1,15 @@ +[Unit] +Description=The Arsse feed fetching service +After=network.target + +[Service] +User=www-data +Group=www-data +WorkingDirectory=/usr/share/arsse/www +Type=simple +StandardOutput=null +StandardError=syslog +ExecStart=/usr/bin/env php /usr/share/arsse/www/arsse.php daemon + +[Install] +WantedBy=multi-user.target \ No newline at end of file diff --git a/www/arsse.php b/www/arsse.php new file mode 100644 index 00000000..78c28244 --- /dev/null +++ b/www/arsse.php @@ -0,0 +1,2 @@ +