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