docs/en/user/installation.rst

   1 Install wallabag
   2 ================
   3
   4 Requirements
   5 ------------
   6
   7 wallabag is compatible with PHP >= 5.5, including PHP 7.
   8
   9 You'll need the following extensions for wallabag to work. Some of these may already activated in your version of PHP, so you may not have to install all corresponding packages.
  10
  11 - php-session
  12 - php-ctype
  13 - php-dom
  14 - php-hash
  15 - php-simplexml
  16 - php-json
  17 - php-gd
  18 - php-mbstring
  19 - php-xml
  20 - php-tidy
  21 - php-iconv
  22 - php-curl
  23 - php-gettext
  24 - php-tokenizer
  25
  26 wallabag uses PDO to connect to database, so you'll need one of:
  27
  28 - pdo_mysql
  29 - pdo_sqlite
  30 - pdo_pgsql
  31
  32 and it's corresponding database server.
  33
  34 Installation
  35 ------------
  36
  37 wallabag uses a big number of libraries in order to function. These libraries must be installed with a tool called Composer. You need to install it if you don't already have.
  38
  39 Install Composer:
  40
  41 ::
  42
  43     curl -s http://getcomposer.org/installer | php
  44
  45 You can find specific instructions `here <https://getcomposer.org/doc/00-intro.md>`__:
  46
  47 To install wallabag itself, you must run these two commands:
  48
  49 ::
  50
  51     git clone https://github.com/wallabag/wallabag.git
  52     cd wallabag
  53     git checkout 2.0.3
  54     SYMFONY_ENV=prod composer install --no-dev -o --prefer-dist
  55     php bin/console wallabag:install --env=prod
  56
  57 To start php's build-in server and test if everything did install correctly, you can do:
  58
  59 ::
  60
  61     php bin/console server:run --env=prod
  62
  63 And access wallabag at http://yourserverip:8000
  64
  65 .. note::
  66
  67     To define parameters with environment variables, you have to set these variables with ``SYMFONY__`` prefix. For example, ``SYMFONY__DATABASE_DRIVER``. You can have a look to the `Symfony documentation <http://symfony.com/doc/current/cookbook/configuration/external_parameters.html>`__.
  68
  69 Installing on Apache
  70 --------------------
  71
  72 Assuming you install wallabag in the /var/www/wallabag folder and that you want to use php as an Apache module, here's a vhost for wallabag:
  73
  74 ::
  75
  76     <VirtualHost *:80>
  77         ServerName domain.tld
  78         ServerAlias www.domain.tld
  79
  80         DocumentRoot /var/www/wallabag/web
  81         <Directory /var/www/wallabag/web>
  82             AllowOverride None
  83             Order Allow,Deny
  84             Allow from All
  85
  86             <IfModule mod_rewrite.c>
  87                 Options -MultiViews
  88                 RewriteEngine On
  89                 RewriteCond %{REQUEST_FILENAME} !-f
  90                 RewriteRule ^(.*)$ app.php [QSA,L]
  91             </IfModule>
  92         </Directory>
  93
  94         # uncomment the following lines if you install assets as symlinks
  95         # or run into problems when compiling LESS/Sass/CoffeScript assets
  96         # <Directory /var/www/wallabag>
  97         #     Options FollowSymlinks
  98         # </Directory>
  99
 100         # optionally disable the RewriteEngine for the asset directories
 101         # which will allow apache to simply reply with a 404 when files are
 102         # not found instead of passing the request into the full symfony stack
 103         <Directory /var/www/wallabag/web/bundles>
 104             <IfModule mod_rewrite.c>
 105                 RewriteEngine Off
 106             </IfModule>
 107         </Directory>
 108         ErrorLog /var/log/apache2/wallabag_error.log
 109         CustomLog /var/log/apache2/wallabag_access.log combined
 110     </VirtualHost>
 111
 112 After reloading or restarting Apache, you should now be able to access wallabag at http://domain.tld.
 113
 114 Installing on Nginx
 115 -------------------
 116
 117 Assuming you install wallabag in the /var/www/wallabag folder, here's the recipe for wallabag :
 118
 119 ::
 120
 121     server {
 122         server_name domain.tld www.domain.tld;
 123         root /var/www/wallabag/web;
 124
 125         location / {
 126             # try to serve file directly, fallback to app.php
 127             try_files $uri /app.php$is_args$args;
 128         }
 129         location ~ ^/app\.php(/|$) {
 130             fastcgi_pass unix:/var/run/php5-fpm.sock;
 131             fastcgi_split_path_info ^(.+\.php)(/.*)$;
 132             include fastcgi_params;
 133             # When you are using symlinks to link the document root to the
 134             # current version of your application, you should pass the real
 135             # application path instead of the path to the symlink to PHP
 136             # FPM.
 137             # Otherwise, PHP's OPcache may not properly detect changes to
 138             # your PHP files (see https://github.com/zendtech/ZendOptimizerPlus/issues/126
 139             # for more information).
 140             fastcgi_param  SCRIPT_FILENAME  $realpath_root$fastcgi_script_name;
 141             fastcgi_param DOCUMENT_ROOT $realpath_root;
 142             # Prevents URIs that include the front controller. This will 404:
 143             # http://domain.tld/app.php/some-path
 144             # Remove the internal directive to allow URIs like this
 145             internal;
 146         }
 147
 148         error_log /var/log/nginx/wallabag_error.log;
 149         access_log /var/log/nginx/wallabag_access.log;
 150     }
 151
 152 After reloading or restarting nginx, you should now be able to access wallabag at http://domain.tld.
 153
 154 .. note::
 155
 156     When you want to import large file into wallabag, you need to add this line in your nginx configuration ``client_max_body_size XM; # allows file uploads up to X megabytes``.
 157
 158
 159
 160
 161 Rights access to the folders of the project
 162 -------------------------------------------
 163
 164
 165 Test Environment
 166 ~~~~~~~~~~~~~~~~
 167
 168 When we just want to test Wallabag, we just run the command ``php bin/console server:run --env=prod`` to start our Wallabag instance and everything will go smoothly because the user who started the project can access to the current folder naturally, without any problem.
 169
 170
 171 Production Environment
 172 ~~~~~~~~~~~~~~~~~~~~~~
 173
 174 As soon as we use Apache or Nginx to access to our Wallabag instance, and not from the command  ``php bin/console server:run --env=prod`` to start it, we should take care to grant the good rights on the good folders to keep safe all the folders of the project.
 175
 176 To do so, the folder name, known as ``DocumentRoot`` (for apache) or ``root`` (for Nginx), has to be absolutely accessible by the Apache/Nginx user. Its name is generally ``www-data``, ``apache`` or ``nobody`` (depending on linux system used).
 177
 178 So the folder ``/var/www/wallabag/web`` has to be accessible by this last one. But this could be not enough if we just care about this folder, because we could meet a blank page or get an error 500 when trying to access to the home page of the project.
 179
 180 This is due to the fact that we will need to grant the same rights access on the folder ``/var/www/wallabag/var`` like those we gave on the folder ``/var/www/wallabag/web``. Thus, we fix this problem with the following command:
 181
 182 .. code-block:: bash
 183
 184    chown -R www-data:www-data /var/www/wallabag/var
 185