From 59e91bc8931a386974a3817e9849aad1ca7fc186 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicolas=20L=C5=93uillet?= Date: Wed, 21 Oct 2015 14:14:51 +0200 Subject: add docs --- docs/en/Administrator/hidden_options.rst | 85 +++++++++++++ docs/en/Administrator/install.rst | 200 +++++++++++++++++++++++++++++++ docs/en/Administrator/multiusers.rst | 47 ++++++++ docs/en/Administrator/sessions.rst | 26 ++++ docs/en/Administrator/update.rst | 30 +++++ 5 files changed, 388 insertions(+) create mode 100644 docs/en/Administrator/hidden_options.rst create mode 100644 docs/en/Administrator/install.rst create mode 100644 docs/en/Administrator/multiusers.rst create mode 100644 docs/en/Administrator/sessions.rst create mode 100644 docs/en/Administrator/update.rst (limited to 'docs/en/Administrator') diff --git a/docs/en/Administrator/hidden_options.rst b/docs/en/Administrator/hidden_options.rst new file mode 100644 index 00000000..5cf0b22e --- /dev/null +++ b/docs/en/Administrator/hidden_options.rst @@ -0,0 +1,85 @@ +Hidden options +============== + +Caution +------- + +**Be careful**, this section is destined to advanced users. We are going +to modify an important wallabag configuration file, +``inc/poche/config.inc.php``. It is therefore advised to do a backup of +this file before you proceed. **Any error occuring during the +modification of a wallabag file could lead to malfunctions**. + +This file is created when you install wallabag. Install wallabag, do a +backup copy of the file, then open it in your favorite text editor. + +In this file, there are some options that are not, as of now, available +in the **config** page of wallabag. + +Modification of advanced options +-------------------------------- + +Each option is defined this way: + +:: + + @define ('OPTION_NAME', 'Value'); + +For each line, you can only modify the ``Value`` field. + +Here is the list of each option you can change: + +- ``HTTP_PORT`` (default: ``80``) : the HTTP port of your web server. + You may need to change it if your server is behind a proxy. Accepted + values: number +- ``SSL_PORT`` (default: ``443``) : the HTTP port of your web server. + You may need to change it if your server use SSLH. Accepted values: + number +- ``MODE_DEMO`` (default : ``FALSE)``: If you ever wanted to set up a + demonstration server… Accepted values: ``TRUE`` or ``FALSE``. +- ``DEBUG_POCHE`` (default: ``FALSE``) : if you encounter some problems + with wallabag, we may ask you to active Debug mode. Accepted values: + ``TRUE`` or ``FALSE``. Check the logs in cache/log.txt after + activating that. +- ``ERROR_REPORTING`` (default : ``E_ALL & ~E_NOTICE``) : Set to + ``E_ALL`` if needed to look for eventual PHP errors. +- ``DOWNLOAD_PICTURES`` (default: ``FALSE``) : Allows wallabag to fetch + images from the articles you save on your server, instead of fetching + only the text. We prefer to let you activate this option yourself. + Accepted values: ``TRUE`` or ``FALSE``. +- ``REGENERATE_PICTURES_QUALITY`` (default : ``75``) : In order to + avoid security problems, pictures are regenerated if you activate the + download of pictures. This is the percentage of quality at which they + are saved. Increase that numbler if you want better quality, lower if + you need better performances. +- ``SHARE_TWITTER`` (default: ``TRUE``) : enables Twitter sharing. + Accepted values: ``TRUE`` or ``FALSE``. +- ``SHARE_MAIL`` (default: ``TRUE``) : enables mail sharing. Accepted + values: ``TRUE`` or ``FALSE``. +- ``SHARE_EVERNOTE``\ (default : ``FALSE``) : enables sharing with your + Evernote account. Accepted values: ``TRUE`` or ``FALSE``. +- ``SHARE_DIASPORA`` (default : ``FALSE``) : enables to share an + article on your Diaspora account. +- ``DIASPORA_URL`` (default : ``http://diasporapod.com``) : The URL of + your Diaspora\* pod +- ``CARROT`` (default : ``FALSE``) : Like Flattr, it’s a service to + give small amounts of money to a web page. See http://carrot.org/ +- ``SHARE_SHAARLI`` (default: ``FALSE``) : enables sharing via your + Shaarli installation (Shaarli is an open-source bookmark manager). + Accepted values: ``TRUE`` or ``FALSE``. +- ``SHAARLI_URL`` (default: ``'http://myshaarliurl.com'``) : defines + your Shaarli installation URL. Accepted values: an URL. +- ``FLATTR`` (default: ``TRUE``) : enables the possibility to Flattr an + article (`Flattr is a microdonation platform`_). If an article is + Flattr-able, an icon will be displayed, allowing you to send a + microdonation to the author. Accepted values: ``TRUE`` or ``FALSE``. +- ``SHOW_PRINTLINK`` (default: ``'1'``) : enables the Print button for + articles. Accepted values: ``'1'`` to enable or ``'0'`` to disable. +- ``SHOW_READPERCENT`` (default: ``'1'``) : enables the reading + progress on articles (working on the ``default``, ``dark``, + ``dmagenta``, ``solarized``, ``solarized-dark`` themes). Accepted + values: ``'1'`` to enable or ``'0'`` to disable. +- ``PAGINATION`` (default: ``'12'``) : defines the number of articles + that are displayed on a list. Accepted values: number. + +.. _Flattr is a microdonation platform: http://en.wikipedia.org/wiki/Flattr diff --git a/docs/en/Administrator/install.rst b/docs/en/Administrator/install.rst new file mode 100644 index 00000000..006d8708 --- /dev/null +++ b/docs/en/Administrator/install.rst @@ -0,0 +1,200 @@ +Download and install wallabag +============================= + +I don’t want to install wallabag +-------------------------------- + +If you can’t or don’t want to install Wallabag on your server, we +suggest you create a free account on `Framabag`_ which uses our +software (see :ref:`Framabag account creation`). + +I want to install wallabag +-------------------------- + +I want to download wallabag manually +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`Download the latest wallabag version`_ and unpack it: + +:: + + wget http://wllbg.org/latest + unzip latest + mv wallabag-version-number wallabag + +Copy the files on your web server. For Ubuntu/Debian, it is the +directory /var/www/html/ : + +:: + + sudo mv wallabag /var/www/html/ + +Then, jump off to next section. + +I want to download wallabag via composer +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You need to install composer: + +:: + + curl -s http://getcomposer.org/installer | php + +Next, on your web server, run this command: + +:: + + composer create-project wallabag/wallabag . dev-master + +All is downloaded into the current folder. + +Prerequisites for your web server +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Wallabag requires that several components to be installed on your web +server. To make sure your server has all the prerequisites, open in your +browser the page ``http://monserveur.com/wallabag/install/index.php``. + +The components are: + +- `PHP 5.3.3 or above`_ **with `PDO`_ support** +- `XML for PHP`_ +- `PCRE`_ +- `ZLib`_ (otherwise, the processing of compressed pages will be + affected) +- `mbstring`_ anb/or `iconv`_ (otherwise some pages will not be read - + even in English) +- The `DOM/XML`_ extension +- `Data filtering`_ +- `GD`_ (otherwise, pictures will not be saved) +- `Tidy for PHP`_ (otherwise, you may encounter problems with some + pages) +- `cURL`_ with ``Parallel URL fetching`` (optionnal) +- `Parse ini file`_ +- `allow\_url\_fopen`_ (optionnal if cURL is installed) +- `gettext`_ (required for multi-language support) + +Install the missing components before to proceed. For example, to +install Tidy on Ubuntu/Debian: + +:: + + sudo apt-get install php5-tidy + sudo service apache2 reload + +Note : if you’re using IIS as a webserver, you have to disable +*Anonymous Authentication* and `enable *Basic Authentication*`_ in order +to be able to login. + +Twig installation +^^^^^^^^^^^^^^^^^ + +wallabag is build with Twig, a template library. You have to download it +for wallabag to work. If you cannot install ``composer`` (for example in +the case of shared hosting), we offer you to download a file which +includes ``Twig``. This file can be downloaed from the page +``http://myservur.com/wallabag/install/index.php`` (section TWIG +INSTALLATION) or directly at http://wllbg.org/vendor. Uncompress it in +your wallabag directory. + +Otherwise, you can use Composer to install ``Twig`` by launching +``composer`` from your wallabag directory (in the case of Ubuntu/Debian +too: /var/www/html/wallabag/) by following the commands written on +screen: + +:: + + curl -s http://getcomposer.org/installer | php + php composer.phar install + +Creation of the database. +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Wallabag can be installed on different types of databases: + +- `SQLite`_. The easiest system of all. No extra configuration needed. +- `MySQL`_. A well known database system, which is in most cases more + efficient than SQLite. +- `PostgreSQL`_. Some people found it better than MySQL. + +We advice you to use MySQL because it is more efficient. In this case, +you should create a new database (for example ``wallabag``), a new user +(for example ``wallabag``) and a password (here ``YourPassWord``). To do +this, you can use ``phpMyAdmin``, or launch the following commands: + +:: + + mysql -p -u root + mysql> CREATE DATABASE wallabag; + mysql> GRANT ALL PRIVILEGES ON `wallabag`.* TO 'wallabag'@'localhost' IDENTIFIED BY 'VotreMotdePasse'; + mysql> exit + +*Note:* If you’re using MySQL or Postgresql, you have to **fill all the +fields**, otherwise the installation will not work and an error message +will tell you what’s wrong. You must create the database that you will +use for wallabag manually with a tool like PHPMyAdmin or the console. + +Permissions +~~~~~~~~~~~ + +Your web server needs a writing access to the ``assets``, ``cache`` and +``db`` directories. Otherwise, a message will report that the +installation is impossible: + +:: + + sudo chown -R www-data:www-data /var/www/html/wallabag + +Installation of wallabag. At last. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Access to wallabag from your web browser: +``http://votreserveur.com/wallabag``. If your server is correctly +configured, you directly reach the setup screen. + +Select the type of database (``sqlite``, ``mysql`` or ``postgresql``) +and fill the information about your database. In the case of the databse +MySQL created before, the standard configuration will be: + +:: + + Database engine: MySQL + Server: localhost + Database: wallabag + Username: wallabag + Password: YourPassWord + +Finally, Create your first user and his/her password (different from the +database user). + +Wallabag is now installed. + +Login +----- + +From your web browser, you reach the login screen: fill your username +and your password to connect to your account. + +Enjoy! + +.. _SQLite: http://php.net/manual/fr/book.sqlite.php +.. _MySQL: http://php.net/manual/fr/book.mysql.php +.. _PostgreSQL: http://php.net/manual/fr/book.pgsql.php +.. _Framabag: https://framabag.org/ +.. _Download the latest wallabag version: http://wllbg.org/latest +.. _PHP 5.3.3 or above: http://php.net/manual/fr/install.php +.. _PDO: http://php.net/manual/en/book.pdo.php +.. _XML for PHP: http://php.net/fr/xml +.. _PCRE: http://php.net/fr/pcre +.. _ZLib: http://php.net/en/zlib +.. _mbstring: http://php.net/en/mbstring +.. _iconv: http://php.net/en/iconv +.. _DOM/XML: http://php.net/manual/en/book.dom.php +.. _Data filtering: http://php.net/manual/fr/book.filter.php +.. _GD: http://php.net/manual/en/book.image.php +.. _Tidy for PHP: http://php.net/fr/tidy +.. _cURL: http://php.net/fr/curl +.. _Parse ini file: http://uk.php.net/manual/en/function.parse-ini-file.php +.. _allow\_url\_fopen: http://www.php.net/manual/fr/filesystem.configuration.php#ini.allow-url-fopen +.. _gettext: http://php.net/manual/fr/book.gettext.php +.. _enable *Basic Authentication*: https://technet.microsoft.com/en-us/library/cc772009%28v=ws.10%29.aspx diff --git a/docs/en/Administrator/multiusers.rst b/docs/en/Administrator/multiusers.rst new file mode 100644 index 00000000..a4053aae --- /dev/null +++ b/docs/en/Administrator/multiusers.rst @@ -0,0 +1,47 @@ +.. _`Multi users`: + +Multi users +=========== + +Create a new account +-------------------- + +Administrator mode +------------------ + +If you want to use wallabag with several persons, you can create new +accounts from the configuration page. + +At the bottom of this page there is a form where you should input a user +name and a password. + +It is now possible to login to this account from the login page of +wallabag. + +No information are shared among the accounts. + +Open registration mode +---------------------- + +Starting from version 1.9, the administrator can let users register by +themselves. This is done by changing the following lines in the +configuration file: + +:: + + // registration + @define ('ALLOW_REGISTER', FALSE); + @define ('SEND_CONFIRMATION_EMAIL', FALSE); + +Then, a user will be able to enter his/her user name and password to +create his/her own account. Depending on the configuration, a +confimation email can be sent to users who gave an email address. + +Remove an account +----------------- + +It is possible to remove your own account from the configuration page. +You simply have to enter your password and to ask for the removal. + +Of course, when there is only one account, it is impossible to remove +it. diff --git a/docs/en/Administrator/sessions.rst b/docs/en/Administrator/sessions.rst new file mode 100644 index 00000000..7dbae257 --- /dev/null +++ b/docs/en/Administrator/sessions.rst @@ -0,0 +1,26 @@ +Session issues +============== + +If you end up disconnected even while checking the *Stay signed in +checkbox*, please run the following commands as root (or with sudo) : + +:: + + mkdir /var/lib/wallabag-sessions + chown www-data:www-data /var/lib/wallabag-sessions + +*NOTE : The www-data user and group may not exist, you may use +``chown http:http /var/lib/wallabag-sessions`` instead* + +Then, using apache add: +``php_admin_value session.save_path /var/lib/wallabag-sessions`` to your +apache vhost, for instance ``wallabag-apache.conf`` Finally, restart +apache, for instance like this : ``/etc/init.d/apache2 restart`` + +If you’re using nginx, add +``php_admin_value[session.save_path] = /var/lib/wallabag-sessions`` in +your nginx configuration file. Then, restart nginx : +``/etc/init.d/nginx restart`` + +*NOTE : If you’re using systemd, you should do +``systemctl restart apache2`` (or nginx).* diff --git a/docs/en/Administrator/update.rst b/docs/en/Administrator/update.rst new file mode 100644 index 00000000..7b799bb3 --- /dev/null +++ b/docs/en/Administrator/update.rst @@ -0,0 +1,30 @@ +Update wallabag +=============== + +Update an existing wallabag installation +---------------------------------------- + +In order to update your installation, download and unzip the archive +into your installation folder. For example on Ubuntu/Debian: + +:: + + wget http://wllbg.org/latest + unzip latest + rsync -ur wallabag-version-number/* /var/www/html/wallabag/ # could be another location such as /srv/html, /usr/share/nginx/html + +After that, just access wallabag in your browser and follow the +instructions to finish the update. + +You can verify at the bottom of the configuration page that you’re +running the last version. + +**If it fails**, just delete the ``install`` folder and clear the cache: + +:: + + cd /var/www/html/wallabag/ + rm -r cache/* install/ + +Clearing the cache is also possible in the configuration page, clicking +on the link ``Delete Cache``. -- cgit v1.2.3