Merge pull request #1 from lando/tests

Add in library and testing

.github/workflows/pr-mysql-tests.yml

@@ -0,0 +1,79 @@
+name: MySQL Tests
+
+on:
+  pull_request:
+
+jobs:
+  leia-tests:
+    runs-on: ${{ matrix.os }}
+    env:
+      TERM: xterm
+    strategy:
+      matrix:
+        lando-versions:
+          - edge
+        os:
+          - ubuntu-20.04
+        node-version:
+          - '14'
+        leia-tests:
+          - examples/5.7
+          - examples/8.0
+          - examples/custom
+    steps:
+      # Install deps and cache
+      # Eventually it would be great if these steps could live in a separate YAML file
+      # that could be included in line to avoid code duplication
+      - name: Checkout code
+        uses: actions/checkout@v2
+      - name: Install node ${{ matrix.node-version }}
+        uses: actions/setup-node@v2
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Get Yarn cache directory
+        id: yarn-cache-dir-path
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - name: Use Yarn cache
+        uses: actions/cache@v2
+        id: yarn-cache
+        with:
+          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ matrix.node-version }}-${{ hashFiles('**/yarn.lock') }}
+      - name: Install Yarn dependencies
+        run: yarn install --prefer-offline --frozen-lockfile
+
+      # This block should eventually become use lando/actions-hyperdrive@v2
+      - name: Verify Docker dependencies
+        run: |
+          docker --version | grep "20.10."
+          docker-compose --version | grep "1.29."
+      - name: Grab latest edge Lando CLI
+        run: |
+          sudo curl -fsSL -o /usr/local/bin/lando "https://files.lando.dev/cli/lando-linux-x64-${{ matrix.lando-versions }}"
+          sudo chmod +x /usr/local/bin/lando
+      - name: Move in lando config appropriate for testing
+        run: |
+          mkdir -p ~/.lando/cache
+          cp -f actions-lando-config.yml ~/.lando/config.yml
+          echo false > ~/.lando/cache/report_errors
+          lando --clear
+      - name: Verify Lando works and we are dogfooding this plugin for tests
+        run: |
+          lando version
+          lando config --path plugins | grep mysql | grep /home/runner/work/mysql/mysql || echo "::error:: Not dogfooding this plugin correctly! "
+
+      # This block should eventually become use lando/actions-leia@v2
+      # @NOTE? Do we want a way for our leia-action to configure apparmor since
+      # this might break a whole bunch of tests? or is this literally just a thing
+      # for the Lagoon mysql/mariadb container?
+      - name: Configure apparmor
+        run: |
+          set -x
+          sudo apt-get remove mysql-server --purge
+          sudo apt-get install apparmor-profiles
+          sudo apparmor_parser -R /etc/apparmor.d/usr.sbin.mysqld
+
+      # This block should eventually become use lando/actions-leia@v2
+      - name: Run leia tests
+        shell: bash
+        run: yarn leia "./${{ matrix.leia-tests }}/README.md" -c 'Destroy tests' --stdin --shell bash

README.md

@@ -1,17 +1,74 @@
-# Plugin Template
-
-Use this repo as a template for creating Lando plugins.
-
-## Steps
-
-1. Copy this repo into your new plugin repo
-2. Change the items marked CHANGEME to the name of this plugin in the following files:
-    * docs/config.js
-    * docs/README.md
-    * .lando.yml
-    * actions-lando-config.yml
-    * plugin.yml
-    * package.json
-3. Add in your files or migrate the files from another plugin.
-4. Add in your testing examples and add them to .github/workflows
-5. PROFIT!
+# Lando MySQL Plugin
+
+The lando MySQL plugin service.
+
+## Installation
+
+```bash
+# With npm
+npm install @lando/mysql
+
+# With yarn
+yarn add @lando/mysql
+```
+
+## Issues, Questions and Support
+
+If you have a question or would like some community support we recommend you [join us on Slack](https://launchpass.com/devwithlando). Note that this is the Slack community for [Lando](https://lando.dev) but we are more than happy to help with this module as well!
+
+If you'd like to report a bug or submit a feature request then please [use the issue queue](https://github.com/lando/mysql/issues/new/choose) in this repo.
+
+## Changelog
+
+We try to log all changes big and small in both [THE CHANGELOG](https://github.com/lando/mysql/blob/main/CHANGELOG.md) and the [release notes](https://github.com/lando/mysql/releases).
+
+
+## Development
+
+* Requires [Node 14+](https://nodejs.org/dist/latest-v14.x/)
+* Prefers [Yarn](https://classic.yarnpkg.com/lang/en/docs/install)
+
+```bash
+git clone https://github.com/lando/mysql.git && cd mysql
+yarn install
+```
+
+If you dont' want to install Node 14 or Yarn for whatever reason you can install [Lando](https://docs.lando.dev/basics/installation.html) and use that:
+
+```bash
+git clone https://github.com/lando/mysql.git && cd mysql
+# Install deps and get node
+lando start
+
+# Run commands
+lando node
+lando yarn
+```
+
+## Testing
+
+```bash
+# Lint the code
+yarn lint
+
+# Run unit tests
+yarn test
+```
+
+## Releasing
+
+```bash
+yarn release
+```
+
+## Contributors
+
+<a href="https://github.com/lando/mysql/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=lando/mysql" />
+</a>
+
+Made with [contributors-img](https://contrib.rocks).
+
+## Other Resources
+
+* [Important advice](https://www.youtube.com/watch?v=WA4iX5D9Z64)

docs/usage.md

@@ -1,5 +1,146 @@
 ---
-description: todo
+description: Add a highly configurable MySQL service to Lando for local development with all the power of Docker and Docker Compose.
 ---
 
-@TODO Add usage docs.
+# MySQL
+
+[MySQL](https://www.mysql.com/) is a very common database server.
+
+You can easily add it to your Lando app by adding an entry to the [services](https://docs.lando.dev/config/services.html) top-level config in your [Landofile](https://docs.lando.dev/config/lando.html).
+
+[[toc]]
+
+## Supported versions
+
+*   [8.0](https://hub.docker.com/r/bitnami/mysql)
+*   **[5.7](https://hub.docker.com/r/bitnami/mysql)** **(default)**
+*   [custom](https://docs.lando.dev/config/services.html#advanced)
+
+## Patch versions
+
+::: warning Not officially supported!
+While we allow users to specify patch versions for this service they are not *officially* supported so if you use one, YMMV.
+:::
+
+To use a patch version, you can do something as shown below:
+
+```yaml
+services:
+  myservice:
+    type: mysql:5.7.24
+```
+
+But make sure you use one of the available [patch tags](https://hub.docker.com/r/bitnami/mysql/tags) for the underlying image we are using.
+
+## Configuration
+
+Here are the configuration options, set to the default values, for this service. If you are unsure about where this goes or what this means, we *highly recommend* scanning the [services documentation](https://docs.lando.dev/config/services.html) to get a good handle on how the magicks work.
+
+Also note that options, in addition to the [build steps](https://docs.lando.dev/config/services.html#build-steps) and [overrides](https://docs.lando.dev/config/services.html#overrides) that are available to every service, are shown below:
+
+::: warning Be careful when switching database type, version or credentials!
+You should be careful switching database `type`, `version` or `creds`.
+
+In the case of type and version, the underlying database files between these things will likely not be compatible. In the case of credentials, these are set when the container is **initially created** so in order to change them you need to `lando destroy && lando start`. Note that `lando destroy` will delete all the data in your database.
+
+
+**Ignoring this warning can prevent your database from starting**
+:::
+
+```yaml
+services:
+  myservice:
+    type: mysql:5.7
+    portforward: false
+    creds:
+      user: mysql
+      password: mysql
+      database: database
+    config:
+      database: SEE BELOW
+    # This setting only works on mysql:8.0
+    authentication: caching_sha2_password
+```
+
+### Port forwarding
+
+`portforward` will allow you to access this service externally by assigning a port directly on your host's `localhost`. Note that ` portforward` can be set to either `true` or a specific `port` but we *highly recommend* you set it to `true` unless you have pretty good knowledge of how port assignment works or you have a **very** compelling reason for needing a locked down port.
+
+`portforward: true` will prevent inevitable port collisions and provide greater reliability and stability across Lando apps. That said, one downside of `portforward: true` is that Docker will assign a different port every time you restart your application. You can read more about accessing services externally [over here](https://docs.lando.dev/guides/external-access.html).
+
+`tl;dr`
+
+**Recommended**
+
+```yaml
+services:
+  myservice:
+    type: mysql
+    portforward: true
+```
+
+**Not recommended**
+
+```yaml
+services:
+  myservice:
+    type: mysql
+    portforward: 3600
+```
+
+### Setting custom credentials
+
+You can also configure the default `database`, `user` and `password`. However, it is *very important* to note that these things get set the **FIRST TIME YOU START** the service and **ONLY THE FIRST TIME.**
+
+This means that if you change any of the `creds`, you need to `lando destroy` and then `lando start` the service for the changes to take effect. This stands in contrast to the normal `lando rebuild` method to change config and is a consequence of persisting the database's data directory between rebuilds.
+
+```yaml
+services:
+  myservice:
+    type: mysql
+    creds:
+      user: mysql -> myuser
+      password: mysql -> mypassword
+      database: database -> db7
+```
+
+```bash
+lando destroy -y && lando start
+```
+
+Also note that by default all `mysql` services have a passwordless `root` user. **DO NOT ALTER THE PASSWORD OF THE ROOT USER.**
+
+
+### Using a custom MySQL config file
+
+You may need to override our [default MySQL config](https://github.com/lando/lando/tree/master/plugins/lando-services/services/mysql) with your own [custom MySQL config](https://dev.mysql.com/doc/refman/8.0/en/option-files.html).
+
+If you do this, you must use a file that exists inside your application and express it relative to your project root as shown below:
+
+**A hypothetical project**
+
+Note that you can put your configuration files anywhere inside your application directory. We use a `config` directory but you can call it whatever you want such as `.lando` in the example below:
+
+```bash
+./
+|-- config
+   |-- my-custom.cnf
+|-- .lando.yml
+```
+
+**Landofile's mysql config**
+
+```yaml
+services:
+  myservice:
+    type: mysql
+    config:
+      database: config/my-custom.cnf
+```
+Your override file will get copied to `/opt/bitnami/mysql/conf/bitnami/my_custom.cnf` in the database container and an include will be added to the MySQL configuration file located at `/opt/bitnami/mysql/conf/my.cnf`.
+
+## Getting information
+
+You can get connection and credential information about your mysql instance by running [`lando info`](https://docs.lando.dev/cli/info.html). It may also be worth checking out our [accessing services externally guide](https://docs.lando.dev/guides/external-access.html).
+
+<RelatedGuides tag="Databases"/>

examples/5.7/.lando.yml

@@ -0,0 +1,6 @@
+name: lando-mysql-57
+services:
+  defaults:
+    type: mysql
+  patch:
+    type: mysql:5.7.24

examples/5.7/README.md

@@ -0,0 +1,48 @@
+MySQL Example
+=============
+
+This example exists primarily to test the following documentation:
+
+* [MySQL Service](https://docs.devwithlando.io/tutorials/mysql.html)
+
+Start up tests
+--------------
+
+Run the following commands to get up and running with this example.
+
+```bash
+# Should start up successfully
+lando poweroff
+lando start
+```
+
+Verification commands
+---------------------
+
+Run the following commands to validate things are rolling as they should.
+
+```bash
+# Should use 5.7.29 as the default version
+lando ssh -s defaults -c "mysql --version | grep 5.7.29"
+
+# Should use the patch version when set by the user
+lando ssh -s patch -c "mysql --version | grep 5.7.24"
+
+# Should use the correct default user pass db
+lando ssh -s defaults -c "mysql -umysql -pmysql database -e quit"
+
+# Should still be running even after a restart
+lando restart
+lando ssh -s defaults -c "mysql -umysql -pmysql database -e quit"
+```
+
+Destroy tests
+-------------
+
+Run the following commands to trash this app like nothing ever happened.
+
+```bash
+# Should be destroyed with success
+lando destroy -y
+lando poweroff
+```

examples/5.7/my.cnf

@@ -0,0 +1,10 @@
+#
+# The MySQL database server configuration file for Kalabox
+# ASHAMEDOFPLAYINGTHEFOOL
+#
+
+[mysqld]
+
+# * Fine Tuning
+#
+table_open_cache = 513

examples/8.0/.lando.yml

@@ -0,0 +1,7 @@
+name: lando-mysql-80
+services:
+  defaults:
+    type: mysql:8.0
+  patch:
+    type: mysql:8.0.24
+