From 950fae879736c170c8bfe44f13e33061dd72970d Mon Sep 17 00:00:00 2001 From: Tim Clifford Date: Mon, 12 Jun 2023 16:49:44 +0100 Subject: [PATCH 1/2] mkdocs init --- .gitignore | 5 ++++- docs/commands/sync.md | 0 docs/config.md | 3 +++ docs/index.md | 22 ++++++++++++++++++++++ mkdocs.yml | 32 ++++++++++++++++++++++++++++++++ 5 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 docs/commands/sync.md create mode 100644 docs/config.md create mode 100644 docs/index.md create mode 100644 mkdocs.yml diff --git a/.gitignore b/.gitignore index 1b68f99..f134c74 100644 --- a/.gitignore +++ b/.gitignore @@ -29,4 +29,7 @@ builds/ # Config files *.lagoon-sync -*.lagoon-sync-defaults \ No newline at end of file +*.lagoon-sync-defaults + +# Docs +site/ diff --git a/docs/commands/sync.md b/docs/commands/sync.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..c744c40 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,3 @@ +# Introduction + +## Configuration file \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..b2cca14 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,22 @@ +# 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 + + +## Commands + +* `lagoon-sync sync [mariadb|files|mongodb|postgres] [flags]` - Sync resources between remote and local environments. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..b2df327 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,32 @@ +site_name: lagoon-sync +site_url: https://uselagoon.github.io/lagoon-sync/ +repo_url: https://github.com/uselagoon/lagoon-sync/ +repo_name: uselagoon/lagoon-sync + +theme: + name: 'material' + palette: + primary: 'blue' + accent: 'light blue' + favicon: lagoon-sync-logo.png + icon: + logo: fontawesome/solid/terminal + repo: fontawesome/brands/github + +markdown_extensions: + - toc: + permalink: "#" + baselevel: 2 + - admonition + - attr_list + - tables + - pymdownx.highlight + - pymdownx.superfences + +plugins: + - search + +nav: + - Getting Started: index.md + - Configuration: config.md + - Commands: commands/sync.md \ No newline at end of file From 4c1a00f4c98463bc6290556c4368c99242398247 Mon Sep 17 00:00:00 2001 From: Tim Clifford Date: Mon, 19 Jun 2023 14:41:37 +0100 Subject: [PATCH 2/2] updating docs and mkdocs configuring --- .github/workflows/mkdocs.yml | 22 ++++++++++ README.md | 6 +-- docs/commands/config.md | 7 ++++ docs/commands/overview.md | 3 ++ docs/commands/sync.md | 31 ++++++++++++++ docs/contributing.md | 10 +++++ docs/guides/syncing-locally.md | 0 docs/index.md | 28 ++++++++++++- docs/installation.md | 58 +++++++++++++++++++++++++ docs/troubleshoot.md | 3 ++ docs/updating.md | 15 +++++++ mkdocs.yml | 77 ++++++++++++++++++++++++++-------- 12 files changed, 235 insertions(+), 25 deletions(-) create mode 100644 .github/workflows/mkdocs.yml create mode 100644 docs/commands/config.md create mode 100644 docs/commands/overview.md create mode 100644 docs/contributing.md create mode 100644 docs/guides/syncing-locally.md create mode 100644 docs/installation.md create mode 100644 docs/troubleshoot.md create mode 100644 docs/updating.md diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml new file mode 100644 index 0000000..63e5491 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/README.md b/README.md index 970a6c8..07e15dc 100644 --- a/README.md +++ b/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). \ No newline at end of file diff --git a/docs/commands/config.md b/docs/commands/config.md new file mode 100644 index 0000000..9e3cf22 --- /dev/null +++ b/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` \ No newline at end of file diff --git a/docs/commands/overview.md b/docs/commands/overview.md new file mode 100644 index 0000000..c250476 --- /dev/null +++ b/docs/commands/overview.md @@ -0,0 +1,3 @@ +# Commands + +* `lagoon-sync sync [mariadb|files|mongodb|postgres] [flags]` - Sync resources between remote and local environments. \ No newline at end of file diff --git a/docs/commands/sync.md b/docs/commands/sync.md index e69de29..51773d9 100644 --- a/docs/commands/sync.md +++ b/docs/commands/sync.md @@ -0,0 +1,31 @@ +# sync + +Sync transfers are executed with `$ lagoon-sync sync ` 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 +``` \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..199631e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/guides/syncing-locally.md b/docs/guides/syncing-locally.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/index.md b/docs/index.md index b2cca14..051750c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,31 @@ Lagoon-sync offers: * 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 -## Commands +Lagoon-sync has the following core commands: -* `lagoon-sync sync [mariadb|files|mongodb|postgres] [flags]` - Sync resources between remote and local environments. \ No newline at end of file +``` +$ 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. +``` \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..9fabaac --- /dev/null +++ b/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 <