Update documentation to introduce migration scripts.

BREAKING.md

@@ -2,19 +2,49 @@ Breaking changes
 ================
 
 Since Authelia is still under active development, it is subject to breaking changes. We then recommend you don't blindly use the latest
-Docker image but pick a version instead and check this file before upgrading. This is where you will get information about breaking changes and about what you should do to overcome those changes.
+Docker image but pick a version instead and read this documentation before upgrading. This is where you will get information about breaking
+changes and about what you should do to overcome those changes.
 
 ## Breaking in v4.0.0
 
-Authelia has been rewritten in Go for better performance and reliability.
+Authelia has been rewritten in Go for better code maintainability and for performance and security reasons.
 
-### Model of U2F devices
+The principles stay the same, Authelia is still an authenticating and authorizing proxy. Some major changes have been made though so
+that the system is more reliable overall. This induced breaking the previous data model and the configuration to bring new features
+but fortunately migration tools are provided to ease the task.
 
-The model of U2F devices has been updated to better fit with the Go library handling U2F keys.
+### Migration tools
 
-### Removal of flag secure for SMTP notifier
+An authelia-scripts command is provided to perform the data model migration from a local database
+or a mongo database created by Authelia v3 into a target SQL database (sqlite3, mysql, postgres)
+supported by Authelia v4.
 
-The go library for sending e-mails automatically switch to TLS if possible according to https://golang.org/pkg/net/smtp/#SendMail.
+Example of usage:
+
+    # Migrate a local database into the targeted database defined in config-v4.yml
+    authelia-scripts migrate local --config=/path/to/config-v4.yml --db-path=/old/db/path
+
+    # Migrate a mongo database into the targeted database defined in config-v4.yml
+    authelia-scripts migrate mongo --config=/path/to/config-v4.yml --url=mongodb://myuser:mypassword@mymongo:27017 --database=authelia
+
+
+Those commands migrate TOTP secrets, U2F devices, authentication traces and user preferences so
+that the migration is almost seamless for your users.
+
+The identity verification tokens are not migrated though since their format has changed. However they were
+made to expire after a few minutes anyway. Consequently, the users who initiated a device registration process
+which has not been completed before the migration will have to restart the device registration process for their
+device. This is because their identity verification token will not be usable in v4.
+
+### Major changes in details:
+
+* The configuration mostly remained the same, only one major key has been added: `jwt_secret` and one key removed: `secure` from the
+SMTP notifier as the Go SMTP library default to TLS if available.
+* The local storage used for dev purpose was a `nedb` database which was implementing the same interface
+as mongo but was not really standard. It has been replaced by a good old sqlite3 database.
+* The model of the database is not compatible with v3. This has been decided to better fit with Golang libraries.
+* Some features have been upgraded such as U2F in order to use the latest security features available like allowing device cloning detection.
+* Furthermore, a top-notch web server implementation (fasthttp) has been selected to allow a large performance gain in order to use Authelia in demanding environments.
 
 ## Breaking in v3.14.0
 

CHANGELOG.md

@@ -4,9 +4,13 @@ Release Notes - Version 4.0.0
 * config.yml should include a secret for jwt issuance and verification.
 * Models in database have been updated to better fit with the Go library.
 * The local storage has been replaced by a good old sqlite3 database.
+* The mongo option for storing user preferences and device secrets has been deprecated in favor of SQL options: mysql and postgres.
 * The "secure" flag from the SMTP notifier configuration has been removed as TLS is used by default when available.
 * authelia-scripts tool has been rewritten in Go.
-* Use pure implementation of crypt to avoid CGO and dependency to libc.
+* Use pure implementation of crypt.
+* Introduction of a "migrate" command to authelia-scripts to help migrating from v3 to v4.
+* Authelia is built and available on Dockerhub in 3 flavors: amd64, arm32v7 and arm64v8.
+* Introduction of suites in Go.
 
 Release Notes - Version 3.16.3
 ------------------------------

README.md

@@ -14,7 +14,7 @@ It acts as a companion of reverse proxies like [nginx] or [Traefik] by handling
 
     BREAKING NEWS: Authelia v4 release is coming soon! The new version is written in Go for reliability, performance and security improvements.
     It is currently available in beta in master.
-    Please read AUTHELIA-V4.md if you want to migrate from v3 to v4. But note that the data model migration is not automated yet.
+    Please read BREAKING.md if you want to migrate from v3 to v4. Otherwise, start fresh in v4 and enjoy!
 
 
 <p align="center">

cmd/authelia-scripts/cmd_bootstrap.go

@@ -224,6 +224,7 @@ func Bootstrap(cobraCmd *cobra.Command, args []string) {
 	bootstrapPrintln("Preparing /etc/hosts to serve subdomains of example.com...")
 	prepareHostsFile()
 
+	fmt.Println()
 	bootstrapPrintln("Run 'authelia-scripts suites setup Standalone' to start Authelia and visit https://home.example.com:8080.")
 	bootstrapPrintln("More details at https://github.com/clems4ever/authelia/blob/master/docs/getting-started.md")
 }