Add docs about using vikunja with utf-8 characters

docs/config.yml

@@ -20,6 +20,11 @@ params:
   plausibleDomain: vikunja.io
   plausibleURL: https://analytics.kolaente.de
 
+markup:
+  goldmark:
+    renderer:
+      unsafe: true
+
 menu:
   page:
     - name: Home

docs/content/doc/setup/docker-start-to-finish.md

@@ -31,6 +31,7 @@ version: '3'
 services:
   db:
     image: mariadb:10
+    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
     environment:
       MYSQL_ROOT_PASSWORD: supersecret
       MYSQL_DATABASE: vikunja

docs/content/doc/setup/full-docker-example.md

@@ -15,6 +15,12 @@ It uses an nginx container or traefik on the host to proxy backend and frontend
 
 For all available configuration options, see [configuration]({{< ref "config.md">}}).
 
+<div class="notification is-warning">
+<b>NOTE:</b> If you intend to run Vikunja with mysql and/or to use non-latin characters 
+<a href="{{< ref "utf-8.md">}}">make sure your db is utf-8 compatible</a>.<br/>
+All examples on this page already reflect this and do not require additional work.
+</div>
+
 ### Redis
 
 To use redis, you'll need to add this to the config examples below:
@@ -84,6 +90,7 @@ services:
     restart: unless-stopped
   db:
     image: mariadb:10
+    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
     environment:
       MYSQL_ROOT_PASSWORD: supersupersecret 
       MYSQL_USER: vikunja
@@ -143,6 +150,7 @@ services:
     restart: unless-stopped
   db:
     image: mariadb:10
+    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
     environment:
       MYSQL_ROOT_PASSWORD: supersupersecret 
       MYSQL_USER: vikunja
@@ -185,6 +193,7 @@ version: '3'
 services:
   db:
     image: mariadb:10
+    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
     environment:
       MYSQL_ROOT_PASSWORD: supersecret
       MYSQL_DATABASE: vikunja
@@ -238,6 +247,7 @@ version: '3'
 services:
   db:
     image: mariadb:10
+    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
     environment:
       MYSQL_ROOT_PASSWORD: supersecret
       MYSQL_DATABASE: vikunja

docs/content/doc/setup/install-backend.md

@@ -10,6 +10,11 @@ menu:
 
 # Backend
 
+<div class="notification is-warning">
+<b>NOTE:</b> If you intend to run Vikunja with mysql and/or to use non-latin characters 
+<a href="{{< ref "utf-8.md">}}">make sure your db is utf-8 compatible</a>.
+</div>
+
 ## Install from binary
 
 Download a copy of Vikunja from the [download page](https://vikunja.io/en/download/) for your architecture.
@@ -148,6 +153,7 @@ services:
       - ./files:/app/vikunja/files
   db:
     image: mariadb:10
+    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
     environment:
       MYSQL_ROOT_PASSWORD: supersecret
       MYSQL_DATABASE: vikunja

docs/content/doc/setup/install.md

@@ -30,6 +30,7 @@ This document provides an overview and instructions for the different methods.
   * [Docker]({{< ref "install-backend.md#docker">}})
   * [Debian packages]({{< ref "install-backend.md#debian-packages">}})
   * [Configuration]({{< ref "config.md">}})
+  * [UTF-8 Settings]({{< ref "utf-8.md">}})
 * [Frontend]({{< ref "install-frontend.md">}})
   * [Docker]({{< ref "install-frontend.md#docker">}})
   * [NGINX]({{< ref "install-frontend.md#nginx">}})

docs/content/doc/setup/utf-8.md

@@ -0,0 +1,106 @@
+---
+date: "2020-07-06:00:00+02:00"
+title: "UTF-8 Settings"
+draft: false
+type: "doc"
+menu:
+  sidebar:
+    parent: "setup"
+---
+
+# UTF-8 Settings
+
+Vikunja itself is always fully capable of handling utf-8 characters.
+However, your database might be not. 
+Vikunja itself will work just fine until you want to use non-latin characters in your tasks/lists/etc.
+
+On this page, you will find information about how to fully ensure non-latin characters like aüäß or emojis work 
+with your installation.
+
+## Postgresql & SQLite
+
+Postgresql and SQLite should handle utf-8 just fine - If you discover any issues nonetheless, please 
+[drop us a message](https://vikunja.io/contact/).
+
+## MySQL
+
+MySQL is not able to handle utf-8 by default.
+To fix this, follow the steps below.
+
+To find out if your db supports utf-8, run the following in a shell or similar, assuming the database 
+you're using for vikunja is called `vikunja`:
+
+{{< highlight sql >}}
+SELECT default_character_set_name FROM information_schema.SCHEMATA WHERE schema_name = 'vikunja';
+{{< /highlight >}}
+
+This will get you a result like the following:
+
+```
++----------------------------+
+| default_character_set_name |
++----------------------------+
+| latin1                     |
++----------------------------+
+1 row in set (0.001 sec)
+```
+
+The charset `latin1` means the db is encoded in the `latin1` encoding which does not support utf-8 characters.
+
+(The following guide is based on [this thread from stackoverflow](https://dba.stackexchange.com/a/104866))
+
+#### 0. Backup your database
+
+Before attempting any conversion, please [back up your database]({{< ref "backups.md">}}).
+
+#### 1. Create a pre-conversion script
+
+Copy the following sql statements in a file called `preAlterTables.sql` and replace all occurences of `vikunja` with 
+the name of your database:
+
+{{< highlight sql >}}
+use information_schema;
+SELECT concat("ALTER DATABASE `",table_schema,"` CHARACTER SET = utf8mb4 COLLATE = utf8mb4_unicode_ci;") as _sql 
+FROM `TABLES` where table_schema like 'vikunja' and TABLE_TYPE='BASE TABLE' group by table_schema;
+SELECT concat("ALTER TABLE `",table_schema,"`.`",table_name,"` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;") as _sql  
+FROM `TABLES` where table_schema like 'vikunja' and TABLE_TYPE='BASE TABLE' group by table_schema, table_name;
+SELECT concat("ALTER TABLE `",table_schema,"`.`",table_name, "` CHANGE `",column_name,"` `",column_name,"` ",data_type,"(",character_maximum_length,") CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci",IF(is_nullable="YES"," NULL"," NOT NULL"),";") as _sql 
+FROM `COLUMNS` where table_schema like 'vikunja' and data_type in ('varchar','char');
+SELECT concat("ALTER TABLE `",table_schema,"`.`",table_name, "` CHANGE `",column_name,"` `",column_name,"` ",data_type," CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci",IF(is_nullable="YES"," NULL"," NOT NULL"),";") as _sql 
+FROM `COLUMNS` where table_schema like 'vikunja' and data_type in ('text','tinytext','mediumtext','longtext');
+{{< /highlight >}}
+
+#### 2. Run the pre-conversion script
+
+Running this will create the actual migration script for your particular database structure and save it in a file called `alterTables.sql`:
+
+{{< highlight bash >}}
+mysql -uroot < preAlterTables.sql | egrep '^ALTER' > alterTables.sql
+{{< /highlight >}}
+
+#### 3. Convert the database
+
+At this point converting is just a matter of executing the previously generated sql script:
+
+{{< highlight bash >}}
+mysql -uroot < alterTables.sql
+{{< /highlight >}}
+
+#### 4. Verify it was successfully converted
+
+If everything worked as intended, your db collation should now look like this:
+
+{{< highlight sql >}}
+SELECT default_character_set_name FROM information_schema.SCHEMATA WHERE schema_name = 'vikunja';
+{{< /highlight >}}
+
+Should get you:
+
+```
++----------------------------+
+| default_character_set_name |
++----------------------------+
+| utf8mb4                    |
++----------------------------+
+1 row in set (0.001 sec)
+```