From a9de346b6ef9c365f557f0405aa1fdd175475d03 Mon Sep 17 00:00:00 2001 From: mvitale1989 Date: Fri, 14 Jul 2023 16:38:24 +0200 Subject: [PATCH] CLD-5793 - mmctl release changes (#6514) * Update mmctl docs, prepare for v8.0.0 release * Also update the mmctl build and testing docs * fix building and testing commands * Use v8.0.0 as an example version, for the docs --------- Co-authored-by: Carrie Warner (Mattermost) <74422101+cwarnermm@users.noreply.github.com> Co-authored-by: Amy Blais <29708087+amyblais@users.noreply.github.com> --- source/manage/mmctl-command-line-tool.rst | 62 ++++++++++++++--------- 1 file changed, 37 insertions(+), 25 deletions(-) diff --git a/source/manage/mmctl-command-line-tool.rst b/source/manage/mmctl-command-line-tool.rst index e482b84d421..cfaab42f641 100644 --- a/source/manage/mmctl-command-line-tool.rst +++ b/source/manage/mmctl-command-line-tool.rst @@ -13,8 +13,8 @@ This feature was developed to a large extent by community contributions and we'd mmctl usage notes ----------------- -- System Admins have two ways to run ``mmctl`` commands: by downloading ``mmctl`` from the repository, or by building it directly. See the `mmctl readme `__ for details. -- ``mmctl`` comes bundled with the Mattermost distribution, and is located in the ``bin`` folder of the installation, next to the ``CLI``. +- System Admins have two ways to run ``mmctl`` commands: by downloading ``mmctl`` from the release URLs, which you can find in the :ref:`installation instructions `, or by building it directly, for which you can check the :ref:`build instructions ` below. The source code lives in the `server/cmd/mmctl directory within the mattermost repository `__. +- ``mmctl`` also comes bundled with the Mattermost distribution, and is located in the ``bin`` folder of the installation, next to the ``CLI``. - We recommend you add the path to the Mattermost ``bin`` folder into your ``$PATH`` environment variable. This ensures that you can run mmctl commands locally regardless of your current directory location. - If the ``bin`` directory is not added to the ``$PATH`` environment variable, each time you use mmctl you must be in the ``bin`` directory to run mmctl commands, and the commands must be prefixed with ``./``. If you're working from a different directory, make sure you specify the full path to mmctl when running mmctl commands. @@ -79,39 +79,60 @@ Install mmctl The mmctl tool comes bundled with Mattermost package. For customers that want to setup it independently from the package, the following methods are available to install mmctl. +.. _install-mmctl-options: + .. tabs:: - .. tab:: Use brew (Linux, macOS) + .. tab:: Using release package (Linux, macOS, Windows) - Use this option on Linux and macOS if you have Homebrew installed. + Starting release ``v8.0.0`` of Mattermost, you can download the mmctl builds at their release URL: ``https://releases.mattermost.com/mmctl/${MATTERMOST_VERSION}/${PLATFORM}_${ARCHITECTURE}.tar`` + + E.g. to download version ``v8.0.0`` of the mmctl amd64 build for linux, you can run the following: .. code-block:: sh - brew install mmctl + curl -vfsSL -O https://releases.mattermost.com/mmctl/v8.0.0/linux_amd64.tar + + Supported platforms, and corresponding supported architectures, are: linux (amd64 and arm64), darwin (amd64 and arm64), windows (amd64 only). + + For versions older than ``v8.0.0``, you can instead visit the `mmctl releases page `__ and download the appropriate release for your OS, and install the binary. .. tab:: Using go install (Linux, macOS, Windows) Use this option on Linux, macOS, and Windows if you have a ``go`` environment configured. - To add the project in your `$GOPATH` run the following command: + To build and install the mmctl binary in your `$GOPATH`, run the following command: .. code-block:: sh + # For Mattermost versions >= v8.0.0 + go install github.com/mattermost/mattermost/server/v8/cmd/mmctl@master + + # For Mattermost versions < v8.0.0 go install github.com/mattermost/mmctl@latest - .. tab:: Using release package (Linux, macOS, Windows) + .. tab:: Use brew (Linux, macOS) + + **NB: this is not an officially supported method.** This installation channel is managed by the community, please refer to the `homebrew/homebrew-core repo `__ for reporting issues. - Vist the `mmctl releases page `__ and download the appropriate release for your OS, and install the binary. + Use this option on Linux and macOS if you have Homebrew installed. + + .. code-block:: sh + + brew install mmctl Build mmctl ------------ -The ``mmctl`` tool uses ``go`` modules to manage dependencies, so you need to have installed -``go`` 1.11 or greater and compile the binary using: +.. _build-mmctl: + +The ``mmctl`` tool uses ``go`` modules to manage dependencies, so you need to have installed ``go`` 1.19 or greater on your machine. + +After checking out the `mattermost repository `__ locally to your machine, from the root directory of the project, you can compile the mmctl binary by running: .. code-block:: sh - make build + make -C server mmctl-build Local mode ---------- @@ -145,24 +166,15 @@ Running mmctl tests mmctl has two types of tests: unit tests and end to end tests. -To run the unit tests, you need to execute: +To execute them, you can run the following commands from the mattermost project root directory: .. code-block:: sh - make test - -To run the end to end test suite, you need to have a Mattermost server instance running. Check the `Developer Setup guide `_ for instructions around how to configure a local test server instance. - -Once the development server is set up, cd into the ``mattermost-server directory``: - -- Start it with ``make run``. To confirm that the instance is running correctly, you can access the web interface at ``http://localhost:8065``. -- Run ``make test-data`` to preload your server instance with initial seed data. Generated data such as users are typically used for logging, etc. - -Change your directory to ``mmctl`` and run the end to end test suite with: - -.. code-block:: sh + # For the unit tests + make -C server test-mmctl-unit - make test-e2e + # For the end to end tests + make -C server test-mmctl-e2e mmctl auth ----------