diff --git a/README.md b/README.md index 2bb844ccf..36e20ec24 100644 --- a/README.md +++ b/README.md @@ -98,14 +98,24 @@ curl -fsSL https://d2lang.com/install.sh | sh -s -- You can run the install script with `--dry-run` to see the commands that will be used to install without executing them. -To uninstall: +Or if you have Go installed you can install from source though you won't get the manpage: + +```sh +go install oss.terrastruct.com/d2@latest +``` + +To uninstall with the install script: ```sh curl -fsSL https://d2lang.com/install.sh | sh -s -- --uninstall ``` -For detailed installation docs, with alternative methods and examples for each OS, see -[./docs/INSTALL.md](./docs/INSTALL.md). +For detailed installation docs, see [./docs/INSTALL.md](./docs/INSTALL.md). +We demonstrate alternative methods and examples for each OS. + +As well, the functioning of the install script is described in detail to alleviate any +concern of its use. We recommend using your OS's package manager directly instead for +improved security but the install script is by no means insecure. ## D2 as a library diff --git a/ci/fmt.sh b/ci/fmt.sh index 75c1f1924..4fb39da34 100755 --- a/ci/fmt.sh +++ b/ci/fmt.sh @@ -6,4 +6,7 @@ cd -- "$(dirname "$0")/.." if is_changed README.md; then sh_c tocsubst --skip 1 README.md fi +if is_changed docs/INSTALL.md; then + sh_c tocsubst --skip 1 docs/INSTALL.md +fi ./ci/sub/fmt/make.sh diff --git a/ci/release/_install.sh b/ci/release/_install.sh index 49f936ffc..510a9c52d 100755 --- a/ci/release/_install.sh +++ b/ci/release/_install.sh @@ -91,6 +91,9 @@ note: Deleting the unarchived releases will cause --uninstall to stop working. You can rerun install.sh to update your version of D2. install.sh will avoid reinstalling if the installed version is the latest unless --force is passed. + +See https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md#security for +documentation on its security. EOF } @@ -506,4 +509,7 @@ brew() { HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_NO_AUTO_UPDATE=1 command brew "$@" } +# The main function does more than provide organization. It provides robustness in that if +# the install script was to only partial download into sh, sh will not execute it because +# main is not invoked until the very last byte. main "$@" diff --git a/ci/release/changelogs/next.md b/ci/release/changelogs/next.md index 4c6e6f979..bb3d79e4f 100644 --- a/ci/release/changelogs/next.md +++ b/ci/release/changelogs/next.md @@ -17,7 +17,7 @@ - `-b/--bundle` flag to `d2` now works and bundles all image assets directly as base64 data urls. [#278](https://github.com/terrastruct/d2/pull/278) -#### Improvements ๐Ÿ”ง +#### Improvements ๐Ÿงน - Local images can now be included, e.g. `icon: ./my_img.png`. [#146](https://github.com/terrastruct/d2/issues/146) diff --git a/ci/release/changelogs/template.md b/ci/release/changelogs/template.md index dd3f64b05..e5cf9fc34 100644 --- a/ci/release/changelogs/template.md +++ b/ci/release/changelogs/template.md @@ -1,5 +1,5 @@ #### Features ๐Ÿš€ -#### Improvements ๐Ÿ”ง +#### Improvements ๐Ÿงน #### Bugfixes ๐Ÿ”ด diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 95d677851..d128de725 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -3,13 +3,12 @@ You may install D2 through any of the following methods. - -- [install.sh](#installsh) -- [macOS (Homebrew)](#macos-homebrew) -- [Standalone](#standalone) -- [From source](#from-source) - - +- install.sh + - Security +- macOS (Homebrew) +- Standalone +- From source +- Coming soon ## install.sh @@ -31,6 +30,37 @@ methods: curl -fsSL https://d2lang.com/install.sh | sh -s -- --help ``` +### Security + +The install script is not the most secure way to install d2. We recommend that if +possible, you use your OS's package manager directly or install from source with `go` as +described below. + +But this does not mean the install script is insecure. There is no major flaw that +the install script is more vulnerable to than any other method of manual installation. +The most secure installation method involves a second independent entity, i.e your OS +package repos or Go's proxy server. + +We're careful shell programmers and are aware of the many footguns of the unix shell. Our +script was written carefully and with detail. For example, it is not vulnerable to partial +execution and the entire script runs with `set -eu` and very meticulous quoting. + +It follows the XDG standards, installs d2 properly into a unix hierarchy path (defaulting +to /usr/local though you can use ~/.local to avoid sudo if you'd like) and allows for easy +uninstall. + +Some other niceties are that it'll tell you if you need to adjust `$PATH` or `$MANPATH` to +access d2 and its manpages. It can also install +[TALA](https://github.com/terrastruct/tala) for you with `--tala`. You can also use it to +install a specific version of `d2` with `--version`. Run it with `--help` for more more +detailed docs on its various options and features. + +If you're still concerned, remember you can run with `--dry-run` to avoid executing +anything permanent. + +The install script does not yet verify any signature on the downloaded release +but that is coming soon. [#315](https://github.com/terrastruct/d2/issues/315) + ## macOS (Homebrew) If you're on macOS, you can install with `brew`. @@ -86,6 +116,14 @@ You can always install from source: go install oss.terrastruct.com/d2@latest ``` +To install a proper release from source clone the repository and then: + +```sh +./ci/release/build.sh --install +# To uninstall: +# ./ci/release/build.sh --uninstall +``` + ## Coming soon - Docker image diff --git a/install.sh b/install.sh index a951260b4..f6f1c4620 100755 --- a/install.sh +++ b/install.sh @@ -576,6 +576,9 @@ note: Deleting the unarchived releases will cause --uninstall to stop working. You can rerun install.sh to update your version of D2. install.sh will avoid reinstalling if the installed version is the latest unless --force is passed. + +See https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md#security for +documentation on its security. EOF } @@ -991,4 +994,7 @@ brew() { HOMEBREW_NO_INSTALL_CLEANUP=1 HOMEBREW_NO_AUTO_UPDATE=1 command brew "$@" } +# The main function does more than provide organization. It provides robustness in that if +# the install script was to only partial download into sh, sh will not execute it because +# main is not invoked until the very last byte. main "$@"