✏️ Guide for selfoss RSS reader

DjCrays · Sep 24, 2018 · aeccd17 · aeccd17
1 parent 1ba5e95
commit aeccd17
Show file tree

Hide file tree

Showing 2 changed files with 170 additions and 0 deletions.
diff --git a/source/_static/images/selfoss.png b/source/_static/images/selfoss.png
diff --git a/source/guide_selfoss.rst b/source/guide_selfoss.rst
@@ -0,0 +1,170 @@
+.. highlight:: console
+
+.. author:: Nico Graf <hallo@uberspace.de>
+
+.. sidebar:: About
+
+  .. image:: _static/images/selfoss.png
+      :align: center
+
+#######
+selfoss
+#######
+
+selfoss_ is a free and open source web-based news feed reader and
+aggregator.
+
+----
+
+.. note:: For this guide you should be familiar with the basic concepts of
+
+  * MySQL_
+  * domains_
+  * PHP_
+  * cron_
+
+License
+=======
+
+The software is licensed under GPLv3_. All relevant information can be found in the repository of the project. 
+
+Prerequisites
+=============
+
+We're using PHP_ in the stable version 7.1:
+
+::
+
+ [isabell@stardust ~]$ uberspace tools version show php
+ Using 'PHP' version: '7.1'
+ [isabell@stardust ~]$
+
+.. include:: includes/my-print-defaults.rst
+
+The domain you want to use must be set up:
+
+.. include:: includes/web-domain-list.rst
+
+Installation
+============
+
+Download and extract ZIP archive
+--------------------------------
+
+Check the selfoss_ website or `GitHub repo`_ for the `latest release`_ and copy the download link to the ZIP file. Then ``cd`` to your DocumentRoot_ and use ``wget`` to download it. Replace the URL with the one you just copied.
+
+.. code-block:: console
+ :emphasize-lines: 2
+
+ [isabell@stardust ~]$ cd /var/www/virtual/$USER/
+ [isabell@stardust isabell]$ wget https://github.com/SSilence/selfoss/releases/download/47.11/selfoss-47.11.zip
+ […]
+ Saving to: ‘selfoss-47.11.zip’
+
+ 100%[========================================================================================================================>] 2,881,068    819KB/s   in 3.7s
+ 
+ 2018-09-24 10:49:50 (766 KB/s) - ‘selfoss-47.11.zip’ saved [2881068/2881068]
+
+Unzip the archive to the ``html`` folder and then delete it. Replace the version in the file name with the one you downloaded.
+
+.. code-block:: console
+ :emphasize-lines: 1,6
+ 
+ [isabell@stardust isabell]$ unzip -d html/ selfoss-47.11.zip
+ […]
+   inflating: html/common.php
+   inflating: html/run.php
+   inflating: html/cliupdate.php
+ [isabell@stardust isabell]$ rm selfoss-47.11.zip
+ [isabell@stardust isabell]$ 
+
+Configuration
+=============
+
+Setup your database
+-------------------
+
+We recommend setting up a new database for selfoss.
+
+::
+
+ [isabell@stardust ~]$ mysql -e "CREATE DATABASE $USER_selfoss"
+
+Configuration
+-------------
+
+Copy the ``default.ini`` to ``config.ini``:
+
+::
+ 
+ [isabell@stardust isabell]$ cd html
+ [isabell@stardust html]$ cp default.ini config.ini
+ [isabell@stardust html]$ 
+
+Now edit ``config.ini`` file, change the database type to ``mysql`` and provide your MySQL credentials. 
+
+.. code-block:: ini
+ :emphasize-lines: 4,5,6
+ 
+ [globals]
+ db_type=mysql
+ db_host=localhost
+ db_database=isabell_selfoss
+ db_username=isabell
+ db_password=MySuperSecretPassword
+ db_port=3306
+
+We also recommend password protection for your installation. First, generate a random string to use as salt_.
+
+::
+ 
+ [isabell@stardust html]$ head /dev/urandom | tr -dc A-Za-z0-9 | head -c 20 ; echo ''
+
+Copy the output and set it as salt in your ``config.ini``.
+
+.. code-block:: ini
+ :emphasize-lines: 1
+ 
+ salt=FqFvsGWABfpPK6zQnVzD
+
+Save the file and visit ``https://isabell.uber.space/password`` in your browser. Replace ``isabell.uber.space`` with your domain. Use the web form to generate a hash of your password and copy the hash.
+
+Edit ``config.ini`` again and insert your user name and password hash:
+
+.. code-block:: ini
+ :emphasize-lines: 1,2
+ 
+ username=isabell
+ password=c6d064709111ff0a689f206524cec8952417b9f16121a06b4ec8c58a11b570cdb7df4d6912e49415d6c615c2961c35166f0ed98eb027425100a1ebdd55a97906
+ salt=FqFvsGWABfpPK6zQnVzD
+
+You can now log in to your installation and start adding and reading feeds.
+
+Check out the official `selfoss documentation`_ for explanation of further configuration parameters.
+
+Cron job
+========
+
+It is recommended to set up a cron job to automatically update your feeds. Edit your cron tab using the ``crontab -e`` command and insert this cron job to update every 15 minutes. Make sure to replace ``isabell.uber.space`` with your own domain.
+
+::
+ 
+ */15 * * * * curl -so /dev/null https://isabell.uber.space/update
+
+.. _MySQL: https://manual.uberspace.de/en/database-mysql.html
+.. _domains: https://manual.uberspace.de/en/web-domains.html
+.. _PHP: https://manual.uberspace.de/en/lang-php.html
+.. _cron: https://manual.uberspace.de/en/daemons-cron.html
+.. _DocumentRoot: https://manual.uberspace.de/en/web-documentroot.html
+.. _credentials: https://manual.uberspace.de/en/database-mysql.html#login-credentials
+.. _selfoss: https://selfoss.aditu.de/
+.. _latest release: https://github.com/SSilence/selfoss/releases/latest
+.. _GPLv3: https://www.gnu.org/licenses/gpl-3.0.html
+.. _salt: https://en.wikipedia.org/wiki/Salt_(cryptography)
+.. _selfoss documentation: https://selfoss.aditu.de/#configuration_params
+.. _Github repo: https://github.com/SSilence/selfoss
+----
+
+Tested with selfoss 2.18, Uberspace 7.1.12.0
+
+.. authors::