diff options
author | Nicolas LÅ“uillet <nicolas@loeuillet.org> | 2017-05-16 13:09:40 +0200 |
---|---|---|
committer | Nicolas LÅ“uillet <nicolas@loeuillet.org> | 2017-05-16 13:09:40 +0200 |
commit | 322c270b6590d0d0bf5025f4782ffe7cdea0f8b0 (patch) | |
tree | e9b900edfa1ca5364820e2b326f77fb689ec6710 /docs/en/user/installation.rst | |
parent | d168fff7a9aedb19db05a95a3264e548748126c1 (diff) | |
download | wallabag-322c270b6590d0d0bf5025f4782ffe7cdea0f8b0.tar.gz wallabag-322c270b6590d0d0bf5025f4782ffe7cdea0f8b0.tar.zst wallabag-322c270b6590d0d0bf5025f4782ffe7cdea0f8b0.zip |
Removed embedded documentation
Diffstat (limited to 'docs/en/user/installation.rst')
-rw-r--r-- | docs/en/user/installation.rst | 365 |
1 files changed, 0 insertions, 365 deletions
diff --git a/docs/en/user/installation.rst b/docs/en/user/installation.rst deleted file mode 100644 index f1146b49..00000000 --- a/docs/en/user/installation.rst +++ /dev/null | |||
@@ -1,365 +0,0 @@ | |||
1 | Install wallabag | ||
2 | ================ | ||
3 | |||
4 | Requirements | ||
5 | ------------ | ||
6 | |||
7 | wallabag is compatible with **PHP >= 5.6**, including PHP 7. | ||
8 | |||
9 | .. note:: | ||
10 | |||
11 | To install wallabag easily, we provide a ``Makefile``, so you need to have the ``make`` tool. | ||
12 | |||
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 | |||
19 | curl -s https://getcomposer.org/installer | php | ||
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. | ||
24 | |||
25 | - php-session | ||
26 | - php-ctype | ||
27 | - php-dom | ||
28 | - php-hash | ||
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 | ||
39 | - php-bcmath | ||
40 | |||
41 | wallabag uses PDO to connect to the database, so you'll need one of the following: | ||
42 | |||
43 | - pdo_mysql | ||
44 | - pdo_sqlite | ||
45 | - pdo_pgsql | ||
46 | |||
47 | and its corresponding database server. | ||
48 | |||
49 | Installation | ||
50 | ------------ | ||
51 | |||
52 | On a dedicated web server (recommended way) | ||
53 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
54 | |||
55 | To install wallabag itself, you must run the following commands: | ||
56 | |||
57 | :: | ||
58 | |||
59 | git clone https://github.com/wallabag/wallabag.git | ||
60 | cd wallabag && make install | ||
61 | |||
62 | To start PHP's build-in server and test if everything did install correctly, you can do: | ||
63 | |||
64 | :: | ||
65 | |||
66 | make run | ||
67 | |||
68 | And access wallabag at http://yourserverip:8000 | ||
69 | |||
70 | .. tip:: | ||
71 | |||
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>`__. | ||
73 | |||
74 | On a shared hosting | ||
75 | ~~~~~~~~~~~~~~~~~~~ | ||
76 | |||
77 | We provide a package with all dependencies inside. | ||
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 | |||
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). | ||
83 | |||
84 | Execute this command to download and extract the latest package: | ||
85 | |||
86 | .. code-block:: bash | ||
87 | |||
88 | wget https://wllbg.org/latest-v2-package && tar xvf latest-v2-package | ||
89 | |||
90 | You will find the `md5 hash of the latest package on our website <https://static.wallabag.org/releases/>`_. | ||
91 | |||
92 | Now, read the following documentation to create your virtual host, then access your wallabag. | ||
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 | ||
96 | ~~~~~~~~~~~~~~~~~~~~~~~~ | ||
97 | |||
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. | ||
99 | |||
100 | Command to launch container | ||
101 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
102 | |||
103 | .. code-block:: bash | ||
104 | |||
105 | docker pull wallabag/wallabag | ||
106 | |||
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. | ||
111 | wallabag is packaged as a Cloudron app and available to install directly from the store. | ||
112 | |||
113 | `Install wallabag on your Cloudron <https://cloudron.io/store/org.wallabag.cloudronapp.html>`__ | ||
114 | |||
115 | Virtual hosts | ||
116 | ------------- | ||
117 | |||
118 | Configuration on Apache | ||
119 | ~~~~~~~~~~~~~~~~~~~~~~~ | ||
120 | |||
121 | Do not forget to active the *rewrite* mod of Apache | ||
122 | |||
123 | .. code-block:: bash | ||
124 | |||
125 | a2enmod rewrite && systemctl reload apache2 | ||
126 | |||
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: | ||
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> | ||
166 | |||
167 | |||
168 | .. tip:: Note for Apache 2.4, in the section `<Directory /var/www/wallabag/web>` you have to replace the directives : | ||
169 | |||
170 | :: | ||
171 | |||
172 | AllowOverride None | ||
173 | Order Allow,Deny | ||
174 | Allow from All | ||
175 | |||
176 | |||
177 | by | ||
178 | |||
179 | :: | ||
180 | |||
181 | Require All granted | ||
182 | |||
183 | |||
184 | After reloading or restarting Apache, you should now be able to access wallabag at http://domain.tld. | ||
185 | |||
186 | Configuration on Nginx | ||
187 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
188 | |||
189 | Assuming you installed wallabag in the ``/var/www/wallabag`` folder, here's the recipe for wallabag : | ||
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 | |||
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 | |||
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. | ||
231 | |||
232 | .. tip:: | ||
233 | |||
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``. | ||
235 | |||
236 | Configuration on lighttpd | ||
237 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
238 | |||
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): | ||
240 | |||
241 | :: | ||
242 | |||
243 | server.modules = ( | ||
244 | "mod_fastcgi", | ||
245 | "mod_access", | ||
246 | "mod_alias", | ||
247 | "mod_compress", | ||
248 | "mod_redirect", | ||
249 | "mod_rewrite", | ||
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 = ( | ||
270 | "^/([^?]*)(?:\?(.*))?" => "/app.php?$1&$2", | ||
271 | "^/([^?]*)" => "/app.php?=$1", | ||
272 | ) | ||
273 | |||
274 | Rights access to the folders of the project | ||
275 | ------------------------------------------- | ||
276 | |||
277 | Test environment | ||
278 | ~~~~~~~~~~~~~~~~ | ||
279 | |||
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. | ||
281 | |||
282 | Production environment | ||
283 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
284 | |||
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. | ||
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 | |||
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. | ||
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 | ||
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/ | ||
302 | * /var/www/wallabag/data/ | ||
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 | ||
311 | chown -R www-data:www-data /var/www/wallabag/data/ | ||
312 | |||
313 | otherwise, sooner or later you will see these error messages: | ||
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 | ||
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 | ||