From: Nicolas Lœuillet Date: Tue, 3 May 2016 13:50:13 +0000 (+0200) Subject: Update documentation X-Git-Tag: 2.0.4~3^2~6 X-Git-Url: https://git.immae.eu/?a=commitdiff_plain;h=bba9907d1ffe993da3bc9b7e6c87169953a11160;p=github%2Fwallabag%2Fwallabag.git Update documentation --- diff --git a/docs/README.rst b/docs/README.rst deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/en/index.rst b/docs/en/index.rst index 590c234a..cd0948c2 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -8,7 +8,7 @@ wallabag documentation **wallabag** is a read-it-later application: it saves a web page by keeping content only. Elements like navigation or ads are deleted. -.. note:: +.. tip:: This documentation is about wallabag v2. If you want to read documentation for wallabag v1, `please have a look here `__. @@ -25,8 +25,8 @@ The main documentation for this application is organized into a couple sections: user/faq user/installation - user/migration user/upgrade + user/migration user/create_account user/login user/configuration diff --git a/docs/en/user/installation.rst b/docs/en/user/installation.rst index c2174a53..3057373c 100644 --- a/docs/en/user/installation.rst +++ b/docs/en/user/installation.rst @@ -34,6 +34,9 @@ and it's corresponding database server. Installation ------------ +On a dedicated web server (recommended way) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 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. Install Composer: @@ -54,7 +57,7 @@ To install wallabag itself, you must run these two commands: SYMFONY_ENV=prod composer install --no-dev -o --prefer-dist php bin/console wallabag:install --env=prod -To start php's build-in server and test if everything did install correctly, you can do: +To start PHP's build-in server and test if everything did install correctly, you can do: :: @@ -62,14 +65,48 @@ To start php's build-in server and test if everything did install correctly, you And access wallabag at http://yourserverip:8000 -.. note:: +.. tip:: 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 `__. -Installing on Apache --------------------- +On a shared hosting +~~~~~~~~~~~~~~~~~~~ + +We provide you a package with all dependancies inside. +The default configuration uses SQLite for the database. If you want to change these settings, please edit ``app/config/parameters.yml``. + +We already created a user: login and password are ``wallabag``. + +.. caution:: With this package, wallabag don't check mandatory extensions used in the application (theses checks are made during ``composer install`` when you have a dedicated web server, see above). + +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 + +Now, read the following documentation to create your virtual host, then access to 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. -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: +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 +148,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 install wallabag in the ``/var/www/wallabag`` folder, here's the recipe for wallabag : :: @@ -151,22 +188,19 @@ 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``. - Rights access to the folders of the project ------------------------------------------- - -Test Environment +Test environment ~~~~~~~~~~~~~~~~ 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. - -Production Environment +Production environment ~~~~~~~~~~~~~~~~~~~~~~ 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. @@ -180,4 +214,3 @@ This is due to the fact that we will need to grant the same rights access on the .. code-block:: bash chown -R www-data:www-data /var/www/wallabag/var - diff --git a/docs/en/user/upgrade.rst b/docs/en/user/upgrade.rst index e4735631..7782dc8a 100644 --- a/docs/en/user/upgrade.rst +++ b/docs/en/user/upgrade.rst @@ -5,6 +5,7 @@ Upgrade on a dedicated web server --------------------------------- The last release is published on https://www.wallabag.org/pages/download-wallabag.html. In order to upgrade your wallabag installation and get the last version, run the following commands in you wallabag folder (replace ``2.0.3`` by the last release number): + :: git fetch origin @@ -12,12 +13,19 @@ The last release is published on https://www.wallabag.org/pages/download-wallaba git checkout 2.0.3 SYMFONY_ENV=prod composer install --no-dev -o --prefer-dist php bin/console cache:clear --env=prod - Upgrade on a shared hosting --------------------------- -Backup your ``app/config/parameters.yml`` file. Extract the archive in your wallabag folder and replace ``app/config/parameters.yml`` with yours. +Backup your ``app/config/parameters.yml`` file. + +Download the last release of wallabag: + +.. code-block:: bash + + wget http://wllbg.org/latest-v2-package && tar xvf latest-v2-package + +Extract the archive in your wallabag folder and replace ``app/config/parameters.yml`` with yours. If you use SQLite, you must also copy your ``data/`` folder inside the new installation. diff --git a/docs/fr/index.rst b/docs/fr/index.rst index 29237721..b4275a43 100644 --- a/docs/fr/index.rst +++ b/docs/fr/index.rst @@ -9,7 +9,7 @@ Documentation de wallabag simplement d’archiver une page web en ne conservant que le contenu. Les éléments superflus (menu, publicité, etc.) sont supprimés. -.. note:: +.. tip:: Vous vous trouvez sur la documentation de wallabag v2. Si vous voulez lire la documentation de wallabag v1, `vous pouvez jeter un œil ici `__. @@ -26,6 +26,7 @@ La documentation principale de cette application est découpée en plusieurs sec user/faq user/installation + user/upgrade user/migration user/create_account user/login diff --git a/docs/fr/user/installation.rst b/docs/fr/user/installation.rst index 33a2cf5c..4645ef74 100644 --- a/docs/fr/user/installation.rst +++ b/docs/fr/user/installation.rst @@ -32,6 +32,9 @@ wallabag utilise PDO afin de se connecter à une base de données, donc vous aur Installation ------------ +Sur un serveur dédié (méthode conseillée) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + wallabag utilise un grand nombre de bibliothèques pour fonctionner. Ces bibliothèques doivent être installées à l'aide d'un outil nommé Composer. Vous devez l'installer si ce n'est déjà fait. Installation de Composer : @@ -60,13 +63,47 @@ Pour démarrer le serveur interne à php et vérifier que tout s'est installé c Et accéder wallabag à l'adresse http://lipdevotreserveur:8000 -.. note:: +.. tip:: Pour définir des paramètres via des variables d'environnement, vous pouvez les spécifier avec le préfixe ``SYMFONY__``. Par exemple, ``SYMFONY__DATABASE_DRIVER``. Vous pouvez lire `documentation Symfony `__ pour en savoir plus. -Installation avec Apache +Sur un serveur mutualisé +~~~~~~~~~~~~~~~~~~~~~~~~ + +Nous mettons à votre disposition une archive avec toutes les dépendances à l'intérieur. +La configuration par défaut utilise SQLite pour la base de données. Si vous souhaitez changer ces paramètres, vous devez modifier le fichier ``app/config/parameters.yml``. + +Nous avons déjà créé un utilisateur : le login et le mot de passe sont ``wallabag``. + +.. caution:: Avec cette archive, wallabag ne vérifie pas si les extensions obligatoires sont présentes sur votre serveur pour bien fonctionner (ces vérifications sont faites durant le ``composer install`` quand vous avez un serveur dédié, voir ci-dessus). + +Exécutez cette commande pour télécharger et décompresser l'archive : + +.. code-block:: bash + + wget http://wllbg.org/latest-v2-package && tar xvf latest-v2-package + +Maintenant, lisez la documentation ci-dessous pour crééer un virtual host. Accédez ensuite à votre installation de wallabag. +Si vous avez changé la configuration pour modifier le type de stockage (MySQL ou PostgreSQL), vous devrez vous créer un utilisateur via la commande ``php bin/console wallabag:install --env=prod``. + +Installation avec Docker ------------------------ -En imaginant que vous vouliez installer wallabag dans le dossier /var/www/wallabag et que vous utilisiez php comme un module Apache, voici un vhost pour wallabag : +Nous vous proposons une image Docker pour installer wallabag facilement. Allez voir du côté de `Docker Hub `__ pour plus d'informations. + +Commande pour démarrer le containeur +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + docker pull wallabag/wallabag + +Virtual hosts +------------- + +Configuration avec Apache +~~~~~~~~~~~~~~~~~~~~~~~~~ + +En imaginant que vous vouliez installer wallabag dans le dossier ``/var/www/wallabag`` et que vous utilisiez PHP comme un module Apache, voici un vhost pour wallabag : :: @@ -108,10 +145,10 @@ En imaginant que vous vouliez installer wallabag dans le dossier /var/www/wallab Après que vous ayez rechargé/redémarré Apache, vous devriez pouvoir avoir accès à wallabag à l'adresse http://domain.tld. -Installation avec Nginx ------------------------ +Configuration avec Nginx +~~~~~~~~~~~~~~~~~~~~~~~~ -En imaginant que vous vouliez installer wallabag dans le dossier /var/www/wallabag, voici un fichier de configuration Nginx pour wallabag : +En imaginant que vous vouliez installer wallabag dans le dossier ``/var/www/wallabag``, voici un fichier de configuration Nginx pour wallabag : :: @@ -148,22 +185,18 @@ En imaginant que vous vouliez installer wallabag dans le dossier /var/www/wallab Après que vous ayez rechargé/redémarré Nginx, vous devriez pouvoir avoir accès à wallabag à l'adresse http://domain.tld. - -.. note:: +.. tip:: Si vous voulez importer un fichier important dans wallabag, vous devez ajouter cette ligne dans votre configuration nginx ``client_max_body_size XM; # allows file uploads up to X megabytes``. - Droits d'accès aux dossiers du projet ------------------------------------- - Environnement de test ~~~~~~~~~~~~~~~~~~~~~ Quand nous souhaitons juste tester wallabag, nous lançons simplement la commande ``php bin/console server:run --env=prod`` pour démarrer l'instance wallabag et tout se passe correctement car l'utilisateur qui a démarré le projet a accès naturellement au repertoire courant, tout va bien. - Environnement de production ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -178,4 +211,3 @@ Cela est dû au fait qu'il faut aussi octroyer les mêmes droits d'accès au dos .. code-block:: bash chown -R www-data:www-data /var/www/wallabag/var - diff --git a/docs/fr/user/upgrade.rst b/docs/fr/user/upgrade.rst new file mode 100644 index 00000000..84a1692d --- /dev/null +++ b/docs/fr/user/upgrade.rst @@ -0,0 +1,32 @@ +Mettre à jour wallabag +====================== + +Mise à jour sur un serveur dédié +-------------------------------- + +La dernière version de wallabag est publiée à cette adresse : https://www.wallabag.org/pages/download-wallabag.html. Pour mettre à jour votre installation de wallabag, exécutez les commandes suivantes dans votre répertoire d'installation (remplacez ``2.0.3`` par le numéro de la dernière version) : + +:: + + git fetch origin + git fetch --tags + git checkout 2.0.3 + SYMFONY_ENV=prod composer install --no-dev -o --prefer-dist + php bin/console cache:clear --env=prod + +Mise à jour sur un hébergement mutualisé +---------------------------------------- + +Effectuez une sauvegarde du fichier ``app/config/parameters.yml``. + +Téléchargez la dernière version de wallabag : + +.. code-block:: bash + + wget http://wllbg.org/latest-v2-package && tar xvf latest-v2-package + +Décompressez l'archive dans votre répertoire d'installation et remplacez le fichier ``app/config/parameters.yml`` avec le votre. + +Si vous utilisez SQLite, vous devez également conserver le contenu du répertoire ``data/``. + +Videz le répertoire ``var/cache``.