]>
Commit | Line | Data |
---|---|---|
e6ebb14f NL |
1 | Install wallabag |
2 | ================ | |
3 | ||
4 | Requirements | |
5 | ------------ | |
6 | ||
de0ab52a | 7 | wallabag is compatible with **PHP >= 5.6**, 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 |
13 | 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``). |
14 | ||
15 | Install Composer: | |
16 | ||
17 | :: | |
18 | ||
7c05d591 | 19 | curl -s https://getcomposer.org/installer | php |
7eff4736 NL |
20 | |
21 | You can find specific instructions `here <https://getcomposer.org/doc/00-intro.md>`__. | |
22 | ||
23 | 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. | |
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 | 41 | wallabag 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 | 47 | and its corresponding database server. |
89d95cdd | 48 | |
e6ebb14f NL |
49 | Installation |
50 | ------------ | |
51 | ||
bba9907d NL |
52 | On a dedicated web server (recommended way) |
53 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
54 | ||
b5fa6607 | 55 | To 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 | 62 | To 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 | |
68 | And 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 |
74 | On a shared hosting |
75 | ~~~~~~~~~~~~~~~~~~~ | |
76 | ||
b5fa6607 | 77 | We provide a package with all dependencies inside. |
bba9907d NL |
78 | The default configuration uses SQLite for the database. If you want to change these settings, please edit ``app/config/parameters.yml``. |
79 | ||
80 | We 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 | |
84 | Execute 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 | 90 | You will find the `md5 hash of the latest package on our website <https://www.wallabag.org/pages/download-wallabag.html>`_. |
94d1dae4 | 91 | |
b5fa6607 | 92 | Now, read the following documentation to create your virtual host, then access your wallabag. |
bba9907d NL |
93 | 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``. |
94 | ||
95 | Installation with Docker | |
7eff4736 | 96 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
bba9907d | 97 | |
a25377cb | 98 | We 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 | 100 | Command to launch container |
7eff4736 | 101 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
bba9907d NL |
102 | |
103 | .. code-block:: bash | |
104 | ||
105 | docker pull wallabag/wallabag | |
106 | ||
56f9adc4 JZ |
107 | Installation on Cloudron |
108 | ~~~~~~~~~~~~~~~~~~~~~~~~ | |
109 | ||
110 | Cloudron provides an easy way to install webapps on your server with a focus on sysadmin automation and keeping apps updated. | |
3ea184ff | 111 | wallabag is packaged as a Cloudron app and available to install directly from the store. |
56f9adc4 | 112 | |
3ea184ff | 113 | `Install wallabag on your Cloudron <https://cloudron.io/store/org.wallabag.cloudronapp.html>`__ |
56f9adc4 | 114 | |
bba9907d NL |
115 | Virtual hosts |
116 | ------------- | |
117 | ||
118 | Configuration on Apache | |
119 | ~~~~~~~~~~~~~~~~~~~~~~~ | |
120 | ||
0a82d6e2 QT |
121 | Do not forget to active the *rewrite* mod of Apache |
122 | ||
123 | .. code-block:: bash | |
124 | ||
125 | a2enmod rewrite && systemctl reload apache2 | |
126 | ||
bba9907d | 127 | 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: |
89d95cdd TC |
128 | |
129 | :: | |
130 | ||
131 | <VirtualHost *:80> | |
132 | ServerName domain.tld | |
133 | ServerAlias www.domain.tld | |
134 | ||
135 | DocumentRoot /var/www/wallabag/web | |
136 | <Directory /var/www/wallabag/web> | |
137 | AllowOverride None | |
138 | Order Allow,Deny | |
139 | Allow from All | |
140 | ||
141 | <IfModule mod_rewrite.c> | |
142 | Options -MultiViews | |
143 | RewriteEngine On | |
144 | RewriteCond %{REQUEST_FILENAME} !-f | |
145 | RewriteRule ^(.*)$ app.php [QSA,L] | |
146 | </IfModule> | |
147 | </Directory> | |
148 | ||
149 | # uncomment the following lines if you install assets as symlinks | |
150 | # or run into problems when compiling LESS/Sass/CoffeScript assets | |
151 | # <Directory /var/www/wallabag> | |
152 | # Options FollowSymlinks | |
153 | # </Directory> | |
154 | ||
155 | # optionally disable the RewriteEngine for the asset directories | |
156 | # which will allow apache to simply reply with a 404 when files are | |
157 | # not found instead of passing the request into the full symfony stack | |
158 | <Directory /var/www/wallabag/web/bundles> | |
159 | <IfModule mod_rewrite.c> | |
160 | RewriteEngine Off | |
161 | </IfModule> | |
162 | </Directory> | |
163 | ErrorLog /var/log/apache2/wallabag_error.log | |
164 | CustomLog /var/log/apache2/wallabag_access.log combined | |
165 | </VirtualHost> | |
3ea184ff NL |
166 | |
167 | ||
168 | .. tip:: Note for Apache 2.4, in the section `<Directory /var/www/wallabag/web>` you have to replace the directives : | |
947ccd07 KG |
169 | |
170 | :: | |
171 | ||
172 | AllowOverride None | |
173 | Order Allow,Deny | |
174 | Allow from All | |
175 | ||
176 | ||
3ea184ff | 177 | by |
947ccd07 KG |
178 | |
179 | :: | |
3ea184ff | 180 | |
947ccd07 | 181 | Require All granted |
3ea184ff | 182 | |
89d95cdd TC |
183 | |
184 | After reloading or restarting Apache, you should now be able to access wallabag at http://domain.tld. | |
185 | ||
bba9907d NL |
186 | Configuration on Nginx |
187 | ~~~~~~~~~~~~~~~~~~~~~~ | |
89d95cdd | 188 | |
b5fa6607 | 189 | Assuming you installed wallabag in the ``/var/www/wallabag`` folder, here's the recipe for wallabag : |
89d95cdd TC |
190 | |
191 | :: | |
192 | ||
193 | server { | |
194 | server_name domain.tld www.domain.tld; | |
195 | root /var/www/wallabag/web; | |
196 | ||
197 | location / { | |
198 | # try to serve file directly, fallback to app.php | |
199 | try_files $uri /app.php$is_args$args; | |
200 | } | |
201 | location ~ ^/app\.php(/|$) { | |
202 | fastcgi_pass unix:/var/run/php5-fpm.sock; | |
203 | fastcgi_split_path_info ^(.+\.php)(/.*)$; | |
204 | include fastcgi_params; | |
205 | # When you are using symlinks to link the document root to the | |
206 | # current version of your application, you should pass the real | |
207 | # application path instead of the path to the symlink to PHP | |
208 | # FPM. | |
209 | # Otherwise, PHP's OPcache may not properly detect changes to | |
210 | # your PHP files (see https://github.com/zendtech/ZendOptimizerPlus/issues/126 | |
211 | # for more information). | |
212 | fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name; | |
213 | fastcgi_param DOCUMENT_ROOT $realpath_root; | |
214 | # Prevents URIs that include the front controller. This will 404: | |
215 | # http://domain.tld/app.php/some-path | |
216 | # Remove the internal directive to allow URIs like this | |
217 | internal; | |
218 | } | |
219 | ||
ccad5d76 OD |
220 | # return 404 for all other php files not matching the front controller |
221 | # this prevents access to other php files you don't want to be accessible. | |
222 | location ~ \.php$ { | |
223 | return 404; | |
224 | } | |
225 | ||
89d95cdd TC |
226 | error_log /var/log/nginx/wallabag_error.log; |
227 | access_log /var/log/nginx/wallabag_access.log; | |
228 | } | |
229 | ||
230 | After reloading or restarting nginx, you should now be able to access wallabag at http://domain.tld. | |
cea846d4 | 231 | |
bba9907d | 232 | .. tip:: |
cea846d4 | 233 | |
a25377cb | 234 | 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 | 235 | |
8b563fc0 | 236 | Configuration on lighttpd |
e546a2d6 NL |
237 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
238 | ||
a25377cb | 239 | 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): |
e546a2d6 NL |
240 | |
241 | :: | |
242 | ||
243 | server.modules = ( | |
8b563fc0 NL |
244 | "mod_fastcgi", |
245 | "mod_access", | |
246 | "mod_alias", | |
247 | "mod_compress", | |
248 | "mod_redirect", | |
249 | "mod_rewrite", | |
e546a2d6 NL |
250 | ) |
251 | server.document-root = "/var/www/wallabag/web" | |
252 | server.upload-dirs = ( "/var/cache/lighttpd/uploads" ) | |
253 | server.errorlog = "/var/log/lighttpd/error.log" | |
254 | server.pid-file = "/var/run/lighttpd.pid" | |
255 | server.username = "www-data" | |
256 | server.groupname = "www-data" | |
257 | server.port = 80 | |
258 | server.follow-symlink = "enable" | |
259 | index-file.names = ( "index.php", "index.html", "index.lighttpd.html") | |
260 | url.access-deny = ( "~", ".inc" ) | |
261 | static-file.exclude-extensions = ( ".php", ".pl", ".fcgi" ) | |
262 | compress.cache-dir = "/var/cache/lighttpd/compress/" | |
263 | compress.filetype = ( "application/javascript", "text/css", "text/html", "text/plain" ) | |
264 | include_shell "/usr/share/lighttpd/use-ipv6.pl " + server.port | |
265 | include_shell "/usr/share/lighttpd/create-mime.assign.pl" | |
266 | include_shell "/usr/share/lighttpd/include-conf-enabled.pl" | |
267 | dir-listing.activate = "disable" | |
268 | ||
269 | url.rewrite-if-not-file = ( | |
02d10905 | 270 | "^/([^?]*)(?:\?(.*))?" => "/app.php?$1&$2", |
8b563fc0 | 271 | "^/([^?]*)" => "/app.php?=$1", |
e546a2d6 NL |
272 | ) |
273 | ||
9ddf49ba OD |
274 | Rights access to the folders of the project |
275 | ------------------------------------------- | |
276 | ||
bba9907d | 277 | Test environment |
9ddf49ba OD |
278 | ~~~~~~~~~~~~~~~~ |
279 | ||
7c122534 | 280 | 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. |
9ddf49ba | 281 | |
bba9907d | 282 | Production environment |
9ddf49ba OD |
283 | ~~~~~~~~~~~~~~~~~~~~~~ |
284 | ||
7c122534 | 285 | 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. |
9ddf49ba OD |
286 | |
287 | 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). | |
288 | ||
a25377cb | 289 | So 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 |
290 | |
291 | 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: | |
292 | ||
293 | .. code-block:: bash | |
294 | ||
295 | chown -R www-data:www-data /var/www/wallabag/var | |
ab46a256 OD |
296 | |
297 | It has to be the same for the following folders | |
298 | ||
299 | * /var/www/wallabag/bin/ | |
300 | * /var/www/wallabag/app/config/ | |
301 | * /var/www/wallabag/vendor/ | |
b5fa6607 | 302 | * /var/www/wallabag/data/ |
ab46a256 OD |
303 | |
304 | by entering | |
305 | ||
306 | .. code-block:: bash | |
307 | ||
308 | chown -R www-data:www-data /var/www/wallabag/bin | |
309 | chown -R www-data:www-data /var/www/wallabag/app/config | |
310 | chown -R www-data:www-data /var/www/wallabag/vendor | |
458854f1 | 311 | chown -R www-data:www-data /var/www/wallabag/data/ |
ab46a256 | 312 | |
b5fa6607 | 313 | otherwise, sooner or later you will see these error messages: |
ab46a256 OD |
314 | |
315 | .. code-block:: bash | |
316 | ||
317 | Unable to write to the "bin" directory. | |
318 | file_put_contents(app/config/parameters.yml): failed to open stream: Permission denied | |
319 | file_put_contents(/.../wallabag/vendor/autoload.php): failed to open stream: Permission denied | |
b5fa6607 P |
320 | |
321 | Additional rules for SELinux | |
322 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
323 | ||
324 | 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: | |
325 | ||
326 | ``getenforce`` | |
327 | ||
328 | This will return ``Enforcing`` if SELinux is enabled. Creating a new context involves the following syntax: | |
329 | ||
330 | ``semanage fcontext -a -t <context type> <full path>`` | |
331 | ||
332 | For example: | |
333 | ||
334 | ``semanage fcontext -a -t httpd_sys_content_t "/var/www/wallabag(/.*)?"`` | |
335 | ||
336 | 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: | |
337 | ||
338 | +-----------------------------------+----------------------------+ | |
339 | | Full path | Context | | |
340 | +===================================+============================+ | |
341 | | /var/www/wallabag(/.*)? | ``httpd_sys_content_t`` | | |
342 | +-----------------------------------+----------------------------+ | |
343 | | /var/www/wallabag/data(/.*)? | ``httpd_sys_rw_content_t`` | | |
344 | +-----------------------------------+----------------------------+ | |
345 | | /var/www/wallabag/var/logs(/.*)? | ``httpd_log_t`` | | |
346 | +-----------------------------------+----------------------------+ | |
347 | | /var/www/wallabag/var/cache(/.*)? | ``httpd_cache_t`` | | |
348 | +-----------------------------------+----------------------------+ | |
349 | ||
350 | After creating these contexts, enter the following in order to apply your rules: | |
351 | ||
352 | ``restorecon -R -v /var/www/wallabag`` | |
353 | ||
354 | 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``. | |
355 | ||
356 | If you're installing the preconfigured latest-v2-package, then an additional rule is needed during the initial setup: | |
357 | ||
358 | ``semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/wallabag/var"`` | |
359 | ||
360 | After you successfully access your wallabag and complete the initial setup, this context can be removed: | |
361 | ||
362 | :: | |
363 | ||
364 | semanage fcontext -d -t httpd_sys_rw_content_t "/var/www/wallabag/var" | |
365 | retorecon -R -v /var/www/wallabag/var |