wallabag Documentation Release 2.0.0

Nicolas Lœuillet

January 05, 2016

Contents

1

Create an account 1.1 Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3 6

2

Login 2.1 Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7 7

3

Configuration 3.1 Settings . . . . . 3.2 RSS . . . . . . . 3.3 User information 3.4 Password . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

9 9 9 9 10

Save your first article 4.1 By using a bookmarklet . . . . . . . 4.2 By using the classic form . . . . . . 4.3 By using a browser add-on . . . . . . 4.4 By using your smarphone application

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

11 11 11 11 12

Migrate to wallabag 5.1 From wallabag 1.x . . . . 5.2 From Pocket . . . . . . . 5.3 From Instapaper . . . . . 5.4 From Readability . . . . . 5.5 From HTML or JSON file

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

13 13 14 14 14 14

6

Download and install wallabag 6.1 I don’t want to install wallabag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.2 I want to install wallabag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.3 Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

15 15 15 17

7

Update wallabag 7.1 Update an existing wallabag installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

19 19

8

Hidden options 8.1 Caution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8.2 Modification of advanced options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

21 21 21

9

Multi users 9.1 Create a new account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23 23

4

5

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . . .

. . . .

. . . . .

. . . .

. . . . .

. . . .

. . . . .

. . . .

. . . . .

. . . . .

i

9.2 9.3 9.4

Administrator mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Open registration mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Remove an account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

23 23 23

10 Session issues

25

11 Write config files 11.1 Automatic config files generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Manual config file generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

27 27 27

12 Create new theme

29

13 Git repository 13.1 Current state . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.2 Workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

31 31 31

ii

wallabag Documentation, Release 2.0.0

wallabag is a read-it-later application: it saves a web page by keeping content only. Elements like navigation or ads are deleted. The main documentation for the site is organized into a couple sections: • User Documentation • Admin Documentation • Developer Documentation

Contents

1

wallabag Documentation, Release 2.0.0

2

Contents

CHAPTER 1

Create an account

On the login page, click on Register button.

3

wallabag Documentation, Release 2.0.0

You have to fill the form. Please sure to type a valid email address, we’ll send you an activation email.

4

Chapter 1. Create an account

wallabag Documentation, Release 2.0.0

Check your inbox, you now have a new mail with a link like this http://wallabag/register/confirm/Ba19wokGovN-DdBQNfg4YgRkUQWRP4-k2g0Bk-hBTX4. Click on it to activate your account. Your account is now activated.

5

wallabag Documentation, Release 2.0.0

1.1 Frequently asked questions 1.1.1 I can’t valid the registration form Make sure that all fields are well filled: • valid email address • same passwords in two fields

1.1.2 I don’t receive my activation email Are you sure your email address was correct? Did you check your spams folder?

1.1.3 When I click on the activation link, I’ve got this message: The user with confirmation token "DtrOPfbQeVkWf6N" does not exist. You already enabled your account or the URL of the activation email is wrong.

6

Chapter 1. Create an account

CHAPTER 2

Login

Your account is now enabled, congratulations! To login to wallabag, fill the form on login page. If you are on your personal computer and you want to stay connected, you can check the Keep me logged in checkbox: wallabag will remember you for one year.

2.1 Frequently asked questions 2.1.1 I forgot my password You can reset your password by clicking on Forgot your password? link, on the login page. Then, fill the form with your email address 7

wallabag Documentation, Release 2.0.0

8

Chapter 2. Login

CHAPTER 3

Configuration

Now you’re logged in, it’s time to configure your account as you want. Click on Config menu. You have four tabs: Settings, RSS, User information and Password.

3.1 Settings 3.1.1 Theme wallabag is customizable. You can choose your prefered theme here. You can also create a new one, a chapter is dedicated for this. The default theme is Material, it’s the theme used in the documentation screenshots.

3.1.2 Items per page You can change the number of articles displayed on each page.

3.1.3 Language You can change the language of wallabag interface.

3.2 RSS wallabag provides RSS feeds for each article status: unread, starred and archive. Firstly, you need to create a personal token: click on Create your token. It’s possible to change your token by clicking on Reset your token. Now you have three links, one for each status: add them into your favourite RSS reader. You can also define how many articles you want in each RSS feed (default value: 50).

3.3 User information You can change your name, your email address and enable Two factor authentication.

9

wallabag Documentation, Release 2.0.0

3.3.1 Two factor authentication Two-factor authentication (also known as 2FA) is a technology patented in 1984 that provides identification of users by means of the combination of two different components. https://en.wikipedia.org/wiki/Two-factor_authentication If you enable 2FA, each time you want to login to wallabag, you’ll receive a code by email. You have to put this code on the following form.

If you don’t want to receive a code each time you want to login, you can check the I’m on a trusted computer checkbox: wallabag will remember you for 15 days.

3.4 Password You can change your password here.

10

Chapter 3. Configuration

CHAPTER 4

Save your first article

The main purpose of wallabag is to save web articles. You have many ways to do it.

4.1 By using a bookmarklet On the Howto page, you have a Bookmarklet tab. Drag and drop the bag it! link to your bookmarks bar of your browser. Now, each time you’re reading an article on the web and you want to save it, click on the bag it! link in your bookmarks bar. The article is saved.

4.2 By using the classic form In the top bar of your screen, you have 3 icons. With the first one, a plus sign, you can easily save a new article.

Click on it to display a new field, paste the article URL inside and press your Return key. The article is saved.

4.3 By using a browser add-on 4.3.1 Firefox Firefox Classic Add-on Download the Firefox add-on at addons.mozilla.org and install it like any other Firefox add-on. In the add-on’s settings, fill the complete URL of your installation of wallabag or your Framabag account. Personalize the Firefox toolbar to add wallabag (W icon). When you find an article you want to save, click on this icon: a new window will open to add the article and will close itself automatically. 11

wallabag Documentation, Release 2.0.0

Firefox Social API Service Available from wallabag v1.9.1 only You will need an https connection to use this. It’s a Firefox requirement, sorry. With Firefox 29+ versions, your browser comes with an integrated interface to share things to multiple social services directly from your browser. In the Firefox interface, it is shown a paper plane-like icon that you will use to share a page, which means here, save an article. You can add the service by going into the Config page of wallabag, then click on Mozilla Services Social API Extension. You must also accept to use Firefox Services.

4.3.2 Chrome

4.4 By using your smarphone application 4.4.1 Android 4.4.2 Firefox OS 4.4.3 Windows Phone 4.4.4 iOS

12

Chapter 4. Save your first article

CHAPTER 5

Migrate to wallabag

5.1 From wallabag 1.x 5.1.1 Export your data from your wallabag 1.x On your config page, click on JSON export in the Export your wallabag data section.

You will have a wallabag-export-1-1970-01-01.json file.

5.1.2 Import your data into wallabag 2.x Click on Import link in the menu, select your export file on your computer and import it.

All your wallabag 1.x articles will be imported.

13

wallabag Documentation, Release 2.0.0

5.2 From Pocket 5.3 From Instapaper 5.4 From Readability 5.5 From HTML or JSON file user/organize user/filters User/read_an_article User/rss_feed User/import_export

14

User/search

User/epub_conversion

User/issue_with_article

Chapter 5. Migrate to wallabag

CHAPTER 6

Download and install wallabag

6.1 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 Framabag account creation).

6.2 I want to install wallabag 6.2.1 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.

6.2.2 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.

15

wallabag Documentation, Release 2.0.0

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:

16

Chapter 6. Download and install wallabag

wallabag Documentation, Release 2.0.0

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.

6.2.3 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

6.2.4 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: Server: Database: Username: Password:

MySQL localhost wallabag wallabag YourPassWord

Finally, Create your first user and his/her password (different from the database user). Wallabag is now installed.

6.3 Login From your web browser, you reach the login screen: fill your username and your password to connect to your account. Enjoy!

6.3. Login

17

wallabag Documentation, Release 2.0.0

18

Chapter 6. Download and install wallabag

CHAPTER 7

Update wallabag

7.1 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/

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.

19

wallabag Documentation, Release 2.0.0

20

Chapter 7. Update wallabag

CHAPTER 8

Hidden options

8.1 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.

8.2 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.

21

wallabag Documentation, Release 2.0.0

• 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.

22

Chapter 8. Hidden options

CHAPTER 9

Multi users

9.1 Create a new account 9.2 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.

9.3 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.

9.4 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.

23

wallabag Documentation, Release 2.0.0

24

Chapter 9. Multi users

CHAPTER 10

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, /var/lib/wallabag-sessions in /etc/init.d/nginx restart

your

add nginx

php_admin_value[session.save_path] = configuration file. Then, restart nginx :

NOTE : If you’re using systemd, you should do ‘‘systemctl restart apache2‘‘ (or nginx).

25

wallabag Documentation, Release 2.0.0

26

Chapter 10. Session issues

CHAPTER 11

Write config files

wallabag can use specific site config files to parse website articles. These files are stored in the ‘inc/3rdparty/site_config/standard