Merge ~ubuntu-docker-images/ubuntu-docker-images/+git/mysql:readme into ~ubuntu-docker-images/ubuntu-docker-images/+git/mysql:edge

[Lucas Kanashiro]

Improve README.

[Sergio Durigan Junior (sergiodj)]

I'm reviewing this one.

[Sergio Durigan Junior (sergiodj)]

Thanks for the MP, Lucas. Just small nits to fix; otherwise it's ready to be pushed.

review: Needs Fixing

[Lucas Kanashiro (lucaskanashiro)]

Thanks again Sergio. Comments addressed. Merging it and updating DockerHub page.

review: Approve

diff --git a/HACKING.md b/HACKING.md
 new file mode 100644
index 0000000..662c988
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,14 @@
+# Contributing
+
+In order to contribute to the MySQL OCI image do the following:
+
+* Create a new branch.
+* Make your changes. Keep your commits logically separated. If it is fixing a bug do not forget to mention it in the commit message.
+* Build a new image with your changes. You can use the following command:
+
+```
+$ docker build -t squeakywheel/mysql:test -f Dockerfile .
+```
+
+* Test the new image. Run it in some way that exercises your changes, you can also check th README.md file.
+* If everything goes well submit a merge proposal.
diff --git a/README.md b/README.md
index 7056b37..4a45fdb 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,199 @@
-## Ubuntu MySQL 8.0 OCI image
+# MySQL | Ubuntu
 
-This is a fork of upstream's mysql image from https://github.com/docker-library/mysql
+## About MySQL
 
-These are the main changes:
-- using Ubuntu Focal 20.04 LTS as the layer
-- installing MySQL 8.0 from Ubuntu Focal 12.04 LTS
-- amd64 only at the moment
+MySQL is a fast, stable and true multi-user, multi-threaded SQL database
+server. SQL (Structured Query Language) is the most popular database query
+language in the world. The main goals of MySQL are speed, robustness and ease
+of use.
 
-The entrypoint and environment variables were not changed.
+## Tags
 
-Bugs? Comments? Get in touch with the Ubuntu Server team at
-https://discourse.ubuntu.com/c/server/
+- `8.0.22-focal`, `8.0.22`, `8.0-focal`, `8.0``8-focal`, `8`, `focal`, `beta` - **/!\ this is a beta release**
 
+### Architectures supported
+
+- `amd64`, `arm64`, `s390x`
+
+## Usage
+
+### Docker CLI
+
+```sh
+$ docker network create mysql-net
+# Run the server
+$ docker run --name mysql-instance --network mysql-net --env MYSQL_ROOT_PASSWORD=My$seCret --detach squeakywheel/mysql:edge
+# Run the client
+$ docker run --interactive --tty --rm --network mysql-net squeakywheel/mysql:edge mysql -hmysql-instance -Uroot -p
+```
+
+The password will be asked and you can enter `My$seCret`. Now, you are logged in and can enjoy your new instance.
+
+Since containers are ephemeral you might be interested in persist data and not initialize a new database every time you launch a new container. To do that you can use docker volumes:
+
+```sh
+$ docker run --name mysql --volume /path/to/persisted/data:/var/lib/mysql --env MYSQL_RANDOM_ROOT_PASSWORD squeakywheel/mysql:edge
+```
+
+#### Parameters
+
+| Parameter | Description |
+|---|---|
+| `-e TZ=UTC` | Timezone |
+| `-e MYSQL_ROOT_PASSWORD=secret_for_root` | Set the password for the `root` user. This option is **mandatory** and **must not be empty**. |
+| `-e MYSQL_PASSWORD=secret` | Set the password for the `MYSQL_USER` user. |
+| `-e MYSQL_USER=john` | Create a new user with superuser privileges. This is used in conjunction with `MYSQL_PASSWORD` |
+| `-e MYSQL_DATABASE=db_test` | Set the name of the default database. |
+| `-e MYSQL_ALLOW_EMPTY_PASSWORD=yes` | Set up a blank password for the `root` user. **This is not recommended to be used in production, make sure you know what you are doing**. |
+| `-e MYSQL_RANDOM_ROOT_PASSWORD=yes` | Generate a random initial password for the `root` user using `pwgen`. It will be printed in the logs, search for `GENERATED ROOT PASSWORD`. |
+| `-e MYSQL_ONETIME_PASSWORD=yes` | Set `root` user as experide once initialization is complete, forcing a password change on first login. |
+| `-e MYSQL_INITSB_SKIP_TZINFO=yes` | Timezone data is automatically loaded via entrypoint script, set this variable to any non-empty value to disable it. | 
+
+#### Initialization Scripts
+
+One can also add initialization scripts to their containers. This includes `*.sql`, `.sql.gz`, and `*.sh` scripts, and you just need to put them inside the  `/docker-entrypoint-initdb.d` directory inside the container. After MySQL initialization is done and the default database and user are created, the scripts are executed in the following order:
+
+* Run any `*.sql` files in alphabetically order. By default the target database is specified via `MYSQL_DATABASE`.
+* Run any executable `*.sh` scripts in alphabetically order.
+* Source any non-executable `*.sh` scripts in alphabetically order.
+
+All of this is done before the MySQL service is started. Keep in mind if your database directory is not empty (contains pre-existing database) they will be left untouched.
+
+#### Database Configuration
+
+You can pass your own configuration files to the container doing the following:
+
+```sh
+$ docker run --name mysql --volume /path/to/mysql/config/files/:/etc/mysql/mysql.conf.d/ --env MYSQL_ROOT_PASSWORD=P@sSwd squeakywheel/mysql:edge
+```
+
+#### Debugging
+
+In case you need to debug what it is happening with the container you can run `docker logs <name_of_the_container>`. But if you want to get access to an interactive shell run:
+
+```sh
+$ docker exec -it <name_of_the_container> /bin/bash
+```
+
+To see how to use the MySQL OCI image with `docker-compose` and `kubernetes` check the `examples/README.md` file.
+
+## Deploy with Kubernetes
+
+You can use your favorite Kubernetes distribution; if you don't have one, consider [installing MicroK8s](https://microk8s.io/).
+
+With microk8s running, enable the `dns` and `storage` add-ons:
+```sh
+$ microk8s enable dns storage
+ ```
+
+Create a configmap for the configuration file (write your `my.cnf` file based on the upstream documentation [here](https://dev.mysql.com/doc/refman/8.0/en/mysql-command-options.html)):
+
+```sh
+$ microk8s kubectl create configmap mysql-config --from-file=main-config=config/my-custom.cnf
+```
+
+Use the sample deployment yaml provided [here](https://git.launchpad.net/~canonical-server/ubuntu-server-oci/+git/mysql/plain/examples/mysql-deployment.yml).
+
+<details>
+  <summary>Apply the `mysql-deployment.yml` (click to expand)</summary>
+
+```yaml
+# mysql-deployment.yml
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: mysql-volume-claim
+spec:
+  accessModes:
+    - ReadWriteOnce
+  storageClassName: microk8s-hostpath
+  resources:
+    requests:
+      storage: 500M
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mysql-deployment
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: mysql
+  template:
+    metadata:
+      labels:
+        app: mysql
+    spec:
+      containers:
+      - name: mysql
+        image: squeakywheel/mysql:edge
+        env:
+        - name: MYSQL_RANDOM_ROOT_PASSWORD
+          value: "yes"
+        - name: MYSQL_PASSWORD
+          value: "myS&cret"
+        - name: MYSQL_USER
+          value: "john"
+        volumeMounts:
+        - name: mysql-config-volume
+          mountPath: /etc/mysql/mysql.conf.d/my-custom.cnf
+          subPath: my-custom.cnf
+        - name: mysql-data
+          mountPath: /var/lib/mysql
+        ports:
+        - containerPort: 3306
+          name: mysql
+          protocol: TCP
+      volumes:
+        - name: mysql-config-volume
+          configMap:
+            name: mysql-config
+            items:
+            - key: main-config
+              path: my-custom.cnf
+        - name: mysql-data
+          persistentVolumeClaim:
+            claimName: mysql-volume-claim
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: mysql-service
+spec:
+  type: NodePort
+  selector:
+    app: mysql
+  ports:
+  - protocol: TCP
+    port: 3306
+    targetPort: 3306
+    nodePort: 30306
+    name: mysql
+```
+
+</details>
+
+```sh
+$ microk8s kubectl apply -f mysql-deployment.yml
+```
+
+You will now be able to connect to the MySQL server on `localhost:30306`.
+
+## Bugs and Features request
+
+If you find a bug in our image or want to request a specific feature file a bug here:
+
+https://bugs.launchpad.net/ubuntu-server-oci/+filebug
+
+In the title of the bug add `mysql: <reason>`.
+
+Make sure to include:
+
+* The digest of the image you are using, you can find it using this command replacing `<tag>` with the one you used to run the image:
+```sh
+$ docker images --no-trunc --quiet squeakywheel/mysql:<tag>
+```
+* Reproduction steps for the deployment
+* If it is a feature request, please provide as much detail as possible
diff --git a/examples/README.md b/examples/README.md
 new file mode 100644
index 0000000..b07a46b
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,44 @@
+# Running the examples
+
+## docker-compose
+
+Install `docker-compose` from the Ubuntu archive:
+
+```
+$ sudo apt install -y docker-compose
+```
+
+Call `docker-compose` from the examples directory:
+
+```
+$ docker-compose up -d
+```
+
+MySQL will be running and available via port `3306` on your host. The password of the `john` user will be `myS&cret`. To stop it run:
+
+```
+$ docker-compose down
+```
+
+# Microk8s
+
+With microk8s running, enable the `dns` and `storage` add-ons:
+
+```
+$ microk8s enable dns storage
+```
+
+Create a configmap for the configuration files:
+
+```
+$ microk8s kubectl create configmap mysql-config \
+		--from-file=main-config=config/my-custom.cnf
+```
+
+Apply the `mysql-deployment.yml`:
+
+```
+$ microk8s kubectl apply -f mysql-deployment.yml
+```
+
+MySQL will be running and available via port `30306` on your host. The password of the `john` user will be `myS&cret`.
diff --git a/examples/config/my-custom.cnf b/examples/config/my-custom.cnf
 new file mode 100644
index 0000000..8e55230
--- /dev/null
+++ b/examples/config/my-custom.cnf
@@ -0,0 +1,3 @@
+[mysqld]
+bind-address = 0.0.0.0
+port = 3306
diff --git a/examples/docker-compose.yml b/examples/docker-compose.yml
 new file mode 100644
index 0000000..ec0ea8f
--- /dev/null
+++ b/examples/docker-compose.yml
@@ -0,0 +1,14 @@
+version: '2'
+
+services:
+    mysql:
+        image: squeakywheel/mysql:edge
+        network_mode: "host"
+        ports:
+            - 3306:3306
+        environment:
+            - MYSQL_RANDOM_ROOT_PASSWORD=yes
+            - MYSQL_PASSWORD=myS&cret
+            - MYSQL_USER=john
+        volumes:
+            - ./config/my-custom.cnf:/etc/mysql/mysql.conf.d/my-custom.cnf
diff --git a/examples/mysql-deployment.yml b/examples/mysql-deployment.yml
 new file mode 100644
index 0000000..2a30022
--- /dev/null
+++ b/examples/mysql-deployment.yml
@@ -0,0 +1,72 @@
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: mysql-volume-claim
+spec:
+  accessModes:
+    - ReadWriteOnce
+  storageClassName: microk8s-hostpath
+  resources:
+    requests:
+      storage: 500M
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mysql-deployment
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: mysql
+  template:
+    metadata:
+      labels:
+        app: mysql
+    spec:
+      containers:
+      - name: mysql
+        image: squeakywheel/mysql:edge
+        env:
+        - name: MYSQL_RANDOM_ROOT_PASSWORD
+          value: "yes"
+        - name: MYSQL_PASSWORD
+          value: "myS&cret"
+        - name: MYSQL_USER
+          value: "john"
+        volumeMounts:
+        - name: mysql-config-volume
+          mountPath: /etc/mysql/mysql.conf.d/my-custom.cnf
+          subPath: my-custom.cnf
+        - name: mysql-data
+          mountPath: /var/lib/mysql
+        ports:
+        - containerPort: 3306
+          name: mysql
+          protocol: TCP
+      volumes:
+        - name: mysql-config-volume
+          configMap:
+            name: mysql-config
+            items:
+            - key: main-config
+              path: my-custom.cnf
+        - name: mysql-data
+          persistentVolumeClaim:
+            claimName: mysql-volume-claim
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: mysql-service
+spec:
+  type: NodePort
+  selector:
+    app: mysql
+  ports:
+  - protocol: TCP
+    port: 3306
+    targetPort: 3306
+    nodePort: 30306
+    name: mysql