X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=docs%2Fen%2Fuser%2Finstallation.rst;h=e08e0306fa0a039eadfe7a0f99017809d0ee6646;hb=7c1225347db8b516cc268709939f6b359bc283c1;hp=8250d2d7d35e3221eb7644f3341cd92cfc845a20;hpb=9c0bc04cfe61e84e21e33b8f8a51161851455221;p=github%2Fwallabag%2Fwallabag.git diff --git a/docs/en/user/installation.rst b/docs/en/user/installation.rst index 8250d2d7..e08e0306 100644 --- a/docs/en/user/installation.rst +++ b/docs/en/user/installation.rst @@ -6,7 +6,20 @@ Requirements wallabag is compatible with PHP >= 5.5, including PHP 7. -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. +.. note:: +To install wallabag easily, we create a ``Makefile``, so you need to have the ``make`` tool. + +wallabag uses a large number of PHP 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 and be sure to use the 1.2 version (if you already have Composer, run a ``composer selfupdate``). + +Install Composer: + +:: + + curl -s http://getcomposer.org/installer | php + +You can find specific instructions `here `__. + +You'll also 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. - php-session - php-ctype @@ -22,54 +35,81 @@ You'll need the following extensions for wallabag to work. Some of these may alr - php-curl - php-gettext - php-tokenizer +- php-bcmath -wallabag uses PDO to connect to database, so you'll need one of: +wallabag uses PDO to connect to the database, so you'll need one of the following: - pdo_mysql - pdo_sqlite - pdo_pgsql -and it's corresponding database server. +and its corresponding database server. Installation ------------ -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. +On a dedicated web server (recommended way) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Install Composer: +To install wallabag itself, you must run the following commands: :: - curl -s http://getcomposer.org/installer | php - -You can find specific instructions `here `__: + git clone https://github.com/wallabag/wallabag.git + cd wallabag && make install -To install wallabag itself, you must run these two commands: +To start PHP's build-in server and test if everything did install correctly, you can do: :: - git clone https://github.com/wallabag/wallabag.git - cd wallabag - git checkout 2.0.3 - SYMFONY_ENV=prod composer install --no-dev -o --prefer-dist - php bin/console wallabag:install --env=prod + make run -To start php's build-in server and test if everything did install correctly, you can do: +And access wallabag at http://yourserverip:8000 -:: +.. tip:: - php bin/console server:run --env=prod + 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 `__. -And access wallabag at http://yourserverip:8000 +On a shared hosting +~~~~~~~~~~~~~~~~~~~ -.. note:: +We provide a package with all dependencies inside. +The default configuration uses SQLite for the database. If you want to change these settings, please edit ``app/config/parameters.yml``. - 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 `__. +We already created a user: login and password are ``wallabag``. -Installing on Apache --------------------- +.. 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). -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: +Execute this command to download and extract the latest package: + +.. code-block:: bash + + wget http://wllbg.org/latest-v2-package && tar xvf latest-v2-package + +You will find the `md5 hash of the latest package on our website `_. + +Now, read the following documentation to create your virtual host, then access your wallabag. +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``. + +Installation with Docker +~~~~~~~~~~~~~~~~~~~~~~~~ + +We provide you a Docker image to install wallabag easily. Have a look to our repository on `Docker Hub `__ to have more information. + +Command to launch container +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: bash + + docker pull wallabag/wallabag + +Virtual hosts +------------- + +Configuration on Apache +~~~~~~~~~~~~~~~~~~~~~~~ + +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: :: @@ -111,10 +151,10 @@ Assuming you install wallabag in the /var/www/wallabag folder and that you want After reloading or restarting Apache, you should now be able to access wallabag at http://domain.tld. -Installing on Nginx -------------------- +Configuration on Nginx +~~~~~~~~~~~~~~~~~~~~~~ -Assuming you install wallabag in the /var/www/wallabag folder, here's the recipe for wallabag : +Assuming you installed wallabag in the ``/var/www/wallabag`` folder, here's the recipe for wallabag : :: @@ -151,6 +191,137 @@ Assuming you install wallabag in the /var/www/wallabag folder, here's the recipe After reloading or restarting nginx, you should now be able to access wallabag at http://domain.tld. -.. note:: +.. tip:: 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``. + +Configuration on lighttpd +~~~~~~~~~~~~~~~~~~~~~~~~~ + +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): + +:: + + server.modules = ( + "mod_fastcgi", + "mod_access", + "mod_alias", + "mod_compress", + "mod_redirect", + "mod_rewrite", + ) + server.document-root = "/var/www/wallabag/web" + server.upload-dirs = ( "/var/cache/lighttpd/uploads" ) + server.errorlog = "/var/log/lighttpd/error.log" + server.pid-file = "/var/run/lighttpd.pid" + server.username = "www-data" + server.groupname = "www-data" + server.port = 80 + server.follow-symlink = "enable" + index-file.names = ( "index.php", "index.html", "index.lighttpd.html") + url.access-deny = ( "~", ".inc" ) + static-file.exclude-extensions = ( ".php", ".pl", ".fcgi" ) + compress.cache-dir = "/var/cache/lighttpd/compress/" + compress.filetype = ( "application/javascript", "text/css", "text/html", "text/plain" ) + include_shell "/usr/share/lighttpd/use-ipv6.pl " + server.port + include_shell "/usr/share/lighttpd/create-mime.assign.pl" + include_shell "/usr/share/lighttpd/include-conf-enabled.pl" + dir-listing.activate = "disable" + + url.rewrite-if-not-file = ( + "^/([^?]*)(?:\?(.*))?" => "/app.php?$1&$2", + "^/([^?]*)" => "/app.php?=$1", + ) + +Rights access to the folders of the project +------------------------------------------- + +Test environment +~~~~~~~~~~~~~~~~ + +When we just want to test wallabag, we just run the command ``make run`` 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. + +Production environment +~~~~~~~~~~~~~~~~~~~~~~ + +As soon as we use Apache or Nginx to access to our wallabag instance, and not from the command ``make run`` 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. + +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). + +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. + +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: + +.. code-block:: bash + + chown -R www-data:www-data /var/www/wallabag/var + +It has to be the same for the following folders + +* /var/www/wallabag/bin/ +* /var/www/wallabag/app/config/ +* /var/www/wallabag/vendor/ +* /var/www/wallabag/data/ + +by entering + +.. code-block:: bash + + chown -R www-data:www-data /var/www/wallabag/bin + chown -R www-data:www-data /var/www/wallabag/app/config + chown -R www-data:www-data /var/www/wallabag/vendor + chown -R www-data:www-data /var/www/wallabag/data/ + +otherwise, sooner or later you will see these error messages: + +.. code-block:: bash + + Unable to write to the "bin" directory. + file_put_contents(app/config/parameters.yml): failed to open stream: Permission denied + file_put_contents(/.../wallabag/vendor/autoload.php): failed to open stream: Permission denied + +Additional rules for SELinux +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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: + +``getenforce`` + +This will return ``Enforcing`` if SELinux is enabled. Creating a new context involves the following syntax: + +``semanage fcontext -a -t `` + +For example: + +``semanage fcontext -a -t httpd_sys_content_t "/var/www/wallabag(/.*)?"`` + +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: + ++-----------------------------------+----------------------------+ +| Full path | Context | ++===================================+============================+ +| /var/www/wallabag(/.*)? | ``httpd_sys_content_t`` | ++-----------------------------------+----------------------------+ +| /var/www/wallabag/data(/.*)? | ``httpd_sys_rw_content_t`` | ++-----------------------------------+----------------------------+ +| /var/www/wallabag/var/logs(/.*)? | ``httpd_log_t`` | ++-----------------------------------+----------------------------+ +| /var/www/wallabag/var/cache(/.*)? | ``httpd_cache_t`` | ++-----------------------------------+----------------------------+ + +After creating these contexts, enter the following in order to apply your rules: + +``restorecon -R -v /var/www/wallabag`` + +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``. + +If you're installing the preconfigured latest-v2-package, then an additional rule is needed during the initial setup: + +``semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/wallabag/var"`` + +After you successfully access your wallabag and complete the initial setup, this context can be removed: + +:: + + semanage fcontext -d -t httpd_sys_rw_content_t "/var/www/wallabag/var" + retorecon -R -v /var/www/wallabag/var