From 89ee3af9c51b6a548825305375bf91b00cb2b7af Mon Sep 17 00:00:00 2001 From: Rene Pot Date: Tue, 7 Nov 2023 11:59:42 +0100 Subject: [PATCH] docs: migrate to docusaurus implementation (#595) --- .github/semantic.yml | 6 +- .github/workflows/dhis2-verify-commits.yml | 38 ++++ CHANGELOG.md | 206 +++++++-------------- README.md | 4 +- docs/_sidebar.md | 5 +- docs/commands/d2-cluster.md | 192 ++++++++++--------- docs/commands/d2-utils-release.md | 30 ++- docs/commands/d2.md | 51 ++--- docs/getting-started.md | 20 +- docs/index.html | 18 ++ docs/recipes/custom-dhis-config.md | 14 +- docs/recipes/custom-image.md | 13 +- docs/recipes/development.md | 32 ++-- docs/recipes/stable.md | 37 ++-- package.json | 7 +- yarn.lock | 30 ++- 16 files changed, 372 insertions(+), 331 deletions(-) create mode 100644 .github/workflows/dhis2-verify-commits.yml create mode 100644 docs/index.html diff --git a/.github/semantic.yml b/.github/semantic.yml index 756b8b5a..16651452 100644 --- a/.github/semantic.yml +++ b/.github/semantic.yml @@ -1,4 +1,4 @@ -titleOnly: true +titleOnly: false commitsOnly: false -titleAndCommits: false -allowMergeCommits: false +titleAndCommits: true +allowMergeCommits: true diff --git a/.github/workflows/dhis2-verify-commits.yml b/.github/workflows/dhis2-verify-commits.yml new file mode 100644 index 00000000..1b6744f9 --- /dev/null +++ b/.github/workflows/dhis2-verify-commits.yml @@ -0,0 +1,38 @@ +name: 'dhis2: verify (commits)' + +on: + pull_request: + types: ['opened', 'edited', 'reopened', 'synchronize'] + +jobs: + lint-pr-title: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-node@v3 + with: + node-version: 16 + cache: 'yarn' + - run: yarn install --frozen-lockfile + - id: commitlint + run: echo ::set-output name=config_path::$(node -e "process.stdout.write(require('@dhis2/cli-style').config.commitlint)") + - uses: JulienKode/pull-request-name-linter-action@v0.5.0 + with: + configuration-path: ${{ steps.commitlint.outputs.config_path }} + + lint-commits: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + with: + fetch-depth: 0 + - uses: actions/setup-node@v3 + with: + node-version: 16 + cache: 'yarn' + - run: yarn install --frozen-lockfile + - id: commitlint + run: echo ::set-output name=config_path::$(node -e "process.stdout.write(require('@dhis2/cli-style').config.commitlint)") + - uses: wagoid/commitlint-github-action@v5 + with: + configFile: ${{ steps.commitlint.outputs.config_path }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 07a7a996..cf84cf68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,440 +1,376 @@ ## [4.2.3](https://github.com/dhis2/cli/compare/v4.2.2...v4.2.3) (2023-01-13) - ### Bug Fixes -* set DHIS2_HOME env var to /DHIS2_home for images pre-Jib ([4e8ce2b](https://github.com/dhis2/cli/commit/4e8ce2b00e4e8f5069ae37c2f685bef31733f0cf)) +- set DHIS2_HOME env var to /DHIS2_home for images pre-Jib ([4e8ce2b](https://github.com/dhis2/cli/commit/4e8ce2b00e4e8f5069ae37c2f685bef31733f0cf)) ## [4.2.2](https://github.com/dhis2/cli/compare/v4.2.1...v4.2.2) (2022-01-10) - ### Bug Fixes -* bump cli-helpers-engine for all packages ([#524](https://github.com/dhis2/cli/issues/524)) ([f651b4a](https://github.com/dhis2/cli/commit/f651b4a4db4136155760347027c9dea0ed1a642e)) +- bump cli-helpers-engine for all packages ([#524](https://github.com/dhis2/cli/issues/524)) ([f651b4a](https://github.com/dhis2/cli/commit/f651b4a4db4136155760347027c9dea0ed1a642e)) ## [4.2.1](https://github.com/dhis2/cli/compare/v4.2.0...v4.2.1) (2022-01-06) - ### Bug Fixes -* **main:** bump cli-helpers-engine to fix undefined project root issue ([#522](https://github.com/dhis2/cli/issues/522)) ([b869c72](https://github.com/dhis2/cli/commit/b869c72bf3557d02ea5204b155bd991dc3e51cec)) +- **main:** bump cli-helpers-engine to fix undefined project root issue ([#522](https://github.com/dhis2/cli/issues/522)) ([b869c72](https://github.com/dhis2/cli/commit/b869c72bf3557d02ea5204b155bd991dc3e51cec)) # [4.2.0](https://github.com/dhis2/cli/compare/v4.1.0...v4.2.0) (2021-11-29) - ### Bug Fixes -* **deps:** bump @dhis2/cli-utils-docsite from 3.0.0 to 3.1.2 [defer release] ([#468](https://github.com/dhis2/cli/issues/468)) ([6c3a69d](https://github.com/dhis2/cli/commit/6c3a69d852dc57aad7714e50da3492dbf39a5c67)) - +- **deps:** bump @dhis2/cli-utils-docsite from 3.0.0 to 3.1.2 [defer release] ([#468](https://github.com/dhis2/cli/issues/468)) ([6c3a69d](https://github.com/dhis2/cli/commit/6c3a69d852dc57aad7714e50da3492dbf39a5c67)) ### Features -* **cli:** prefer project-local tools ([50e1eae](https://github.com/dhis2/cli/commit/50e1eaec3c3107e2134386589efca68f5ecb8965)) -* **deps:** bump @dhis2/cli-utils-cypress from 8.0.1 to 9.0.1 [defer release] ([#513](https://github.com/dhis2/cli/issues/513)) ([ea03992](https://github.com/dhis2/cli/commit/ea0399223feb6e344124c806ee79eae3f6fb85ce)) +- **cli:** prefer project-local tools ([50e1eae](https://github.com/dhis2/cli/commit/50e1eaec3c3107e2134386589efca68f5ecb8965)) +- **deps:** bump @dhis2/cli-utils-cypress from 8.0.1 to 9.0.1 [defer release] ([#513](https://github.com/dhis2/cli/issues/513)) ([ea03992](https://github.com/dhis2/cli/commit/ea0399223feb6e344124c806ee79eae3f6fb85ce)) # [4.1.0](https://github.com/dhis2/cli/compare/v4.0.5...v4.1.0) (2021-11-10) - ### Features -* **deps:** bump @dhis2/cli-app-scripts from 7.1.0 to 8.3.0 [defer release] ([#508](https://github.com/dhis2/cli/issues/508)) ([288039e](https://github.com/dhis2/cli/commit/288039e5e0f2cea1ce20627871a38668f75fe77b)) +- **deps:** bump @dhis2/cli-app-scripts from 7.1.0 to 8.3.0 [defer release] ([#508](https://github.com/dhis2/cli/issues/508)) ([288039e](https://github.com/dhis2/cli/commit/288039e5e0f2cea1ce20627871a38668f75fe77b)) ## [4.0.5](https://github.com/dhis2/cli/compare/v4.0.4...v4.0.5) (2021-07-05) - ### Bug Fixes -* **deps:** update semantic-release dependencies ([a3d6aef](https://github.com/dhis2/cli/commit/a3d6aefda0dcd6792dce92149ba79d6aeecab040)) +- **deps:** update semantic-release dependencies ([a3d6aef](https://github.com/dhis2/cli/commit/a3d6aefda0dcd6792dce92149ba79d6aeecab040)) ## [4.0.4](https://github.com/dhis2/cli/compare/v4.0.3...v4.0.4) (2021-06-23) - ### Bug Fixes -* **utils:** manage versions on private packages when not publishing to npm ([1a305f9](https://github.com/dhis2/cli/commit/1a305f9)) +- **utils:** manage versions on private packages when not publishing to npm ([1a305f9](https://github.com/dhis2/cli/commit/1a305f9)) ## [4.0.3](https://github.com/dhis2/cli/compare/v4.0.2...v4.0.3) (2021-06-23) - ### Bug Fixes -* **release:** always update package.json version ([97fbfd6](https://github.com/dhis2/cli/commit/97fbfd6)) +- **release:** always update package.json version ([97fbfd6](https://github.com/dhis2/cli/commit/97fbfd6)) ## [4.0.2](https://github.com/dhis2/cli/compare/v4.0.1...v4.0.2) (2021-06-16) - ### Bug Fixes -* **semantic-release:** pin version to 16 ([254b55c](https://github.com/dhis2/cli/commit/254b55c)) +- **semantic-release:** pin version to 16 ([254b55c](https://github.com/dhis2/cli/commit/254b55c)) ## [4.0.1](https://github.com/dhis2/cli/compare/v4.0.0...v4.0.1) (2021-06-14) - ### Bug Fixes -* **deps:** update cli-style to work in non-project context ([adf329e](https://github.com/dhis2/cli/commit/adf329e)) -* **utils:** include cypress utilities ([df0e5ce](https://github.com/dhis2/cli/commit/df0e5ce)) +- **deps:** update cli-style to work in non-project context ([adf329e](https://github.com/dhis2/cli/commit/adf329e)) +- **utils:** include cypress utilities ([df0e5ce](https://github.com/dhis2/cli/commit/df0e5ce)) # [4.0.0](https://github.com/dhis2/cli/compare/v3.1.0...v4.0.0) (2021-06-14) - ### chore -* remove node 10 support ([c35761e](https://github.com/dhis2/cli/commit/c35761e)) - +- remove node 10 support ([c35761e](https://github.com/dhis2/cli/commit/c35761e)) ### BREAKING CHANGES -* New minimum version for NodeJS is 12.x. +- New minimum version for NodeJS is 12.x. # [3.1.0](https://github.com/dhis2/cli/compare/v3.0.6...v3.1.0) (2021-02-02) - ### Features -* **codemods:** add d2-utils-codemods ([#397](https://github.com/dhis2/cli/issues/397)) ([0afbfe8](https://github.com/dhis2/cli/commit/0afbfe8)) +- **codemods:** add d2-utils-codemods ([#397](https://github.com/dhis2/cli/issues/397)) ([0afbfe8](https://github.com/dhis2/cli/commit/0afbfe8)) ## [3.0.6](https://github.com/dhis2/cli/compare/v3.0.5...v3.0.6) (2020-11-06) - ### Bug Fixes -* cut release to finish migration to jira ([2c671d7](https://github.com/dhis2/cli/commit/2c671d7)) +- cut release to finish migration to jira ([2c671d7](https://github.com/dhis2/cli/commit/2c671d7)) ## [3.0.5](https://github.com/dhis2/cli/compare/v3.0.4...v3.0.5) (2020-09-10) - ### Bug Fixes -* **deps:** bump @dhis2/cli-app-scripts from 4.0.0 to 5.2.0 ([#367](https://github.com/dhis2/cli/issues/367)) ([bc9eceb](https://github.com/dhis2/cli/commit/bc9eceb)) +- **deps:** bump @dhis2/cli-app-scripts from 4.0.0 to 5.2.0 ([#367](https://github.com/dhis2/cli/issues/367)) ([bc9eceb](https://github.com/dhis2/cli/commit/bc9eceb)) ## [3.0.4](https://github.com/dhis2/cli/compare/v3.0.3...v3.0.4) (2020-05-05) - ### Bug Fixes -* use new location for sample database downloads ([#327](https://github.com/dhis2/cli/issues/327)) ([d571de4](https://github.com/dhis2/cli/commit/d571de4)) +- use new location for sample database downloads ([#327](https://github.com/dhis2/cli/issues/327)) ([d571de4](https://github.com/dhis2/cli/commit/d571de4)) ## [3.0.3](https://github.com/dhis2/cli/compare/v3.0.2...v3.0.3) (2020-04-06) - ### Bug Fixes -* add cli-table3 as d2-cluster dependency ([bd84e12](https://github.com/dhis2/cli/commit/bd84e12)) +- add cli-table3 as d2-cluster dependency ([bd84e12](https://github.com/dhis2/cli/commit/bd84e12)) ## [3.0.2](https://github.com/dhis2/cli/compare/v3.0.1...v3.0.2) (2020-04-03) - ### Bug Fixes -* don't set DHIS2_CORE_CONFIG to undefined, it needs to be unset ([21b467a](https://github.com/dhis2/cli/commit/21b467a)) +- don't set DHIS2_CORE_CONFIG to undefined, it needs to be unset ([21b467a](https://github.com/dhis2/cli/commit/21b467a)) ## [3.0.1](https://github.com/dhis2/cli/compare/v3.0.0...v3.0.1) (2020-04-03) - ### Bug Fixes -* **release:** avoid picking a prop from undefined ([5e9f48e](https://github.com/dhis2/cli/commit/5e9f48e)) +- **release:** avoid picking a prop from undefined ([5e9f48e](https://github.com/dhis2/cli/commit/5e9f48e)) # [3.0.0](https://github.com/dhis2/cli/compare/v2.9.1...v3.0.0) (2020-04-02) - ### chore -* require node >=10 ([ee2a64b](https://github.com/dhis2/cli/commit/ee2a64b)) - +- require node >=10 ([ee2a64b](https://github.com/dhis2/cli/commit/ee2a64b)) ### Features -* **utils:** add cypress subcommand ([96c5b86](https://github.com/dhis2/cli/commit/96c5b86)) - +- **utils:** add cypress subcommand ([96c5b86](https://github.com/dhis2/cli/commit/96c5b86)) ### BREAKING CHANGES -* Require Node version 10 or later. +- Require Node version 10 or later. ## [2.9.1](https://github.com/dhis2/cli/compare/v2.9.0...v2.9.1) (2020-03-15) - ### Bug Fixes -* **release:** fix changelog ([f6b7a0d](https://github.com/dhis2/cli/commit/f6b7a0d)) +- **release:** fix changelog ([f6b7a0d](https://github.com/dhis2/cli/commit/f6b7a0d)) # [2.9.0](https://github.com/dhis2/cli/compare/v2.8.1...v2.9.0) (2020-03-15) - ### Bug Fixes -* release with the internal changes, not the npm package ([6763800](https://github.com/dhis2/cli/commit/6763800)) - +- release with the internal changes, not the npm package ([6763800](https://github.com/dhis2/cli/commit/6763800)) ### Features -* **release:** support distribution tags and custom release user info ([#292](https://github.com/dhis2/cli/issues/292)) ([7e59cf5](https://github.com/dhis2/cli/commit/7e59cf5)) +- **release:** support distribution tags and custom release user info ([#292](https://github.com/dhis2/cli/issues/292)) ([7e59cf5](https://github.com/dhis2/cli/commit/7e59cf5)) ## [2.8.1](https://github.com/dhis2/cli/compare/v2.8.0...v2.8.1) (2020-01-20) - ### Bug Fixes -* **docs:** format link correctly ([#255](https://github.com/dhis2/cli/issues/255)) ([8626546](https://github.com/dhis2/cli/commit/8626546)) +- **docs:** format link correctly ([#255](https://github.com/dhis2/cli/issues/255)) ([8626546](https://github.com/dhis2/cli/commit/8626546)) # [2.8.0](https://github.com/dhis2/cli/compare/v2.7.0...v2.8.0) (2020-01-09) - ### Features -* **cluster:** add option to pass in path to custom dhis.conf ([#236](https://github.com/dhis2/cli/issues/236)) ([80f4cd5](https://github.com/dhis2/cli/commit/80f4cd5)) +- **cluster:** add option to pass in path to custom dhis.conf ([#236](https://github.com/dhis2/cli/issues/236)) ([80f4cd5](https://github.com/dhis2/cli/commit/80f4cd5)) # [2.7.0](https://github.com/dhis2/cli/compare/v2.6.1...v2.7.0) (2019-11-26) - ### Features -* upgrade @dhis2/cli-style to 5.0.2, don't auto-format code in pre-commit hook ([#208](https://github.com/dhis2/cli/issues/208)) ([c2f8eea](https://github.com/dhis2/cli/commit/c2f8eea)) +- upgrade @dhis2/cli-style to 5.0.2, don't auto-format code in pre-commit hook ([#208](https://github.com/dhis2/cli/issues/208)) ([c2f8eea](https://github.com/dhis2/cli/commit/c2f8eea)) ## [2.6.1](https://github.com/dhis2/cli/compare/v2.6.0...v2.6.1) (2019-11-21) - ### Bug Fixes -* **deps:** bump @dhis2/cli-app-scripts from 1.5.5 to 1.5.9 ([#195](https://github.com/dhis2/cli/issues/195)) ([35f9487](https://github.com/dhis2/cli/commit/35f9487)) +- **deps:** bump @dhis2/cli-app-scripts from 1.5.5 to 1.5.9 ([#195](https://github.com/dhis2/cli/issues/195)) ([35f9487](https://github.com/dhis2/cli/commit/35f9487)) # [2.6.0](https://github.com/dhis2/cli/compare/v2.5.0...v2.6.0) (2019-10-24) - ### Features -* add i18n modernize to create new translation files from old ones ([#113](https://github.com/dhis2/cli/issues/113)) ([4e52e32](https://github.com/dhis2/cli/commit/4e52e32)) +- add i18n modernize to create new translation files from old ones ([#113](https://github.com/dhis2/cli/issues/113)) ([4e52e32](https://github.com/dhis2/cli/commit/4e52e32)) # [2.5.0](https://github.com/dhis2/cli/compare/v2.4.0...v2.5.0) (2019-10-16) - ### Features -* allow defer-release keyword in commit messages ([#161](https://github.com/dhis2/cli/issues/161)) ([ef6b385](https://github.com/dhis2/cli/commit/ef6b385)) +- allow defer-release keyword in commit messages ([#161](https://github.com/dhis2/cli/issues/161)) ([ef6b385](https://github.com/dhis2/cli/commit/ef6b385)) # [2.4.0](https://github.com/dhis2/cli/compare/v2.3.1...v2.4.0) (2019-10-09) - ### Bug Fixes -* **deps:** bump @dhis2/cli-style from 4.1.2 to 4.1.3 ([#157](https://github.com/dhis2/cli/issues/157)) [skip ci] ([957fd62](https://github.com/dhis2/cli/commit/957fd62)) - +- **deps:** bump @dhis2/cli-style from 4.1.2 to 4.1.3 ([#157](https://github.com/dhis2/cli/issues/157)) [skip ci] ([957fd62](https://github.com/dhis2/cli/commit/957fd62)) ### Features -* **deps:** bump @dhis2/cli-app-scripts from 1.4.4 to 1.5.3 ([#156](https://github.com/dhis2/cli/issues/156)) ([2ae6bf7](https://github.com/dhis2/cli/commit/2ae6bf7)) +- **deps:** bump @dhis2/cli-app-scripts from 1.4.4 to 1.5.3 ([#156](https://github.com/dhis2/cli/issues/156)) ([2ae6bf7](https://github.com/dhis2/cli/commit/2ae6bf7)) ## [2.3.1](https://github.com/dhis2/cli/compare/v2.3.0...v2.3.1) (2019-09-27) - ### Bug Fixes -* bump @dhis2/cli-app-scripts from 1.3.1 to 1.4.4 ([#145](https://github.com/dhis2/cli/issues/145)) ([d10842f](https://github.com/dhis2/cli/commit/d10842f)) +- bump @dhis2/cli-app-scripts from 1.3.1 to 1.4.4 ([#145](https://github.com/dhis2/cli/issues/145)) ([d10842f](https://github.com/dhis2/cli/commit/d10842f)) # [2.3.0](https://github.com/dhis2/cli/compare/v2.2.2...v2.3.0) (2019-09-17) - ### Features -* schema differ ([#43](https://github.com/dhis2/cli/issues/43)) ([c46e343](https://github.com/dhis2/cli/commit/c46e343)), closes [#51](https://github.com/dhis2/cli/issues/51) +- schema differ ([#43](https://github.com/dhis2/cli/issues/43)) ([c46e343](https://github.com/dhis2/cli/commit/c46e343)), closes [#51](https://github.com/dhis2/cli/issues/51) ## [2.2.2](https://github.com/dhis2/cli/compare/v2.2.1...v2.2.2) (2019-09-17) - ### Bug Fixes -* don't swallow release command errors ([#131](https://github.com/dhis2/cli/issues/131)) ([8a09d32](https://github.com/dhis2/cli/commit/8a09d32)) +- don't swallow release command errors ([#131](https://github.com/dhis2/cli/issues/131)) ([8a09d32](https://github.com/dhis2/cli/commit/8a09d32)) ## [2.2.1](https://github.com/dhis2/cli/compare/v2.2.0...v2.2.1) (2019-09-06) - ### Bug Fixes -* correctly normalize compose project name ([#129](https://github.com/dhis2/cli/issues/129)) ([12129e7](https://github.com/dhis2/cli/commit/12129e7)) +- correctly normalize compose project name ([#129](https://github.com/dhis2/cli/issues/129)) ([12129e7](https://github.com/dhis2/cli/commit/12129e7)) # [2.2.0](https://github.com/dhis2/cli/compare/v2.1.3...v2.2.0) (2019-08-29) - ### Features -* add support for d2-app-scripts and d2-utils-docsite ([#121](https://github.com/dhis2/cli/issues/121)) ([4b39415](https://github.com/dhis2/cli/commit/4b39415)) +- add support for d2-app-scripts and d2-utils-docsite ([#121](https://github.com/dhis2/cli/issues/121)) ([4b39415](https://github.com/dhis2/cli/commit/4b39415)) ## [2.1.3](https://github.com/dhis2/cli/compare/v2.1.2...v2.1.3) (2019-08-27) - ### Bug Fixes -* properly handle workspaces.packages arrays ([1a5929a](https://github.com/dhis2/cli/commit/1a5929a)) +- properly handle workspaces.packages arrays ([1a5929a](https://github.com/dhis2/cli/commit/1a5929a)) ## [2.1.2](https://github.com/dhis2/cli/compare/v2.1.1...v2.1.2) (2019-08-27) - ### Bug Fixes -* missing import ([06d22bc](https://github.com/dhis2/cli/commit/06d22bc)) +- missing import ([06d22bc](https://github.com/dhis2/cli/commit/06d22bc)) ## [2.1.1](https://github.com/dhis2/cli/compare/v2.1.0...v2.1.1) (2019-08-25) - ### Bug Fixes -* improve cluster list formatting ([#119](https://github.com/dhis2/cli/issues/119)) ([8b6411c](https://github.com/dhis2/cli/commit/8b6411c)) +- improve cluster list formatting ([#119](https://github.com/dhis2/cli/issues/119)) ([8b6411c](https://github.com/dhis2/cli/commit/8b6411c)) # [2.1.0](https://github.com/dhis2/cli/compare/v2.0.0...v2.1.0) (2019-08-24) - ### Features -* add `cluster list` command ([#118](https://github.com/dhis2/cli/issues/118)) ([b3b1e6d](https://github.com/dhis2/cli/commit/b3b1e6d)) +- add `cluster list` command ([#118](https://github.com/dhis2/cli/issues/118)) ([b3b1e6d](https://github.com/dhis2/cli/commit/b3b1e6d)) # [2.0.0](https://github.com/dhis2/cli/compare/v1.4.0...v2.0.0) (2019-07-15) - ### chore -* prepare 2.0 of d2 ([#100](https://github.com/dhis2/cli/issues/100)) ([52d4f00](https://github.com/dhis2/cli/commit/52d4f00)) - +- prepare 2.0 of d2 ([#100](https://github.com/dhis2/cli/issues/100)) ([52d4f00](https://github.com/dhis2/cli/commit/52d4f00)) ### BREAKING CHANGES -* Remove deprecated `d2-cluster seed` command, and update `d2-style` to 4.1.0. +- Remove deprecated `d2-cluster seed` command, and update `d2-style` to 4.1.0. -- For changelog of what has changed with cli-style, see https://github.com/dhis2/cli-style/blob/master/CHANGELOG.md#breaking-changes for a list of changes. +* For changelog of what has changed with cli-style, see https://github.com/dhis2/cli-style/blob/master/CHANGELOG.md#breaking-changes for a list of changes. -- `d2-cluster seed` has been deprecated in favour of `d2-cluster db restore`, see `d2 cluster db --help` for more information on usage. +* `d2-cluster seed` has been deprecated in favour of `d2-cluster db restore`, see `d2 cluster db --help` for more information on usage. # [1.4.0](https://github.com/dhis2/cli/compare/v1.3.0...v1.4.0) (2019-07-02) - ### Features -* add cluster db commands, update images on up, add compose cmd ([#95](https://github.com/dhis2/cli/issues/95)) ([7dd4fc1](https://github.com/dhis2/cli/commit/7dd4fc1)) +- add cluster db commands, update images on up, add compose cmd ([#95](https://github.com/dhis2/cli/issues/95)) ([7dd4fc1](https://github.com/dhis2/cli/commit/7dd4fc1)) # [1.3.0](https://github.com/dhis2/cli/compare/v1.2.4...v1.3.0) (2019-07-01) - ### Features -* decouple configs from cluster ([#53](https://github.com/dhis2/cli/issues/53)) ([e5b40af](https://github.com/dhis2/cli/commit/e5b40af)) +- decouple configs from cluster ([#53](https://github.com/dhis2/cli/issues/53)) ([e5b40af](https://github.com/dhis2/cli/commit/e5b40af)) ## [1.2.4](https://github.com/dhis2/cli/compare/v1.2.3...v1.2.4) (2019-06-13) - ### Bug Fixes -* use dhis2/docker-compose instead of amcgee/dhis2-backend as default ([#61](https://github.com/dhis2/cli/issues/61)) ([85d708f](https://github.com/dhis2/cli/commit/85d708f)) +- use dhis2/docker-compose instead of amcgee/dhis2-backend as default ([#61](https://github.com/dhis2/cli/issues/61)) ([85d708f](https://github.com/dhis2/cli/commit/85d708f)) ## [1.2.3](https://github.com/dhis2/cli/compare/v1.2.2...v1.2.3) (2019-06-12) - ### Bug Fixes -* avoid double parsing of arguments ([#64](https://github.com/dhis2/cli/issues/64)) ([b616152](https://github.com/dhis2/cli/commit/b616152)) +- avoid double parsing of arguments ([#64](https://github.com/dhis2/cli/issues/64)) ([b616152](https://github.com/dhis2/cli/commit/b616152)) ## [1.2.2](https://github.com/dhis2/cli/compare/v1.2.1...v1.2.2) (2019-05-27) - ### Bug Fixes -* use the resolved db dump url ([#56](https://github.com/dhis2/cli/issues/56)) ([0f26ad1](https://github.com/dhis2/cli/commit/0f26ad1)) +- use the resolved db dump url ([#56](https://github.com/dhis2/cli/issues/56)) ([0f26ad1](https://github.com/dhis2/cli/commit/0f26ad1)) ## [1.2.1](https://github.com/dhis2/cli/compare/v1.2.0...v1.2.1) (2019-05-27) - ### Bug Fixes -* resolve dockerComposeRepository from defaults if cluster undefined ([#55](https://github.com/dhis2/cli/issues/55)) ([39fc0c7](https://github.com/dhis2/cli/commit/39fc0c7)) +- resolve dockerComposeRepository from defaults if cluster undefined ([#55](https://github.com/dhis2/cli/issues/55)) ([39fc0c7](https://github.com/dhis2/cli/commit/39fc0c7)) # [1.2.0](https://github.com/dhis2/cli/compare/v1.1.0...v1.2.0) (2019-05-27) - ### Features -* support official docker images ([#54](https://github.com/dhis2/cli/issues/54)) ([8e2a6da](https://github.com/dhis2/cli/commit/8e2a6da)) +- support official docker images ([#54](https://github.com/dhis2/cli/issues/54)) ([8e2a6da](https://github.com/dhis2/cli/commit/8e2a6da)) # [1.1.0](https://github.com/dhis2/cli/compare/v1.0.5...v1.1.0) (2019-05-23) - ### Features -* decouple tag, name, and version ([#46](https://github.com/dhis2/cli/issues/46)) ([28e88e4](https://github.com/dhis2/cli/commit/28e88e4)) +- decouple tag, name, and version ([#46](https://github.com/dhis2/cli/issues/46)) ([28e88e4](https://github.com/dhis2/cli/commit/28e88e4)) ## [1.0.5](https://github.com/dhis2/cli/compare/v1.0.4...v1.0.5) (2019-05-14) - ### Bug Fixes -* update @dhis2/cli style 3.2.1 ([#49](https://github.com/dhis2/cli/issues/49)) ([c375f8d](https://github.com/dhis2/cli/commit/c375f8d)), closes [#48](https://github.com/dhis2/cli/issues/48) [#48](https://github.com/dhis2/cli/issues/48) +- update @dhis2/cli style 3.2.1 ([#49](https://github.com/dhis2/cli/issues/49)) ([c375f8d](https://github.com/dhis2/cli/commit/c375f8d)), closes [#48](https://github.com/dhis2/cli/issues/48) [#48](https://github.com/dhis2/cli/issues/48) ## [1.0.4](https://github.com/dhis2/cli/compare/v1.0.3...v1.0.4) (2019-05-14) - ### Bug Fixes -* update @dhis2/cli-helpers-engine in group default to the latest version 🚀 ([#47](https://github.com/dhis2/cli/issues/47)) ([6139000](https://github.com/dhis2/cli/commit/6139000)) +- update @dhis2/cli-helpers-engine in group default to the latest version 🚀 ([#47](https://github.com/dhis2/cli/issues/47)) ([6139000](https://github.com/dhis2/cli/commit/6139000)) ## [1.0.3](https://github.com/dhis2/cli/compare/v1.0.2...v1.0.3) (2019-05-13) - ### Bug Fixes -* **cluster:** expose the version as an environment variable in the context ([#39](https://github.com/dhis2/cli/issues/39)) ([7e8e8dd](https://github.com/dhis2/cli/commit/7e8e8dd)) +- **cluster:** expose the version as an environment variable in the context ([#39](https://github.com/dhis2/cli/issues/39)) ([7e8e8dd](https://github.com/dhis2/cli/commit/7e8e8dd)) ## [1.0.2](https://github.com/dhis2/cli/compare/v1.0.1...v1.0.2) (2019-03-28) - ### Bug Fixes -* upgrade @dhis2/cli-helpers-engine and @dhis2/cli-style ([#35](https://github.com/dhis2/cli/issues/35)) ([251ac22](https://github.com/dhis2/cli/commit/251ac22)) +- upgrade @dhis2/cli-helpers-engine and @dhis2/cli-style ([#35](https://github.com/dhis2/cli/issues/35)) ([251ac22](https://github.com/dhis2/cli/commit/251ac22)) ## [1.0.1](https://github.com/dhis2/cli/compare/v1.0.0...v1.0.1) (2019-03-27) - ### Bug Fixes -* seed from file variable name was misspelled ([#33](https://github.com/dhis2/cli/issues/33)) ([6109c95](https://github.com/dhis2/cli/commit/6109c95)) +- seed from file variable name was misspelled ([#33](https://github.com/dhis2/cli/issues/33)) ([6109c95](https://github.com/dhis2/cli/commit/6109c95)) # [1.0.0](https://github.com/dhis2/cli/compare/v0.14.0...v1.0.0) (2019-03-25) - ### Features -* upgrade cli-helpers-engine and cli-style dependencies ([#32](https://github.com/dhis2/cli/issues/32)) ([21c78dd](https://github.com/dhis2/cli/commit/21c78dd)) - +- upgrade cli-helpers-engine and cli-style dependencies ([#32](https://github.com/dhis2/cli/issues/32)) ([21c78dd](https://github.com/dhis2/cli/commit/21c78dd)) ### BREAKING CHANGES -* cut major version 1.0.0 +- cut major version 1.0.0 -* chore: update cli-helpers-engine and cli-style dependencies +- chore: update cli-helpers-engine and cli-style dependencies -* chore: let greenkeeper watch the create cli template +- chore: let greenkeeper watch the create cli template # [0.14.0](https://github.com/dhis2/cli/compare/v0.13.0...v0.14.0) (2019-03-25) - ### Features -* one dot oh! ([#28](https://github.com/dhis2/cli/issues/28)) ([207ae93](https://github.com/dhis2/cli/commit/207ae93)) +- one dot oh! ([#28](https://github.com/dhis2/cli/issues/28)) ([207ae93](https://github.com/dhis2/cli/commit/207ae93)) # [0.13.0](https://github.com/dhis2/cli/compare/v0.12.1...v0.13.0) (2019-03-25) - ### Bug Fixes -* don't update the package.json version before npm stage ([#25](https://github.com/dhis2/cli/issues/25)) ([5909f78](https://github.com/dhis2/cli/commit/5909f78)) - +- don't update the package.json version before npm stage ([#25](https://github.com/dhis2/cli/issues/25)) ([5909f78](https://github.com/dhis2/cli/commit/5909f78)) ### Features -* semantic release update deps ([#24](https://github.com/dhis2/cli/issues/24)) ([d2c155e](https://github.com/dhis2/cli/commit/d2c155e)) +- semantic release update deps ([#24](https://github.com/dhis2/cli/issues/24)) ([d2c155e](https://github.com/dhis2/cli/commit/d2c155e)) ## [0.12.1](https://github.com/dhis2/cli/compare/v0.12.0...v0.12.1) (2019-03-22) - ### Bug Fixes -* add scripts subcommand ([#23](https://github.com/dhis2/cli/issues/23)) ([bb36a22](https://github.com/dhis2/cli/commit/bb36a22)) -* publish multiple packages from inside a package ([#22](https://github.com/dhis2/cli/issues/22)) ([6012782](https://github.com/dhis2/cli/commit/6012782)) +- add scripts subcommand ([#23](https://github.com/dhis2/cli/issues/23)) ([bb36a22](https://github.com/dhis2/cli/commit/bb36a22)) +- publish multiple packages from inside a package ([#22](https://github.com/dhis2/cli/issues/22)) ([6012782](https://github.com/dhis2/cli/commit/6012782)) diff --git a/README.md b/README.md index 60d2538b..6a4077ff 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,13 @@ See the [documentation site](https://cli.dhis2.nu) for end-user installation and ## Conventions -The `d2` command-line tool is structured as a collection of namespaces, each of which may include sub-namespaces and sub-commands. This heirarchy should follow one simple rule: +The `d2` command-line tool is structured as a collection of namespaces, each of which may include sub-namespaces and sub-commands. This hierarchy should follow one simple rule: **namespaces are nouns, commands are verbs** Each subsequent namespace should narrow the context in which a command (an action) will be performed. For example: -- `d2 cluster restart` performs the action **restart** in the **d2 cluster** namespace +- `d2 cluster restart` performs the action `restart` in the `d2 cluster` namespace - `d2 style js apply` performs the **apply** action in the **js** sub-namespace of the **d2 style** namespace Anything following the action verb is either a positional argument or a flag (if preceded by `-` or `--`), i.e.: diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 15cf2ff7..97af6ecd 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,17 +1,16 @@ - [**Getting Started**](getting-started) - **Commands** - - [`d2`](commands/d2) -- - `d2 app` -- - - [`d2 app scripts`↗️](https://platform.dhis2.nu/#/scripts ':ignore') - - [`d2 cluster`](commands/d2-cluster) - - - [Use a stable version](recipes/stable) - - - [Use a development version](recipes/development) - - - [Use a custom Docker image](recipes/custom-image) - - - [Use a custom `dhis.conf`](recipes/custom-dhis-config) -- - [`d2 style`↗️](https://cli-style.dhis2.nu ':ignore') - - `d2 utils` - - - [`d2 utils release`](commands/d2-utils-release) - - - [`d2 utils cypress`↗️](https://cli-utils-cypress.dhis2.nu ':ignore') - - - [`d2 utils docsite`↗️](https://cli-utils-docsite.dhis2.nu ':ignore') +- - [`d2 style`↗️](https://cli-style.dhis2.nu ':ignore') +- - [`d2 app scripts`↗️](https://platform.dhis2.nu/#/scripts ':ignore') -   - [Changelog](CHANGELOG) diff --git a/docs/commands/d2-cluster.md b/docs/commands/d2-cluster.md index 1d7aae87..62bab703 100644 --- a/docs/commands/d2-cluster.md +++ b/docs/commands/d2-cluster.md @@ -1,97 +1,111 @@ -# Introduction +--- +title: d2 cluster overview +sidebar_label: Overview +id: d2-cluster +slug: '/cli/cluster' +--- -`d2 cluster` helps you spin up a DHIS2 instance using containers ([Docker](https://www.docker.com)) +# d2 cluster overview + +`d2 cluster` helps you spin up a DHIS2 instance using ([Docker](https://www.docker.com)) containers. # Usage -While you can install and run `d2-cluster` from `@dhis2/cli-cluster`, -the preferred entrypoint is the root `d2` CLI. To install the `d2` CLI: +To use the `d2 cluster` command, you need to have the `@dhis2/cli` package installed globally. -```bash -yarn global add @dhis2/cli +Then you can use the `d2 cluster` command with the `--help` flag to get more information about the available commands and options. + +```sh d2 cluster --help ``` -Depending on your installation method, the following examples which use -`d2 cluster` may need to be modified to use `d2-cluster`, or `npx @dhis2/cli-cluster`. +Which will output something like this: + +```sh +Commands: + d2 cluster compose Run arbitrary docker-compose commands + against a DHIS2 cluster. + NOTE: pass -- after [aliases: c] + d2 cluster db Manage the database in a DHIS2 Docker + cluster + d2 cluster down Destroy a running container [aliases: d] + d2 cluster list List all active cluster configurations + [aliases: ls] + d2 cluster logs [service] Tail the logs from a given service + [aliases: l] + d2 cluster restart [service] Restart a cluster or cluster service + [aliases: r] + d2 cluster status Check the status of cluster containers + [aliases: s] + d2 cluster up Spin up a new cluster [aliases: u] + +Global Options: + -h, --help Show help [boolean] + -v, --version Show version number [boolean] + --verbose Enable verbose messages [boolean] + --debug Enable debug messages [boolean] + --quiet Enable quiet mode [boolean] + --config Path to JSON config file -For consistency we will use `d2 cluster`. +``` # Common concepts +Depending on your installation method, the following examples which use `d2 cluster` may need to be modified to use `d2-cluster`, or `npx @dhis2/cli-cluster`. + +For consistency we will use `d2 cluster`. + ## Release channels DHIS2 has several release channels, such as **dev** and **stable**. -To each channel several artifacts can be published, so the **stable** -channel contains all the stable releases of DHIS2, such as 2.32.0, -2.32.1, etc. +To each channel several artifacts can be published, so the **stable** channel contains all the stable releases of DHIS2, such as 2.39.0, 2.40.0.1, etc. -The **dev** channel is the latest build straight from the development -branches. There is one development branch per supported release of -DHIS2. +The **dev** channel is the latest build straight from the development branches. There is one development branch per supported release of DHIS2. -For our Docker images, that means that we have one repo on Docker Hub -per channel: +> Keep in mind with the development branch it's a work in progress, so it might not be stable or cause unexpected issues. Never use these for production environments. + +For our Docker images, that means that we have one repo on Docker Hub per channel: - Stable: https://hub.docker.com/r/dhis2/core - Dev: https://hub.docker.com/r/dhis2/core-dev ## Tags -Within each Docker repo, we have multiple tags. The channel coupled with -the tag uniquely identifies a built DHIS2 Docker image. This is -important for how the `cluster` command works. +Within each Docker repo, we have multiple tags. The channel coupled with the tag uniquely identifies a built DHIS2 Docker image. This is important for how the `cluster` command works. -For the **stable channel** each tag represents a formally released version -of DHIS2. +For the **stable channel** each tag represents a formally released version of DHIS2. For example: -- [2.32.0](https://github.com/dhis2/dhis2-core/tree/2.32.0) -- [2.31.3](https://github.com/dhis2/dhis2-core/tree/2.31.3) +- [2.39.2.1](https://github.com/dhis2/dhis2-core/tree/2.39.2.1) +- [2.40.0](https://github.com/dhis2/dhis2-core/tree/2.40.0) -For the **dev channel**, each tag represents the last build from the -development branches in +For the **dev channel**, each tag represents the last build from the development branches in [dhis2/dhis2-core](https://github.com/dhis2/dhis2-core): - [master](https://github.com/dhis2/dhis2-core/tree/master) -- [2.32](https://github.com/dhis2/dhis2-core/tree/2.32) -- [2.31](https://github.com/dhis2/dhis2-core/tree/2.31) -- [2.30](https://github.com/dhis2/dhis2-core/tree/2.30) - -## Database dumps - -For development DHIS2 provides a [set of database -dumps](https://github.com/dhis2/dhis2-demo-db) which are essential in -getting a usable environment up and running quickly. +- [2.38](https://github.com/dhis2/dhis2-core/tree/2.38) +- [2.39](https://github.com/dhis2/dhis2-core/tree/2.39) +- [2.40](https://github.com/dhis2/dhis2-core/tree/2.40) -Most often we use the [Sierra -Leone](https://github.com/dhis2/dhis2-demo-db/tree/master/sierra-leone) -dumps. +For more tags you can look at the tags page at the GitHub repository: https://github.com/dhis2/dhis2-core/tags -# Usage - -## Getting help +## Database dumps -Remember that the help is your friend: +For development DHIS2 provides a [set of database dumps](https://databases.dhis2.org/) which are essential in getting a usable environment up and running quickly. -```bash -d2 cluster --help -``` +There are database dumps per version of DHIS2, but also for the dev channel. Look at the filenames to see which version they are for. -## Command layout +# d2 cluster command layout -There are two arguments that are always required for the `cluster` to -command to be able to do anything at all: `{command}` and `{name}`. +There are two arguments that are always required for the `cluster` to command to be able to do anything at all: `{command}` and `{name}`. ```bash d2 cluster {command} {name} ``` -The command refers to an action, like `up` or `down` (see below for more information and examples) and the name is the -name of the cluster to operate on, which can be anything you like, like -`mydev`, `superfly`, or `2.32`. +The command refers to an action, like `up` or `down` (see below for more information and examples) and the name is the name of the cluster to operate on, which can be anything you like, like `mydev`, `superfly`, or `2.40`. -### Command `up` +## Command `up` This command spins up a new cluster: @@ -99,7 +113,17 @@ This command spins up a new cluster: d2 cluster up {name} ``` -### Command `down` +To spin up a cluster for version `2.40` for example, you can use the following command: + +```bash +d2 cluster up 2.40 --db-version 2.40 +``` + +This assumes a db-version of 2.40 exists, and a docker container with 2.40 exists. Make sure to check the [database dumps](#database-dumps) and [release channels](#release-channels) sections for more information. + +To read more in-depth about spinning up a stable release, check the [stable](../recipes/stable.md) page. + +## Command `down` This command destroys a running container: @@ -107,61 +131,62 @@ This command destroys a running container: d2 cluster down {name} ``` -#### Command `down --clean` +To destroy a cluster for version `2.40`, which we created above, for example, you can use the following command: + +```bash +d2 cluster down 2.40 +``` -This command brings down a cluster and cleans up after itself. This destroys all containers and volumes associated with the cluster. For example, this means that the attached database will be wiped so it is useful when you want to remove a cluster entirely. +### Command `down --clean` + +This command brings down a cluster and cleans up after itself. This destroys all containers and volumes associated with the cluster. For example, this means that the attached database will be wiped so it is useful when you want to remove a cluster entirely. Replace the `{name}` with the name of the cluster you want to remove, such as 2.40 above. ```bash d2 cluster down {name} --clean ``` -## Arguments +# Arguments -In addition to the command and name, there are more arguments you can -pass to `cluster` to customize your environment. If the arguments are -omitted there is some fallback logic, so even if they are not used, they -are important to know about. +In addition to the command and name, there are more arguments you can pass to `cluster` to customize your environment. If the arguments are omitted there is some fallback logic, so even if they are not used, they are important to know about. - `--channel`: This matches to the Docker Hub repository mentioned above in [Release channels](#release-channels). E.g. `dev`. - `--dhis2-version`: This matches to the [tag name within a Docker Hub repo](#tags). E.g. - [`2.32`](https://hub.docker.com/r/dhis2/core-dev/tags) + [`2.40`](https://hub.docker.com/r/dhis2/core-dev/tags) - `--db-version`: This matches to the database dumps mentioned in - [Database dumps](#database-dumps). E.g. `dev` or `2.32`. + [Database dumps](#database-dumps). E.g. `dev` or `2.40`. -So through a combination of these arguments: `channel`, `dhis2-version`, -and `db-version` we can spin up a cluster. +So through a combination of these arguments: `channel`, `dhis2-version`, and `db-version` we can spin up a cluster. # Configuration ## Cached configuration -To avoid having to pass in all arguments over and over when using the -`up` and `down` commands often, the `cluster` command caches your -configuration per cluster in a `config.json` file. +To avoid having to pass in all arguments over and over when using the `up` and `down` commands often, the `cluster` command caches your configuration per cluster in a `config.json` file. ```bash -d2 debug cache list clusters/2.32.0 +d2 debug cache list clusters/2.40.1 ┌────────────────┬──────┬─────────────────────┐ │ Name │ Size │ Modified │ ├────────────────┼──────┼─────────────────────┤ -│ config.json │ 171 │ 2019-06-06 11:07:37 │ +│ config.json │ 205 │ 2023-10-05 06:59:04 │ ├────────────────┼──────┼─────────────────────┤ -│ docker-compose │ 512 │ 2019-06-06 11:07:32 │ +│ docker-compose │ 160 │ 2023-08-09 12:52:24 │ └────────────────┴──────┴─────────────────────┘ ``` And it looks like this: ```bash -cat ~/.cache/d2/cache/clusters/2.32.0/config.json +cat ~/.cache/d2/cache/clusters/2.40.1/config.json { - "channel": "dev", - "dbVersion": "2.32", - "dhis2Version": "2.32.0", + "channel": "stable", + "dbVersion": "2.40", + "dhis2Version": "2.40.1", + "dhis2Home": "/opt/dhis2", "customContext": false, "image": "dhis2/core{channel}:{version}", "port": 8080 @@ -172,7 +197,7 @@ This means that if you run a command sequence like: ```bash d2 cluster up superfly \ - --db-version 2.31 \ + --db-version 2.40 \ --dhis2-version master \ --seed \ --custom-context \ @@ -184,14 +209,13 @@ d2 cluster down superfly d2 cluster up superfly ``` -The second time you run `up superfly` it will use the configuration from -the first run: +The second time you run `up superfly` it will use the configuration from the first run: ```bash cat ~/.cache/d2/cache/clusters/superfly/config.json { "channel": "dev", - "dbVersion": "2.31", + "dbVersion": "2.40", "dhis2Version": "master", "customContext": true, "image": "dhis2/core{channel}:{version}", @@ -211,8 +235,7 @@ Purged cache item clusters/superfly/config.json ## Persistent configuration -It is also possible to set up your clusters in the `d2` configuration -file, e.g. `~/.config/d2/config.js`: +It is also possible to set up your clusters in the `d2` configuration file, e.g. `~/.config/d2/config.js`: ```js module.exports = { @@ -221,7 +244,7 @@ module.exports = { clusters: { superfly: { channel: 'dev', - dbVersion: '2.31', + dbVersion: '2.40', dhis2Version: 'master', customContext: true, image: 'dhis2/core{channel}:{version}', @@ -247,8 +270,7 @@ cat ~/.cache/d2/cache/clusters/superfly/config.json } ``` -From here it's possible to override the configuration file properties -for a cluster as well: +From here it's possible to override the configuration file properties for a cluster as well: ``` # port is 9999 in ~/.config/d2/config.js:clusters.superfly.port @@ -257,6 +279,4 @@ d2 cluster up superfly --port 8888 # port is saved as 8888 in ~/.cache/d2/cache/clusters/superfly/config.json:port ``` -Now for each subsequence `down` and `up` command, the cached config will -take priority over the persistent configuration. When you clear the -cache, the persistent configuration will come into effect again. +Now for each subsequence `down` and `up` command, the cached config will take priority over the persistent configuration. When you clear the cache, the persistent configuration will come into effect again. diff --git a/docs/commands/d2-utils-release.md b/docs/commands/d2-utils-release.md index 40c01197..af7b6614 100644 --- a/docs/commands/d2-utils-release.md +++ b/docs/commands/d2-utils-release.md @@ -1,30 +1,26 @@ +--- +title: d2 utils release +sidebar_label: d2 utils release +id: d2-utils-release +slug: '/cli/utils/release' +--- + # Introduction -`d2 utils release` allows you to publish libraries and applications to -various package repositories. +`d2 utils release` allows you to publish libraries and applications to various package repositories. # Usage -Internally the `release` command utilizes [semantic -release](https://github.com/semantic-release/semantic-release), so -understanding how that tool operates is helpful. +Internally the `release` command utilizes [semantic release](https://github.com/semantic-release/semantic-release), so understanding how that tool operates is helpful. -Simply put, every time a commit appears on the `master` branch, the -fully automated release process begins, and the commit is released. +Simply put, every time a commit appears on the `master` branch, the fully automated release process begins, and the commit is released. # Advanced usage ## Distribution channels -We support the default channels recommended by semantic release, and -there is a [good -walkthrough](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/distribution-channels.md) -of them available on their docs. +We support the default channels recommended by semantic release, and there is a [good walkthrough](https://github.com/semantic-release/semantic-release/blob/master/docs/recipes/distribution-channels.md) of them available on their docs. -Our [GH Actions -workflow](https://github.com/dhis2/workflows/blob/master/ci/node-publish.yml#L5) -is kept in sync with those defaults. +Our [GH Actions workflow](https://github.com/dhis2/workflows/blob/master/ci/node-publish.yml#L5) is kept in sync with those defaults. -It is possible to e.g. only use the `master` branch for releases by -restricting the `on.push.branches` list in the workflow file in the -local repo. +It is possible to e.g. only use the `master` branch for releases by restricting the `on.push.branches` list in the workflow file in the local repo. diff --git a/docs/commands/d2.md b/docs/commands/d2.md index 5f3d8fe1..84a56ca8 100644 --- a/docs/commands/d2.md +++ b/docs/commands/d2.md @@ -1,25 +1,19 @@ -# Installation +--- +title: d2 CLI overview +sidebar_label: d2 overview +id: d2-overview +slug: '/cli/d2-overview' +--- -The CLI can be installed globally with `npm` or `yarn` as follows: +# d2 CLI Overview -```sh -> yarn global add @dhis2/cli -OR -> npm install --global @dhis2/cli -``` +First, make sure you've got the CLI installed globally before you can use it. Once you've installed it you can run the `d2 --help` command to see the available commands, as shown below. -You can also run the CLI ad-hoc with `npx`, no installation necessary (sacrifices startup performance): - -``` -> npx @dhis2/cli +```sh +d2 --help ``` -# Usage - ```sh -> d2 --help -d2 - Commands: d2 app Front-end application and library commands d2 cluster Manage DHIS2 Docker clusters [aliases: c] @@ -29,22 +23,11 @@ Commands: d2 utils Utils for miscellaneous operations d2 debug Debug local d2 installation -Options: - --version Show version number [boolean] - --config Path to JSON config file - -h, --help Show help [boolean] -``` - -# Examples - -Bootstrap a new DHIS2 cli module - -```sh -> d2 create cli -``` - -Spin up a DHIS2 server installation on port 8082 with default seeded [Sierra Leone demo database](https://github.com/dhis2/dhis2-demo-db) (requires [Docker](https://www.docker.com/products/docker-desktop)) - -```sh -> d2 cluster up 2.32.0 --port 8082 --seed --db-version 2.32 +Global Options: + -h, --help Show help [boolean] + -v, --version Show version number [boolean] + --verbose Enable verbose messages [boolean] + --debug Enable debug messages [boolean] + --quiet Enable quiet mode [boolean] + --config Path to JSON config file ``` diff --git a/docs/getting-started.md b/docs/getting-started.md index 1d3aea66..f440dfba 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,15 +1,29 @@ +--- +# This file is only used on the bundled docsify site +--- + # Install the CLI -``` +```bash yarn global add @dhis2/cli +``` -# or +or through npm +``` npm install --global @dhis2/cli ``` -# Verify that it is available on PATH +## Verify that it is available on PATH ``` d2 --version ``` + +## Ad-hoc usage + +You can also run the CLI ad-hoc with `npx`, no installation necessary (sacrifices startup performance). So only do this if you've got a good use case for it. In most cases you'll want to install it globally. + +``` +> npx @dhis2/cli +``` diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..5cbe5edd --- /dev/null +++ b/docs/index.html @@ -0,0 +1,18 @@ + + + + + Redirecting to Developer Portal + + +

Redirecting to Developer Portal...

+ + + + diff --git a/docs/recipes/custom-dhis-config.md b/docs/recipes/custom-dhis-config.md index 959bd95d..55873cfb 100644 --- a/docs/recipes/custom-dhis-config.md +++ b/docs/recipes/custom-dhis-config.md @@ -1,12 +1,16 @@ +--- +title: Use a custom dhis.conf +sidebar_label: Custom dhis.conf +id: custom-dhis-config +slug: '/cli/recipes/custom-dhis-config' +--- + # Spin up environment with custom dhis.conf file -Given that you have a `dhis.conf` file on somewhere on your computer, -you can override the [default -`dhis.conf`](https://github.com/dhis2/docker-compose/blob/master/cluster/config/DHIS2_home/dhis.conf) -supplied by the [Docker Compose setup](https://github.com/dhis2/docker-compose/blob/master/cluster/docker-compose.yml#L7). +Given that you have a `dhis.conf` file on somewhere on your computer, you can override the [default `dhis.conf`](https://github.com/dhis2/docker-compose/blob/master/cluster/config/DHIS2_home/dhis.conf) supplied by the [Docker Compose setup](https://github.com/dhis2/docker-compose/blob/master/cluster/docker-compose.yml#L7). To do so, use the `--dhis2-config` switch to `d2 cluster up`: ``` -d2 cluster up 2.33.1 --dhis2-config /path/to/custom-dhis.conf +d2 cluster up 2.40.0 --dhis2-config /path/to/custom-dhis.conf ``` diff --git a/docs/recipes/custom-image.md b/docs/recipes/custom-image.md index 6ee6650e..347c37c4 100644 --- a/docs/recipes/custom-image.md +++ b/docs/recipes/custom-image.md @@ -1,9 +1,15 @@ +--- +title: Spin up a custom DHIS2 Docker image +sidebar_label: Use a custom docker image +id: custom-docker-image +slug: '/cli/recipes/custom-docker-image' +--- + # Spin up a custom DHIS2 Docker image ## Build the custom image -For detailed instructions on how to build a complete DHIS2 image [refer -to the instructions in the core repository](https://github.com/dhis2/dhis2-core/blob/master/docker/README.md). +For detailed instructions on how to build a complete DHIS2 image [refer to the instructions in the core repository](https://github.com/dhis2/dhis2-core/blob/master/docker/README.md). ```bash cd /path/to/dhis2-core @@ -14,8 +20,7 @@ ONLY_DEFAULT=1 ./docker/build-containers.sh core:superfly local ## Use image with d2-cluster -This will spin up DHIS2 and seed the database with the **dev** dump of -the database. +This will spin up DHIS2 and seed the database with the **dev** dump of the database. ```bash d2 cluster up superfly \ diff --git a/docs/recipes/development.md b/docs/recipes/development.md index 056d7478..e53e5d62 100644 --- a/docs/recipes/development.md +++ b/docs/recipes/development.md @@ -1,24 +1,25 @@ +--- +title: Spin up a development version +sidebar_label: Use a development version +id: development +slug: '/cli/recipes/development' +--- + # Spin up a development version -Let's switch to the **dev** channel as we want the bleeding edge build -from 2.32. We want it seeded with a 2.32 dump so we are going to run it -with `--seed`. +Let's switch to the **dev** channel as we want the bleeding edge build from DHIS2 v40. We want it seeded with a v40 dump so we are going to run it with `--seed`. ```bash -d2 cluster up 2.32 --channel dev --seed +d2 cluster up 2.40 --channel dev --seed # result # --- # channel: dev -# dhis2Version: 2.32 -# dbVersion: 2.32 +# dhis2Version: 2.40 +# dbVersion: 2.40 ``` -Since the 2.32 branch exists in -[dhis2-core](https://github.com/dhis2/dhis2-core/tree/2.32) and the 2.32 -dump exists in -[dhis2-demo-db](https://github.com/dhis2/dhis2-demo-db/tree/master/sierra-leone/2.32) -the tool doesn't need more information to create an environment. +Since the 2.40 branch exists in [dhis2-core](https://github.com/dhis2/dhis2-core/tree/2.32) and the 2.40 dump exists on the [database site](https://databases.dhis2.org/) the tool doesn't need more information to create an environment. Now, let's run a `master` build from the **dev** channel: @@ -35,11 +36,7 @@ d2 cluster up master \ # dbVersion: dev ``` -Since the `--dhis2-version` argument was omitted, it used the `{name}` -as fallback. Since we used `master` as the name, and the `master` tag -exists in the -[dhis2/core-dev](https://cloud.docker.com/u/dhis2/repository/docker/dhis2/core-dev/tags) -it is able to resolve a complete environment. +Since the `--dhis2-version` argument was omitted, it used the `{name}` as fallback. Since we used `master` as the name, and the `master` tag exists in the [dhis2/core-dev](https://cloud.docker.com/u/dhis2/repository/docker/dhis2/core-dev/tags) it is able to resolve a complete environment. We could also have run: @@ -51,5 +48,4 @@ d2 cluster up master \ --seed ``` -The name can be anything you wish, but remember to specify `channel`, -`dhis2-version`, and `db-version` in that case. +The name can be anything you wish, but remember to specify `channel`, `dhis2-version`, and `db-version` in that case. diff --git a/docs/recipes/stable.md b/docs/recipes/stable.md index f7171666..3491a22b 100644 --- a/docs/recipes/stable.md +++ b/docs/recipes/stable.md @@ -1,34 +1,41 @@ +--- +title: Spin up a stable version +sidebar_label: Use a stable version +id: stable +slug: '/cli/recipes/stable' +--- + # Spin up a stable version -First up, in the best case scenario where you want to run DHIS2 2.32.0 on -an empty database, you are able to run: +Spinning up a stable version is what you generally want. The Stable version is the one tested and released by the DHIS2 core team. It is the version that is recommended for production use, and therefore also the best to develop on. However, sometimes it makes sense to check out the development branch to test with the latest features. Read more about the [development branch here](./development.md). + +First up, in the best case scenario where you want to run DHIS2 v40 on an empty database, you are able to run: ```bash -d2 cluster up 2.32.0 +d2 cluster up 2.40 # result # --- # channel: stable -# dhis2Version: 2.32.0 +# dhis2Version: 2.40.0 # dbVersion: empty ``` -Usually you want to `seed` your database with a database dump from -Sierra Leone to have an instance set up with data. If you add the -`--seed` command to the command above, it will try to find the database -dump 2.32.0 in the -[dhis2-db-demo](https://github.com/dhis2/dhis2-demo-db/tree/master/sierra-leone) -repo. That doesn't exist, but 2.32 does. +Usually you want to `seed` your database with a database dump from Sierra Leone to have an instance set up with data. If you add the `--seed` command to the command above, it will try to find the database dump `2.40.0` on the [databases](https://databases.dhis2.org/) site. If it doesn't exist it will throw an error. ```bash -d2 cluster up 2.32.0 --seed -# fail: there's no db dump with 2.32.0 +d2 cluster up 2.40.0 --seed +# fail: if there's no 2.40.0 database dump, it will fail +``` -d2 cluster up 2.32.0 --db-version 2.32 --seed +You'll need to provide a `--db-version` argument to tell the command which database dump to use. The database dump needs to exist on the [databases](https://databases.dhis2.org/) site. + +```bash +d2 cluster up 2.40.0 --db-version 2.40 --seed # result # --- # channel: stable -# dhis2Version: 2.32.0 -# dbVersion: 2.32 +# dhis2Version: 2.40.0 +# dbVersion: 2.40 ``` diff --git a/package.json b/package.json index a9b8731a..a3a08ce8 100644 --- a/package.json +++ b/package.json @@ -12,12 +12,12 @@ "license": "BSD-3-Clause", "devDependencies": { "@dhis2/cli-style": "^9.0.1", - "@dhis2/cli-utils-docsite": "^3.1.2", + "@dhis2/cli-utils-docsite": "^3.2.0", "tape": "^4.13.2", "tape-await": "^0.1.2" }, "scripts": { - "build:docs": "d2-utils-docsite build ./docs -o ./dist", + "docs:build": "mkdir -p dist && cp docs/index.html dist/", "start": "d2-utils-docsite serve ./docs -o ./dist", "test": "tape packages/**/tests/*.js" }, @@ -26,5 +26,8 @@ "name": "DHIS2 CLI", "description": "A unified CLI for DHIS2 development workflows." } + }, + "resolutions": { + "@ls-lint/ls-lint": "2.0.1" } } diff --git a/yarn.lock b/yarn.lock index 4ca993e4..952455b0 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2132,6 +2132,26 @@ react-docgen "^6.0.0-alpha.0" url-join "^4.0.1" +"@dhis2/cli-utils-docsite@^3.2.0": + version "3.2.0" + resolved "https://registry.yarnpkg.com/@dhis2/cli-utils-docsite/-/cli-utils-docsite-3.2.0.tgz#a9234bd71d1b716dfdba54e711bbc0ff8e102dd1" + integrity sha512-U7gUb7PSHdCkWlzMznUQCQR2Lkp+/pMwoo8DC01OzL8JjFojZtP+iSY4Zx4JCmQz7s1Ncyy1bmwRx1+ogQCSsQ== + dependencies: + "@dhis2/cli-helpers-engine" "^3.0.0" + "@dhis2/cli-helpers-template" "^3.0.0" + ast-types "^0.14.2" + chokidar "^3.3.1" + front-matter "^3.1.0" + fs-extra "^8.1.0" + glob "^7.1.7" + hyperscript-html "^2.0.0" + jsdoc-to-markdown "^5.0.3" + live-server "^1.2.1" + marked "^2.1.3" + match-all "^1.2.5" + react-docgen "^6.0.0-alpha.0" + url-join "^4.0.1" + "@dhis2/d2-i18n@^1.1.0": version "1.1.0" resolved "https://registry.yarnpkg.com/@dhis2/d2-i18n/-/d2-i18n-1.1.0.tgz#ec777c5091f747e4c5aa4f9801c62ba4d1ef3d16" @@ -2656,10 +2676,10 @@ "@types/yargs" "^16.0.0" chalk "^4.0.0" -"@ls-lint/ls-lint@^1.9.2": - version "1.9.2" - resolved "https://registry.yarnpkg.com/@ls-lint/ls-lint/-/ls-lint-1.9.2.tgz#689f1f4c06072823a726802ba167340efcefe19c" - integrity sha512-sugEjWjSSy9OHF6t1ZBLZCAROj52cZthB9dIePmzZzzMwmWwy3qAEMSdJheHeS1FOwDZI7Ipm1H/bWgzJNnSAw== +"@ls-lint/ls-lint@2.0.1", "@ls-lint/ls-lint@^1.9.2": + version "2.0.1" + resolved "https://registry.yarnpkg.com/@ls-lint/ls-lint/-/ls-lint-2.0.1.tgz#27a0513fde8e06704ff174b0a696d473190b8874" + integrity sha512-z+sGTPWHQ2nWRj2UsDFSEQDOCw2iIjP2bPU/K1wgLNkWUv7J8WjzoBsZLgUqIgD1Sqi7zpksFTtTymgnUwramA== "@nodelib/fs.scandir@2.1.5": version "2.1.5" @@ -17079,8 +17099,10 @@ watchpack@^1.7.4: resolved "https://registry.yarnpkg.com/watchpack/-/watchpack-1.7.5.tgz#1267e6c55e0b9b5be44c2023aed5437a2c26c453" integrity sha512-9P3MWk6SrKjHsGkLT2KHXdQ/9SNkyoJbabxnKOoJepsvJjJG8uYTR3yTPxPQvNDI3w4Nz1xnE0TLHK4RIVe/MQ== dependencies: + chokidar "^3.4.1" graceful-fs "^4.1.2" neo-async "^2.5.0" + watchpack-chokidar2 "^2.0.1" optionalDependencies: chokidar "^3.4.1" watchpack-chokidar2 "^2.0.1"