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 the database, so you'll need one of the following:
  27
  28 - pdo_mysql
  29 - pdo_sqlite
  30 - pdo_pgsql
  31
  32 and its corresponding database server.
  33
  34 Installation
  35 ------------
  36
  37 On a dedicated web server (recommended way)
  38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  39
  40 wallabag uses a large number of libraries in order to function. These libraries must be installed with a tool called Composer. You need to install it if you have not already done so.
  41
  42 Install Composer:
  43
  44 ::
  45
  46     curl -s http://getcomposer.org/installer | php
  47
  48 You can find specific instructions `here <https://getcomposer.org/doc/00-intro.md>`__:
  49
  50 To install wallabag itself, you must run the following commands:
  51
  52 ::
  53
  54     git clone https://github.com/wallabag/wallabag.git
  55     cd wallabag
  56     git checkout 2.0.5
  57     SYMFONY_ENV=prod composer install --no-dev -o --prefer-dist
  58     php bin/console wallabag:install --env=prod
  59
  60 To start PHP's build-in server and test if everything did install correctly, you can do:
  61
  62 ::
  63
  64     php bin/console server:run --env=prod
  65
  66 And access wallabag at http://yourserverip:8000
  67
  68 .. tip::
  69
  70     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 at `Symfony documentation <http://symfony.com/doc/current/cookbook/configuration/external_parameters.html>`__.
  71
  72 On a shared hosting
  73 ~~~~~~~~~~~~~~~~~~~
  74
  75 We provide a package with all dependencies inside.
  76 The default configuration uses SQLite for the database. If you want to change these settings, please edit ``app/config/parameters.yml``.
  77
  78 We already created a user: login and password are ``wallabag``.
  79
  80 .. caution:: With this package, wallabag doesn't check for mandatory extensions used in the application (theses checks are made during ``composer install`` when you have a dedicated web server, see above).
  81
  82 Execute this command to download and extract the latest package:
  83
  84 .. code-block:: bash
  85
  86     wget http://wllbg.org/latest-v2-package && tar xvf latest-v2-package
  87
  88 Now, read the following documentation to create your virtual host, then access your wallabag.
  89 If you changed the database configuration to use MySQL or PostgreSQL, you need to create a user via this command ``php bin/console wallabag:install --env=prod``.
  90
  91 Installation with Docker
  92 ------------------------
  93
  94 We provide you a Docker image to install wallabag easily. Have a look to our repository on `Docker Hub <https://hub.docker.com/r/wallabag/wallabag/>`__ to have more information.
  95
  96 Command to launch container
  97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98
  99 .. code-block:: bash
 100
 101     docker pull wallabag/wallabag
 102
 103 Virtual hosts
 104 -------------
 105
 106 Configuration on Apache
 107 ~~~~~~~~~~~~~~~~~~~~~~~
 108
 109 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:
 110
 111 ::
 112
 113     <VirtualHost *:80>
 114         ServerName domain.tld
 115         ServerAlias www.domain.tld
 116
 117         DocumentRoot /var/www/wallabag/web
 118         <Directory /var/www/wallabag/web>
 119             AllowOverride None
 120             Order Allow,Deny
 121             Allow from All
 122
 123             <IfModule mod_rewrite.c>
 124                 Options -MultiViews
 125                 RewriteEngine On
 126                 RewriteCond %{REQUEST_FILENAME} !-f
 127                 RewriteRule ^(.*)$ app.php [QSA,L]
 128             </IfModule>
 129         </Directory>
 130
 131         # uncomment the following lines if you install assets as symlinks
 132         # or run into problems when compiling LESS/Sass/CoffeScript assets
 133         # <Directory /var/www/wallabag>
 134         #     Options FollowSymlinks
 135         # </Directory>
 136
 137         # optionally disable the RewriteEngine for the asset directories
 138         # which will allow apache to simply reply with a 404 when files are
 139         # not found instead of passing the request into the full symfony stack
 140         <Directory /var/www/wallabag/web/bundles>
 141             <IfModule mod_rewrite.c>
 142                 RewriteEngine Off
 143             </IfModule>
 144         </Directory>
 145         ErrorLog /var/log/apache2/wallabag_error.log
 146         CustomLog /var/log/apache2/wallabag_access.log combined
 147     </VirtualHost>
 148
 149 After reloading or restarting Apache, you should now be able to access wallabag at http://domain.tld.
 150
 151 Configuration on Nginx
 152 ~~~~~~~~~~~~~~~~~~~~~~
 153
 154 Assuming you installed wallabag in the ``/var/www/wallabag`` folder, here's the recipe for wallabag :
 155
 156 ::
 157
 158     server {
 159         server_name domain.tld www.domain.tld;
 160         root /var/www/wallabag/web;
 161
 162         location / {
 163             # try to serve file directly, fallback to app.php
 164             try_files $uri /app.php$is_args$args;
 165         }
 166         location ~ ^/app\.php(/|$) {
 167             fastcgi_pass unix:/var/run/php5-fpm.sock;
 168             fastcgi_split_path_info ^(.+\.php)(/.*)$;
 169             include fastcgi_params;
 170             # When you are using symlinks to link the document root to the
 171             # current version of your application, you should pass the real
 172             # application path instead of the path to the symlink to PHP
 173             # FPM.
 174             # Otherwise, PHP's OPcache may not properly detect changes to
 175             # your PHP files (see https://github.com/zendtech/ZendOptimizerPlus/issues/126
 176             # for more information).
 177             fastcgi_param  SCRIPT_FILENAME  $realpath_root$fastcgi_script_name;
 178             fastcgi_param DOCUMENT_ROOT $realpath_root;
 179             # Prevents URIs that include the front controller. This will 404:
 180             # http://domain.tld/app.php/some-path
 181             # Remove the internal directive to allow URIs like this
 182             internal;
 183         }
 184
 185         error_log /var/log/nginx/wallabag_error.log;
 186         access_log /var/log/nginx/wallabag_access.log;
 187     }
 188
 189 After reloading or restarting nginx, you should now be able to access wallabag at http://domain.tld.
 190
 191 .. tip::
 192
 193     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``.
 194
 195 Configuration on lighttpd
 196 ~~~~~~~~~~~~~~~~~~~~~~~~~
 197
 198 Assuming you install wallabag in the /var/www/wallabag folder, here's the recipe for wallabag (edit your ``lighttpd.conf`` file and paste this configuration into it):
 199
 200 ::
 201
 202     server.modules = (
 203         "mod_fastcgi",
 204         "mod_access",
 205         "mod_alias",
 206         "mod_compress",
 207         "mod_redirect",
 208         "mod_rewrite",
 209     )
 210     server.document-root = "/var/www/wallabag/web"
 211     server.upload-dirs = ( "/var/cache/lighttpd/uploads" )
 212     server.errorlog = "/var/log/lighttpd/error.log"
 213     server.pid-file = "/var/run/lighttpd.pid"
 214     server.username = "www-data"
 215     server.groupname = "www-data"
 216     server.port = 80
 217     server.follow-symlink = "enable"
 218     index-file.names = ( "index.php", "index.html", "index.lighttpd.html")
 219     url.access-deny = ( "~", ".inc" )
 220     static-file.exclude-extensions = ( ".php", ".pl", ".fcgi" )
 221     compress.cache-dir = "/var/cache/lighttpd/compress/"
 222     compress.filetype = ( "application/javascript", "text/css", "text/html", "text/plain" )
 223     include_shell "/usr/share/lighttpd/use-ipv6.pl " + server.port
 224     include_shell "/usr/share/lighttpd/create-mime.assign.pl"
 225     include_shell "/usr/share/lighttpd/include-conf-enabled.pl"
 226     dir-listing.activate = "disable"
 227
 228     url.rewrite-if-not-file = (
 229         "^/([^?])(?:\?(.))?" => "/app.php?$1&$2",
 230         "^/([^?]*)" => "/app.php?=$1",
 231     )
 232
 233 Rights access to the folders of the project
 234 -------------------------------------------
 235
 236 Test environment
 237 ~~~~~~~~~~~~~~~~
 238
 239 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.
 240
 241 Production environment
 242 ~~~~~~~~~~~~~~~~~~~~~~
 243
 244 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.
 245
 246 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).
 247
 248 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 homepage of the project.
 249
 250 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:
 251
 252 .. code-block:: bash
 253
 254    chown -R www-data:www-data /var/www/wallabag/var
 255
 256 It has to be the same for the following folders
 257
 258 * /var/www/wallabag/bin/
 259 * /var/www/wallabag/app/config/
 260 * /var/www/wallabag/vendor/
 261 * /var/www/wallabag/data/
 262
 263 by entering
 264
 265 .. code-block:: bash
 266
 267    chown -R www-data:www-data /var/www/wallabag/bin
 268    chown -R www-data:www-data /var/www/wallabag/app/config
 269    chown -R www-data:www-data /var/www/wallabag/vendor
 270    chown -R www-data:www-data /var/www/wallabag/data/
 271
 272 otherwise, sooner or later you will see these error messages:
 273
 274 .. code-block:: bash
 275
 276     Unable to write to the "bin" directory.
 277     file_put_contents(app/config/parameters.yml): failed to open stream: Permission denied
 278     file_put_contents(/.../wallabag/vendor/autoload.php): failed to open stream: Permission denied
 279
 280 Additional rules for SELinux
 281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 282
 283 If SELinux is enabled on your system, you will need to configure additional contexts in order for wallabag to function properly. To check if SELinux is enabled, simply enter the following:
 284
 285 ``getenforce``
 286
 287 This will return ``Enforcing`` if SELinux is enabled. Creating a new context involves the following syntax:
 288
 289 ``semanage fcontext -a -t <context type> <full path>``
 290
 291 For example:
 292
 293 ``semanage fcontext -a -t httpd_sys_content_t "/var/www/wallabag(/.*)?"``
 294
 295 This will recursively apply the httpd_sys_content_t context to the wallabag directory and all underlying files and folders. The following rules are needed:
 296
 297 +-----------------------------------+----------------------------+
 298 | Full path                         | Context                    |
 299 +===================================+============================+
 300 | /var/www/wallabag(/.*)?           | ``httpd_sys_content_t``    |
 301 +-----------------------------------+----------------------------+
 302 | /var/www/wallabag/data(/.*)?      | ``httpd_sys_rw_content_t`` |
 303 +-----------------------------------+----------------------------+
 304 | /var/www/wallabag/var/logs(/.*)?  | ``httpd_log_t``            |
 305 +-----------------------------------+----------------------------+
 306 | /var/www/wallabag/var/cache(/.*)? | ``httpd_cache_t``          |
 307 +-----------------------------------+----------------------------+
 308
 309 After creating these contexts, enter the following in order to apply your rules:
 310
 311 ``restorecon -R -v /var/www/wallabag``
 312
 313 You can check contexts in a directory by typing ``ls -lZ`` and you can see all of your current rules with ``semanage fcontext -l -C``.
 314
 315 If you're installing the preconfigured latest-v2-package, then an additional rule is needed during the initial setup:
 316
 317 ``semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/wallabag/var"``
 318
 319 After you successfully access your wallabag and complete the initial setup, this context can be removed:
 320
 321 ::
 322
 323     semanage fcontext -d -t httpd_sys_rw_content_t "/var/www/wallabag/var"
 324     retorecon -R -v /var/www/wallabag/var