Docs: How to restore backup #190

Author: dennissiemensma

docs/application.rst

@@ -47,7 +47,10 @@ Data preservation & backups
 
 - The SD card is by far **the weakest link** of this setup and **will** fail you some day.
 
-- The application will, by default, create a backup every night. However, as the data is still stored **locally** on your 'vulnerable' SD card, you must export it off your RaspberryPi as well. 
+- The application will, by default, create a database backup every night. 
+
+ - You can find them in the ``backups`` folder of the application. They either have a ``.sql`` or ``.gz`` extension, depending on whether compression is enabled in the backup configuration.
+ - However, as the data is still stored **locally** on your 'vulnerable' SD card, you must export it off your RaspberryPi as well. 
 
 - There is an builtin option to have backups synced to your **Dropbox**, *without exposing your Dropbox account and your private files in it*. 
 

docs/changelog.rst

@@ -25,6 +25,7 @@ v1.6.0 - 2017-xx-xx
 
 - Automatic refresh of dashboard charts (`#210 <https://github.com/dennissiemensma/dsmr-reader/issues/210>`_).
 - Extend API docs with additional example (`#185 <https://github.com/dennissiemensma/dsmr-reader/issues/185>`_).
+- Docs: How to restore backup (`#190 <https://github.com/dennissiemensma/dsmr-reader/issues/190>`_).
 
 
 

docs/faq.rst

@@ -135,8 +135,8 @@ This application displays separate tariffs by default, but supports merging them
 Just make sure that you apply the **same price to both electricity 1 and 2** and enable the option ``Merge electricity tariffs`` in the frontend configuration.
 
 
-I want to see my electricity phases as well
--------------------------------------------
+I want to see the load of each electricity phase as well
+---------------------------------------------------------
 Since ``DSMR-reader v1.5`` it's possible to track your ``P+`` (consumption) phases as well. You will need to enable this in the ``Datalogger configuration``.
 There is a setting called ``Track electricity phases``. When active, this will log the current usage of those phases and plot these on the Dashboard page.
 
@@ -171,6 +171,58 @@ The gas meter positions are only be updated once per hour (for DSMR v4).
 The Status page will give you insight in this as well.
 
 
+How do I restore a database backup?
+-----------------------------------
+
+.. warning::
+
+    Restoring a backup will replace any existing data stored in the database and is irreversible! 
+
+.. note::
+
+    Do you need a complete reinstall of DSMR-reader as well? 
+    Then please :doc:`follow the install guide<installation>` and restore the database backup **using the notes at the end of chapter 1**. 
+
+Only want to restore the database?
+
+- This asumes you are still running the same application version as the backup was created in.
+
+- Stop the application first with ``sudo supervisorctl stop all``. This will disconnect it from the database as well.
+
+For **PostgreSQL** restores::
+
+    sudo sudo -u postgres dropdb dsmrreader
+    sudo sudo -u postgres createdb -O dsmrreader dsmrreader
+    
+    # Either restore an uncompressed (.sql) backup:
+    sudo sudo -u postgres psql dsmrreader -f <PATH-TO-POSTGRESQL-BACKUP.sql>
+    
+    # OR
+    
+    # Restore a compressed (.gz) backup with:
+    zcat <PATH-TO-POSTGRESQL-BACKUP.sql.gz> | sudo sudo -u postgres psql dsmrreader
+
+
+For **MySQL** restores::
+
+    sudo mysqladmin create dsmrreader
+    sudo mysqladmin drop dsmrreader
+    
+    # Either restore an uncompressed (.sql) backup:
+    cat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql -D dsmrreader --defaults-file=/etc/mysql/debian.cnf
+    
+    # OR
+    
+    # Restore a compressed (.gz) backup with:
+    zcat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql -D dsmrreader --defaults-file=/etc/mysql/debian.cnf
+
+
+- Start the application again with ``sudo supervisorctl start all``.
+
+.. note::
+
+    In case the version differs, you can try forcing a deployment reload by: ``sudo su - dsmr`` and then executing ``./post-deploy.sh``.
+
 
 Feature/bug report
 ------------------

docs/installation.rst

@@ -87,6 +87,18 @@ Does Postgres not start due to locales? Try: ``dpkg-reconfigure locales``.  Stil
 
     sudo sudo -u postgres psql -c "alter user dsmrreader with password 'dsmrreader';"
 
+.. note::
+
+    **Optional**: Do you need to restore a **PostgreSQL** database backup as well?
+    
+    Restore an uncompressed (``.sql``) backup with::
+    
+        sudo sudo -u postgres psql dsmrreader -f <PATH-TO-POSTGRESQL-BACKUP.sql>
+
+    Or restore a compressed (``.gz``) backup with::
+    
+        zcat <PATH-TO-POSTGRESQL-BACKUP.sql.gz> | sudo sudo -u postgres psql dsmrreader
+
 
 (Option B.) MySQL/MariaDB
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -112,6 +124,18 @@ Install MariaDB. You can also choose to install the closed source MySQL, as they
 
     sudo mysqladmin reload --defaults-file=/etc/mysql/debian.cnf
 
+.. note::
+
+    **Optional**: Do you need to restore a **MySQL** database backup as well?
+    
+    Restore an uncompressed (``.sql``) backup with::
+    
+        cat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql -D dsmrreader --defaults-file=/etc/mysql/debian.cnf
+
+    Or restore a compressed (``.gz``) backup with::
+    
+        zcat <PATH-TO-MYSQL-BACKUP.sql.gz> | sudo mysql -D dsmrreader --defaults-file=/etc/mysql/debian.cnf
+
 
 2. Dependencies
 ---------------

docs/locale/nl/LC_MESSAGES/application.mo

@@ -2,8 +2,8 @@ msgid ""
 msgstr ""
 "Project-Id-Version: DSMR Reader v1.x\n"
 "Report-Msgid-Bugs-To: Dennis Siemensma <github@dennissiemensma.nl>\n"
-"POT-Creation-Date: 2016-01-01 00:00+0100\n"
-"PO-Revision-Date: 2017-01-01 14:30+0100\n"
+"POT-Creation-Date: 2017-01-03 20:39+0100\n"
+"PO-Revision-Date: 2017-01-03 20:41+0100\n"
 "Last-Translator: Dennis Siemensma <github@dennissiemensma.nl>\n"
 "Language-Team: Dennis Siemensma <github@dennissiemensma.nl>\n"
 "MIME-Version: 1.0\n"
@@ -117,16 +117,29 @@ msgstr ""
 "gegarandeerd kapot** op een dag."
 
 #: ../../application.rst:50
+msgid "The application will, by default, create a database backup every night."
+msgstr "De applicatie maakt standaard elke nacht een back-up."
+
+#: ../../application.rst:52
 msgid ""
-"The application will, by default, create a backup every night. However, as the "
-"data is still stored **locally** on your 'vulnerable' SD card, you must export "
-"it off your RaspberryPi as well."
+"You can find them in the ``backups`` folder of the application. They either "
+"have a ``.sql`` or ``.gz`` extension, depending on whether compression is "
+"enabled in the backup configuration."
 msgstr ""
-"De applicatie maakt standaard elke nacht een back-up. Echter, hiermee staan de "
-"gegevens nog steeds **lokaal** op je 'kwestsbare' SD-kaart. Je zult die data "
-"dus moeten kopieren naar een locatie buiten je RaspberryPi om."
+"Je kunt ze terugvinden in de ``backups`` map van de applicatie. Ze zijn te "
+"herkennen aan een ``.sql`` of ``.gz`` extensie, afhankelijk de gekozen "
+"compressie-instellingen in de back-upconfiguratie."
 
-#: ../../application.rst:52
+#: ../../application.rst:53
+msgid ""
+"However, as the data is still stored **locally** on your 'vulnerable' SD card, "
+"you must export it off your RaspberryPi as well."
+msgstr ""
+"Echter, hiermee staan de gegevens nog steeds **lokaal** op je 'kwestsbare' SD-"
+"kaart. Je zult die data dus moeten kopieren naar een locatie buiten je "
+"RaspberryPi om."
+
+#: ../../application.rst:55
 msgid ""
 "There is an builtin option to have backups synced to your **Dropbox**, *without "
 "exposing your Dropbox account and your private files in it*."
@@ -135,20 +148,20 @@ msgstr ""
 "uploaden. *Zonder dat de applicatie toegang tot je (privé) bestanden in je "
 "Dropbox-account heeft*."
 
-#: ../../application.rst:54
+#: ../../application.rst:57
 msgid ""
 "Please either use this service or manage offloading backups on your own (see "
 "below)."
 msgstr ""
 "Zorg ervoor dat je ofwel deze feature gebruikt ofwel zelf back-ups maakt en ze "
 "regelmatig ergens heen kopieert (zie hieronder)."
 
-#: ../../application.rst:56
+#: ../../application.rst:59
 msgid "You may also decide to run backups outside the application."
 msgstr ""
 "Je kunt er tevens voor kiezen om zelf backups buiten de applicatie om te maken."
 
-#: ../../application.rst:58
+#: ../../application.rst:61
 msgid ""
 "There are example backup scripts available in ``dsmrreader/provisioning/"
 "postgresql/psql-backup.sh`` for **PostgreSQL**, which I dump to a separately "
@@ -159,23 +172,23 @@ msgstr ""
 "handmatig een back-up te maken naar een USB-stick die aan mijn RaspberryPi "
 "hangt."
 
-#: ../../application.rst:60
+#: ../../application.rst:63
 msgid ""
 "For **MySQL/MariaDB** you can use ``dsmrreader/provisioning/mysql/mysql-backup."
 "sh``."
 msgstr ""
 "Voor **MySQL/MariaDB** kun je dit script gebruiken: ``dsmrreader/provisioning/"
 "mysql/mysql-backup.sh``."
 
-#: ../../application.rst:62
+#: ../../application.rst:65
 msgid ""
 "Make sure to schedule the backup scripts as cronjob and also verify that it "
 "actually works, by running ``run-parts -v /etc/cron.daily``."
 msgstr ""
 "Zorg ervoor dat je de back-ups via een 'daily cronjob' hebt ingepland en test "
 "dat door het volgende uit te voeren:  ``run-parts -v /etc/cron.daily``."
 
-#: ../../application.rst:64
+#: ../../application.rst:67
 msgid ""
 "Also, check your free disk space once in a while. I will implement automatic "
 "cleanup settings later, allowing you to choose your own retention (for all the "
@@ -185,43 +198,43 @@ msgstr ""
 "mogelijkheid toevoegen om oude metingen (niet de dagtotalen) te verwijderen na "
 "een X-periode."
 
-#: ../../application.rst:66
+#: ../../application.rst:69
 msgid ""
 "Everything OK? Congratulations, this was the hardest part and now the fun "
 "begins by monitoring your energy consumption."
 msgstr ""
 "Alles gelukt? Gefeliciteerd! Dit was het lastigste gedeelte en nu kun je "
 "eindelijk gebruikmaken van de applicatie en je energieverbruik meten."
 
-#: ../../application.rst:70
+#: ../../application.rst:73
 msgid "Application updates (bug fixes & new features)"
 msgstr "Applicatie updates (bugfixes & nieuwe mogelijkheden)"
 
-#: ../../application.rst:74
+#: ../../application.rst:77
 msgid ":doc:`This information can be found here<faq>`."
 msgstr ":doc:`Deze informatie kun je hier terugvinden<faq>`."
 
-#: ../../application.rst:78
+#: ../../application.rst:81
 msgid "Public webinterface warning"
 msgstr "Waarschuwing voor publiekelijke toegang"
 
-#: ../../application.rst:82
+#: ../../application.rst:85
 msgid ""
 "If you expose your application to the outside world or a public network, you "
 "might want to take additional steps:"
 msgstr ""
 "Wanneer je de applicatie koppelt aan het Internet wil je sowieso extra "
 "maatregelen nemen:"
 
-#: ../../application.rst:84
+#: ../../application.rst:87
 msgid ""
 "Please make sure to **alter** the ``SECRET_KEY`` setting in your ``dsmrreader/"
 "settings.py``."
 msgstr ""
 "Zorg ervoor dat je de instelling ``SECRET_KEY`` wijzigt in het bestand "
 "``dsmrreader/settings.py``."
 
-#: ../../application.rst:86
+#: ../../application.rst:89
 msgid ""
 "Don't forget to run ``./post-deploy.sh`` in the project's root, which will "
 "force the application to gracefully reload itself and apply the new settings "
@@ -231,7 +244,7 @@ msgstr ""
 "hoogste map van project), die ervoor zorgt dat de hele applicatie zichzelf "
 "herlaadt en daarmee de nieuwe instellingen per direct gebruikt."
 
-#: ../../application.rst:88
+#: ../../application.rst:91
 msgid ""
 "Install a firewall, such as ``ufw`` `UncomplicatedFirewall <https://wiki.ubuntu."
 "com/UncomplicatedFirewall>`_ and restrict traffic to port ``22`` (only for "
@@ -241,7 +254,7 @@ msgstr ""
 "ubuntu.com/UncomplicatedFirewall>`_) and beperk al het toegestane verkeer tot "
 "poort ``22`` (puur voor jezelf) en poort ``80``."
 
-#: ../../application.rst:90
+#: ../../application.rst:93
 msgid ""
 "You should also have Nginx restrict application access when exposing it to the "
 "Internet. Simply generate an htpasswd string `using one of the many generators "
@@ -252,7 +265,7 @@ msgstr ""
 "tekenreeks via `een van de vele websites die dit voor je kunnen doen <https://"
 "www.transip.nl/htpasswd/>`_."
 
-#: ../../application.rst:94
+#: ../../application.rst:97
 msgid ""
 "It's safe to a htpasswd generator, **just make sure to NEVER enter personal "
 "credentials** there **used for other applications or personal accounts**."
@@ -261,27 +274,27 @@ msgstr ""
 "persoonlijke informatie of gegevens invoert die je ook op andere websites "
 "gebruikt**!"
 
-#: ../../application.rst:96
+#: ../../application.rst:99
 msgid "Paste the htpasswd string in ``/etc/nginx/htpasswd``."
 msgstr "Plak de htpasswd-tekenreeks in het bestand ``/etc/nginx/htpasswd``."
 
-#: ../../application.rst:98
+#: ../../application.rst:101
 msgid ""
 "Open the site's vhost in ``/etc/nginx/sites-enabled/dsmr-webinterface`` and "
 "**uncomment** the following lines (remove the ##)::"
 msgstr ""
 "Open de website's vhost in ``/etc/nginx/sites-enabled/dsmr-webinterface`` en "
 "schakel de volgende regels in (verwijder de ## tekens)::"
 
-#: ../../application.rst:103
+#: ../../application.rst:106
 msgid "Now make sure you didn't insert any typo's by running::"
 msgstr "Zorg ervoor dat je geen typefouten hebt gemaakt door te controleren met::"
 
-#: ../../application.rst:107
+#: ../../application.rst:110
 msgid "And reload with::"
 msgstr "En herlaad met::"
 
-#: ../../application.rst:111
+#: ../../application.rst:114
 msgid ""
 "You should be prompted for login credentials the next time your browser "
 "accesses the application. For more information regarding this topic, see the "