From 96f366f5e75214db98650b00273539687baef236 Mon Sep 17 00:00:00 2001 From: kolaente Date: Mon, 6 Jul 2020 21:53:26 +0200 Subject: [PATCH] Add docs about using vikunja with utf-8 characters --- docs/config.yml | 5 + .../doc/setup/docker-start-to-finish.md | 1 + docs/content/doc/setup/full-docker-example.md | 10 ++ docs/content/doc/setup/install-backend.md | 6 + docs/content/doc/setup/install.md | 1 + docs/content/doc/setup/utf-8.md | 106 ++++++++++++++++++ 6 files changed, 129 insertions(+) create mode 100644 docs/content/doc/setup/utf-8.md diff --git a/docs/config.yml b/docs/config.yml index 2550de24..a0844e1e 100644 --- a/docs/config.yml +++ b/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 diff --git a/docs/content/doc/setup/docker-start-to-finish.md b/docs/content/doc/setup/docker-start-to-finish.md index b9b04f33..2a125374 100644 --- a/docs/content/doc/setup/docker-start-to-finish.md +++ b/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 diff --git a/docs/content/doc/setup/full-docker-example.md b/docs/content/doc/setup/full-docker-example.md index 096b7edf..d21578d1 100644 --- a/docs/content/doc/setup/full-docker-example.md +++ b/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">}}). +
+NOTE: If you intend to run Vikunja with mysql and/or to use non-latin characters +}}">make sure your db is utf-8 compatible.
+All examples on this page already reflect this and do not require additional work. +
+ ### 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 diff --git a/docs/content/doc/setup/install-backend.md b/docs/content/doc/setup/install-backend.md index c75894da..3e5507ce 100644 --- a/docs/content/doc/setup/install-backend.md +++ b/docs/content/doc/setup/install-backend.md @@ -10,6 +10,11 @@ menu: # Backend +
+NOTE: If you intend to run Vikunja with mysql and/or to use non-latin characters +}}">make sure your db is utf-8 compatible. +
+ ## 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 diff --git a/docs/content/doc/setup/install.md b/docs/content/doc/setup/install.md index 08b1fe10..3c48fbbd 100644 --- a/docs/content/doc/setup/install.md +++ b/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">}}) diff --git a/docs/content/doc/setup/utf-8.md b/docs/content/doc/setup/utf-8.md new file mode 100644 index 00000000..8c6abf07 --- /dev/null +++ b/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) +```