mkdocs init

.github/workflows/mkdocs.yml

@@ -0,0 +1,22 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - mkdocs
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
+        env:
+          GITHUB_TOKEN: ${{ secrets.GH_ACTION_PAT }}
+          CONFIG_FILE: ./mkdocs.yml
+          REQUIREMENTS: docs/requirements.txt

.gitignore

@@ -29,4 +29,7 @@ builds/
 
 # Config files
 *.lagoon-sync
-*.lagoon-sync-defaults
+*.lagoon-sync-defaults
+
+# Docs
+site/

README.md

@@ -244,10 +244,6 @@ Setting up locally:
 * `make check-current-tag-version`    Check the current version.
 * `make clean`                        Remove all build files and assets.
 
-## Releases
-
 We are using [goreleaser](https://github.com/goreleaser/goreleaser) for the official build, release and publish steps that will be run from a GitHub Action on a pushed tag event.
 
-Locally, we can run `make release-test` to check if our changes will build. If compiling was successful we can commit our changes and then run `make release-[patch|minor|major]` to tag with next release number and it will push up to GitHub. A GitHub action will then be triggered which will publish the official release using goreleaser.
-
-Prior to that, we can locally test our release to ensure that it will successfully build with `make release-test`. If compiling was successful we can commit our changes and then run `make release-[patch|minor|major]` to tag with next release number and it will push up to GitHub. A GitHub action will then be triggered which will publish the official release using goreleaser.
+Locally whhen contributing, we can run `make release-test` to check if our changes will build sucessfully. If compiling was successful we can commit our changes to a new PR ready for review (https://github.com/uselagoon/lagoon-sync/pulls).

docs/commands/config.md

@@ -0,0 +1,7 @@
+# config
+
+The `config` command will output current sync-related configuration information it can find in a given environment. 
+
+This can be run with:
+
+`$ lagoon-sync config`

docs/commands/overview.md

@@ -0,0 +1,3 @@
+# Commands
+
+* `lagoon-sync sync [mariadb|files|mongodb|postgres] [flags]` - Sync resources between remote and local environments.

docs/commands/sync.md

@@ -0,0 +1,31 @@
+# sync
+
+Sync transfers are executed with `$ lagoon-sync sync <syncer>` and require at least a syncer type `[mariadb|files|mongodb|postgres|drupalconfig]`, a valid project name `-p` and source environment `-e`. By default, if you do not provide an optional target environment `-t` then `local` is used.
+
+```
+lagoon-sync sync
+
+Usage:
+  lagoon-sync sync [mariadb|files|mongodb|postgres|etc.] [flags]
+
+Flags:
+      --dry-run                          Don't run the commands, just preview what will be run
+  -h, --help                             help for sync
+      --no-interaction                   Disallow interaction
+  -p, --project-name string              The Lagoon project name of the remote system
+  -r, --rsync-args string                Pass through arguments to change the behaviour of rsync (default "--omit-dir-times --no-perms --no-group --no-owner --chmod=ugo=rwX --recursive --compress")
+  -s, --service-name string              The service name (default is 'cli'
+      --skip-source-cleanup              Don't clean up any of the files generated on the source
+      --skip-target-cleanup              Don't clean up any of the files generated on the target
+      --skip-target-import               This will skip the import step on the target, in combination with 'no-target-cleanup' this essentially produces a resource dump
+  -e, --source-environment-name string   The Lagoon environment name of the source system
+  -H, --ssh-host string                  Specify your lagoon ssh host, defaults to 'ssh.lagoon.amazeeio.cloud' (default "ssh.lagoon.amazeeio.cloud")
+  -i, --ssh-key string                   Specify path to a specific SSH key to use for authentication
+  -P, --ssh-port string                  Specify your ssh port, defaults to '32222' (default "32222")
+  -t, --target-environment-name string   The target environment name (defaults to local)
+      --verbose                          Run ssh commands in verbose (useful for debugging)
+
+Global Flags:
+      --config string   config file (default is .lagoon.yaml) (default "./.lagoon.yml")
+      --show-debug      Shows debug information
+```

docs/config.md

@@ -0,0 +1,3 @@
+# Introduction
+
+## Configuration file

docs/contributing.md

@@ -0,0 +1,10 @@
+# Contributing
+
+Setting up locally:
+
+* `make all`                          Installs missing dependencies, runs tests and build locally.
+* `make build`                        Compiles binary based on current go env.
+* `make local-build-linux`            Compile linix binary.
+* `make local-build-darwin`           Compile macOS (darwin) binary.
+* `make check-current-tag-version`    Check the current version.
+* `make clean`                        Remove all build files and assets.

docs/index.md

@@ -0,0 +1,46 @@
+# Lagoon-sync
+
+Lagoon-sync is cli tool written in Go that fundamentally provides the functionality to synchronise data between Lagoon environments. Lagoon-sync is part of the [Lagoon cli](https://github.com/amazeeio/lagoon-cli) toolset and works closely with its parent project.
+
+Lagoon-sync offers:
+
+* Sync commands for databases such as `mariadb`, `postgres` and `mongodb`
+* Php/node-based framework support such as Drupal, Laravel or Node.js
+* Standard file transfer support with `files` syncer
+* Has built-in default configuration values for syncing out-the-box
+* Provides an easy way to override sync configuration via `.lagoon.yml` or `.lagoon-sync.yml` files
+* Offers `--dry-run` flag to see what commands would be executed before running a transfer
+* `--no-interaction` can be used to auto-run all processes without prompt - useful for CI/builds
+* `config` command shows the configuration of the current environment
+* There is a `--show-debug` flag to output more verbose logging for debugging
+* Lagoon-sync uses `rsync` for the transfer of data, and will automatically detect and install `rsync` if it is not available on target environments
+* Secure cross-platform self-updating with `selfUpdate` command
+
+## Usage
+
+Lagoon-sync has the following core commands:
+
+```
+$ lagoon-sync
+lagoon-sync is a tool for syncing resources between environments in Lagoon hosted applications. This includes files, databases, and configurations.
+
+Usage:
+  lagoon-sync [command]
+
+Available Commands:
+  completion  generate the autocompletion script for the specified shell
+  config      Print the config that is being used by lagoon-sync
+  help        Help about any command
+  selfUpdate  Update this tool to the latest version
+  sync        Sync a resource type
+  version     Print the version number of lagoon-sync
+
+Flags:
+      --config string   config file (default is .lagoon.yaml) (default "./.lagoon.yml")
+  -h, --help            help for lagoon-sync
+      --show-debug      Shows debug information
+  -t, --toggle          Help message for toggle
+  -v, --version         version for lagoon-sync
+
+Use "lagoon-sync [command] --help" for more information about a command.
+```

docs/installation.md

@@ -0,0 +1,58 @@
+# Installation
+
+You can run `lagoon-sync` as a single binary by downloading from `https://github.com/uselagoon/lagoon-sync/releases/latest`.
+
+MacOS: `lagoon-sync_*.*.*_darwin_amd64`
+Linux (3 variants available): `lagoon-sync_*.*.*_linux_386`
+Windows: `lagoon-sync_*.*.*_windows_amd64.exe`
+
+To install via bash:
+
+## macOS (with M1 processors)
+
+    DOWNLOAD_PATH=$(curl -sL "https://api.github.com/repos/uselagoon/lagoon-sync/releases/latest" | grep "browser_download_url" | cut -d \" -f 4 | grep darwin_arm64) && wget -O /usr/local/bin/lagoon-sync $DOWNLOAD_PATH && chmod a+x /usr/local/bin/lagoon-sync
+
+## macOS (with Intel processors)
+
+    DOWNLOAD_PATH=$(curl -sL "https://api.github.com/repos/uselagoon/lagoon-sync/releases/latest" | grep "browser_download_url" | cut -d \" -f 4 | grep darwin_amd64) && wget -O /usr/local/bin/lagoon-sync $DOWNLOAD_PATH && chmod a+x /usr/local/bin/lagoon-sync
+
+## Linux (386)
+
+    DOWNLOAD_PATH=$(curl -sL "https://api.github.com/repos/uselagoon/lagoon-sync/releases/latest" | grep "browser_download_url" | cut -d \" -f 4 | grep linux_386) && wget -O /usr/local/bin/lagoon-sync $DOWNLOAD_PATH && chmod a+x /usr/local/bin/lagoon-sync
+
+## Linux (amd64)
+
+    DOWNLOAD_PATH=$(curl -sL "https://api.github.com/repos/uselagoon/lagoon-sync/releases/latest" | grep "browser_download_url" | cut -d \" -f 4 | grep linux_amd64) && wget -O /usr/local/bin/lagoon-sync $DOWNLOAD_PATH && chmod a+x /usr/local/bin/lagoon-sync
+
+## Linux (arm64)
+
+    DOWNLOAD_PATH=$(curl -sL "https://api.github.com/repos/uselagoon/lagoon-sync/releases/latest" | grep "browser_download_url" | cut -d \" -f 4 | grep linux_arm64) && wget -O /usr/local/bin/lagoon-sync $DOWNLOAD_PATH && chmod a+x /usr/local/bin/lagoon-sync
+
+
+## Quick setup (Linux example)
+
+This script will install `lagoon-sync` and create a configuration file that will connect to a `mariadb` instance. 
+
+```
+#!/usr/bin/env bash
+
+DOWNLOAD_PATH=$(curl -sL "https://api.github.com/repos/uselagoon/lagoon-sync/releases/latest" | grep "browser_download_url" | cut -d \" -f 4 | grep linux_amd64) && wget -O /usr/local/bin/lagoon-sync $DOWNLOAD_PATH && chmod a+x /usr/local/bin/lagoon-sync && chmod +x /usr/local/bin/lagoon-sync
+
+cat > .lagoon-sync <<EOF
+lagoon-sync:
+    mariadb:
+      config:
+        hostname: "\$MARIADB_DATABASE"
+        username: "\$MARIADB_USERNAME"
+        password: "\$MARIADB_PASSWORD"
+        port: "\$MARIADB_PORT"
+        database: "\$MARIADB_DATABASE"
+      local:
+        config:
+          hostname: "\$MARIADB_HOST"
+          username: "\$MARIADB_USERNAME"
+          password: "\$MARIADB_PASSWORD"
+          port: "\$MARIADB_PORT"
+          database: "\$MARIADB_DATABASE"
+EOF
+```

docs/troubleshoot.md

@@ -0,0 +1,3 @@
+# Introduction
+
+## Configuration files

docs/updating.md

@@ -0,0 +1,15 @@
+## Updating lagoon-sync
+
+It's possible to safely perform a cross-platform update of your lagoon-sync binary by running the `$ lagoon-sync selfUpdate` command. This will look for the latest release, then download the corresponding checksum and signature of the executable on GitHub, and verify its integrity and authenticity before it performs the update. The binary used to perform the update will then replace itself (if successful) to the new version. If an error occurs then the update will roll back to the previous stable version.
+
+```
+$ lagoon-sync selfUpdate
+
+Downloading binary from https://github.com/uselagoon/lagoon-sync/releases/download/v0.4.4/lagoon-sync_0.4.4_linux_386
+Checksum for linux_386: 61a55bd793d5745b6196ffd5bb87263aba85629f55ee0eaf53c771a0720adefd
+Good signature from "amazeeio"
+Applying update...
+Successfully updated binary at: /usr/bin/lagoon-sync
+```
+
+You can check version with `$ lagoon-sync --version`

mkdocs.yml

@@ -0,0 +1,73 @@
+site_name: Lagoon Sync Documentation
+site_url: https://uselagoon.github.io/lagoon-sync/
+repo_url: https://github.com/uselagoon/lagoon-sync/
+repo_name: uselagoon/lagoon-sync
+edit_uri: edit/main/docs
+site_author: The Lagoon Authors
+
+nav:
+  - Getting Started: index.md
+  - Configuration: config.md
+  - Commands:
+    - Overview: commands/overview.md
+    - Sync: commands/sync.md
+  - Guides:
+      - Syncing remote to local: guides/syncing-locally.md
+  - Example Configs: https://github.com/uselagoon/lagoon-sync/examples
+  - Troubleshoot: troubleshoot.md
+  - Release Notes: https://github.com/uselagoon/lagoon-sync/releases
+
+
+theme:
+  name: 'material'
+  palette:
+    # Palette toggle for light mode
+    - primary: 'blue'
+      accent: 'light blue'
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    # Palette toggle for dark mode
+    - scheme: slate
+      primary: 'blue'
+      toggle:
+        icon: material/brightness-7
+        name: Switch to light mode
+
+extra:
+  analytics:
+    provider: google
+    property: G-W1SJFEVFDB
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - def_list
+  - md_in_html
+  - mdx_truly_sane_lists
+  - pymdownx.caret
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+      auto_title: true
+  - pymdownx.inlinehilite
+  - pymdownx.mark
+  - pymdownx.snippets
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tilde
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.superfences
+  - tables
+  - toc:
+      permalink: "#"
+      baselevel: 1
+
+plugins:
+  - search
+  # - redirects:
+  #     redirect_maps:
+  #       'lagoon/README.md': 'README.md'