From 43a5981b93cfaab58cf497ab477d14284f5c1227 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Fri, 9 May 2025 11:35:43 +0200 Subject: [PATCH 1/4] Add install script --- .github/workflows/release.yml | 19 +++++++++++ docs/contribute/locally.md | 45 +++++++++++++------------- install.ps1 | 60 +++++++++++++++++++++++++++++++++++ install.sh | 29 +++++++++++++++++ 4 files changed, 130 insertions(+), 23 deletions(-) create mode 100644 install.ps1 create mode 100755 install.sh diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a5384acb6..81ba2a36d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -152,6 +152,15 @@ jobs: .artifacts/publish/docs-builder/release/*.zip .artifacts/publish/docs-assembler/release/*.zip + # Add install scripts to artifacts directory (only on Linux runner to avoid duplication) + - name: Copy install scripts to artifacts + if: matrix.os == 'ubuntu-latest' + run: | + mkdir -p .artifacts/publish/scripts + cp install.sh .artifacts/publish/scripts/ + cp install.ps1 .artifacts/publish/scripts/ + shell: bash + - name: Attach Distribution to release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -159,6 +168,16 @@ jobs: gh release upload ${{ needs.release-drafter.outputs.tag_name }} .artifacts/publish/docs-builder/release/*.zip gh release upload ${{ needs.release-drafter.outputs.tag_name }} .artifacts/publish/docs-assembler/release/*.zip shell: bash + + # Upload install scripts (only on Linux runner to avoid duplication) + - name: Attach install scripts to release + if: matrix.os == 'ubuntu-latest' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + gh release upload ${{ needs.release-drafter.outputs.tag_name }} install.sh + gh release upload ${{ needs.release-drafter.outputs.tag_name }} install.ps1 + shell: bash publish-release: needs: diff --git a/docs/contribute/locally.md b/docs/contribute/locally.md index 81963a460..6d19f592e 100644 --- a/docs/contribute/locally.md +++ b/docs/contribute/locally.md @@ -30,44 +30,43 @@ This guide uses the first option. If you'd like to clone the repository and buil :::{tab-item} macOS -1. **Download the Binary:** - Download the latest macOS binary from [releases](https://github.com/elastic/docs-builder/releases/latest/): - ```sh - curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip - ``` +1. **Download and run the install script** + + Run this command to download and install the latest version of `docs-builder`: -2. **Extract the Binary:** - Unzip the downloaded file: ```sh - unzip docs-builder-mac-arm64.zip + curl -L https://github.com/elastic/docs-builder/releases/latest/download/install.sh | sh ``` + This downloads the latest binary, makes it executable, and installs it to your user PATH. + +2. **Run docs-builder from a docs folder** + + Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`: -3. **Run the Binary:** - Use the `serve` command to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`: ```sh - ./docs-builder serve -p ./path/to/docs + docs-builder serve ``` ::: :::{tab-item} Windows -1. **Download the Binary:** - Download the latest Windows binary from [releases](https://github.com/elastic/docs-builder/releases/latest/): - ```sh - Invoke-WebRequest -Uri https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip -OutFile docs-builder-win-x64.zip - ``` +1. **Download and run the install script** -2. **Extract the Binary:** - Unzip the downloaded file. You can use tools like WinZip, 7-Zip, or the built-in Windows extraction tool. - ```sh - Expand-Archive -Path docs-builder-win-x64.zip -DestinationPath . + Run this command to download and install the latest version of `docs-builder`: + + ```powershell + iex (New-Object System.Net.WebClient).DownloadString('https://github.com/elastic/docs-builder/releases/latest/download/install.ps1') ``` -3. **Run the Binary:** - Use the `serve` command to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`: + This downloads the latest binary, makes it executable, and installs it to your user PATH. + +2. **Run docs-builder from a docs folder** + + Use the `serve` command from any docs folder to start serving the documentation at http://localhost:3000. The path to the `docset.yml` file that you want to build can be specified with `-p`: + ```sh - .\docs-builder serve -p ./path/to/docs + docs-builder serve ``` ::: diff --git a/install.ps1 b/install.ps1 new file mode 100644 index 000000000..f410dee38 --- /dev/null +++ b/install.ps1 @@ -0,0 +1,60 @@ +# PowerShell script to install docs-builder binary + +# Use AppData\Local for user-specific installation instead of Program Files +$targetDir = Join-Path -Path $env:LOCALAPPDATA -ChildPath "docs-builder" +$targetPath = Join-Path -Path $targetDir -ChildPath "docs-builder.exe" + +# Check if docs-builder already exists +if (Test-Path -Path $targetPath) { + Write-Host "docs-builder is already installed." + $choice = Read-Host -Prompt "Do you want to update/overwrite it? (y/n)" + switch ($choice.ToLower()) { + 'y' { Write-Host "Updating docs-builder..." } + 'n' { Write-Host "Installation aborted."; exit 0 } + Default { Write-Host "Invalid choice. Installation aborted."; exit 1 } + } +} + +# Create target directory if it doesn't exist +if (-not (Test-Path -Path $targetDir)) { + New-Item -ItemType Directory -Path $targetDir -Force | Out-Null +} + +# Download the latest Windows binary from releases +$tempZipPath = "$env:TEMP\docs-builder-win-x64.zip" +Write-Host "Downloading docs-builder binary..." +Invoke-WebRequest -Uri "https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-win-x64.zip" -OutFile $tempZipPath + +# Create a temporary directory for extraction +$tempExtractPath = "$env:TEMP\docs-builder-extract" +if (Test-Path -Path $tempExtractPath) { + Remove-Item -Path $tempExtractPath -Recurse -Force +} +New-Item -ItemType Directory -Path $tempExtractPath -Force | Out-Null + +# Extract the binary +Write-Host "Extracting binary..." +Expand-Archive -Path $tempZipPath -DestinationPath $tempExtractPath -Force + +# Copy the executable to the target location +Write-Host "Installing docs-builder..." +Copy-Item -Path "$tempExtractPath\docs-builder.exe" -Destination $targetPath -Force + +# Add to PATH if not already in PATH (using User scope instead of Machine) +$currentPath = [Environment]::GetEnvironmentVariable("PATH", [EnvironmentVariableTarget]::User) +if ($currentPath -notlike "*$targetDir*") { + Write-Host "Adding docs-builder to the user PATH..." + [Environment]::SetEnvironmentVariable( + "PATH", + "$currentPath;$targetDir", + [EnvironmentVariableTarget]::User + ) + $env:PATH = "$env:PATH;$targetDir" +} + +# Clean up temporary files +Remove-Item -Path $tempZipPath -Force +Remove-Item -Path $tempExtractPath -Recurse -Force + +Write-Host "docs-builder has been installed successfully and is available in your PATH." +Write-Host "You may need to restart your terminal or PowerShell session for the PATH changes to take effect." \ No newline at end of file diff --git a/install.sh b/install.sh new file mode 100755 index 000000000..7af05e8df --- /dev/null +++ b/install.sh @@ -0,0 +1,29 @@ +#!/bin/sh +set -e + +# Check if docs-builder already exists +if [ -f /usr/local/bin/docs-builder ]; then + echo "docs-builder is already installed." + printf "Do you want to update/overwrite it? (y/n): " + read choice + case "$choice" in + y|Y ) echo "Updating docs-builder..." ;; + n|N ) echo "Installation aborted."; exit 0 ;; + * ) echo "Invalid choice. Installation aborted."; exit 1 ;; + esac +fi + +# Download the latest macOS binary from releases +curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip + +# Extract only the docs-builder file to /tmp directory +# Use -o flag to always overwrite files without prompting +unzip -j -o docs-builder-mac-arm64.zip docs-builder -d /tmp + +# Ensure the binary is executable +chmod +x /tmp/docs-builder + +# Move the binary to a system path with force flag to overwrite +mv -f /tmp/docs-builder /usr/local/bin/docs-builder + +echo "docs-builder has been installed successfully and is available in your PATH." \ No newline at end of file From c3c2dc5984290d66ef9c743239d1455de09e5b3d Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Fri, 9 May 2025 12:04:02 +0200 Subject: [PATCH 2/4] Remove release logic --- .github/workflows/release.yml | 21 +-------------------- 1 file changed, 1 insertion(+), 20 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 81ba2a36d..34bf1e514 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -152,15 +152,6 @@ jobs: .artifacts/publish/docs-builder/release/*.zip .artifacts/publish/docs-assembler/release/*.zip - # Add install scripts to artifacts directory (only on Linux runner to avoid duplication) - - name: Copy install scripts to artifacts - if: matrix.os == 'ubuntu-latest' - run: | - mkdir -p .artifacts/publish/scripts - cp install.sh .artifacts/publish/scripts/ - cp install.ps1 .artifacts/publish/scripts/ - shell: bash - - name: Attach Distribution to release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} @@ -168,17 +159,7 @@ jobs: gh release upload ${{ needs.release-drafter.outputs.tag_name }} .artifacts/publish/docs-builder/release/*.zip gh release upload ${{ needs.release-drafter.outputs.tag_name }} .artifacts/publish/docs-assembler/release/*.zip shell: bash - - # Upload install scripts (only on Linux runner to avoid duplication) - - name: Attach install scripts to release - if: matrix.os == 'ubuntu-latest' - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - gh release upload ${{ needs.release-drafter.outputs.tag_name }} install.sh - gh release upload ${{ needs.release-drafter.outputs.tag_name }} install.ps1 - shell: bash - + publish-release: needs: - release From 8eb60564545809668d14fcfc14e51f18d7e26697 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Fri, 9 May 2025 12:06:12 +0200 Subject: [PATCH 3/4] Update docs --- docs/contribute/locally.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contribute/locally.md b/docs/contribute/locally.md index 6d19f592e..b0c8f2d83 100644 --- a/docs/contribute/locally.md +++ b/docs/contribute/locally.md @@ -35,7 +35,7 @@ This guide uses the first option. If you'd like to clone the repository and buil Run this command to download and install the latest version of `docs-builder`: ```sh - curl -L https://github.com/elastic/docs-builder/releases/latest/download/install.sh | sh + curl -L https://raw.githubusercontent.com/elastic/docs-builder/refs/heads/main/install.sh | sh ``` This downloads the latest binary, makes it executable, and installs it to your user PATH. @@ -56,7 +56,7 @@ This guide uses the first option. If you'd like to clone the repository and buil Run this command to download and install the latest version of `docs-builder`: ```powershell - iex (New-Object System.Net.WebClient).DownloadString('https://github.com/elastic/docs-builder/releases/latest/download/install.ps1') + iex (New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/elastic/docs-builder/refs/heads/main/install.ps1') ``` This downloads the latest binary, makes it executable, and installs it to your user PATH. From 4ce818a4fb5c5f7edf7a1f1adc1e0b06086560e2 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri Benedetti Date: Fri, 9 May 2025 12:09:11 +0200 Subject: [PATCH 4/4] Add sudo --- docs/contribute/locally.md | 2 +- install.ps1 | 0 install.sh | 57 +++++++++++++++++++++++++++++++++----- 3 files changed, 51 insertions(+), 8 deletions(-) mode change 100644 => 100755 install.ps1 diff --git a/docs/contribute/locally.md b/docs/contribute/locally.md index b0c8f2d83..c499984ef 100644 --- a/docs/contribute/locally.md +++ b/docs/contribute/locally.md @@ -35,7 +35,7 @@ This guide uses the first option. If you'd like to clone the repository and buil Run this command to download and install the latest version of `docs-builder`: ```sh - curl -L https://raw.githubusercontent.com/elastic/docs-builder/refs/heads/main/install.sh | sh + sudo curl -L https://raw.githubusercontent.com/elastic/docs-builder/refs/heads/main/install.sh | sh ``` This downloads the latest binary, makes it executable, and installs it to your user PATH. diff --git a/install.ps1 b/install.ps1 old mode 100644 new mode 100755 diff --git a/install.sh b/install.sh index 7af05e8df..dc6332a1a 100755 --- a/install.sh +++ b/install.sh @@ -1,8 +1,40 @@ #!/bin/sh set -e +# Determine OS type and architecture +OS=$(uname -s | tr '[:upper:]' '[:lower:]') +ARCH=$(uname -m) + +# Map architecture naming +if [ "$ARCH" = "x86_64" ]; then + ARCH="amd64" +elif [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then + ARCH="arm64" +fi + +# Determine binary to download based on OS +if [ "$OS" = "darwin" ]; then + BINARY="docs-builder-mac-$ARCH.zip" + DEFAULT_INSTALL_DIR="/usr/local/bin" +elif [ "$OS" = "linux" ]; then + BINARY="docs-builder-linux-$ARCH.zip" + DEFAULT_INSTALL_DIR="/usr/local/bin" +else + echo "Unsupported operating system: $OS" + exit 1 +fi + +# Determine if we need sudo for the install directory +INSTALL_DIR="$DEFAULT_INSTALL_DIR" +if [ ! -w "$INSTALL_DIR" ]; then + USE_SUDO=true + echo "Note: Installing to $INSTALL_DIR requires administrator privileges." +else + USE_SUDO=false +fi + # Check if docs-builder already exists -if [ -f /usr/local/bin/docs-builder ]; then +if [ -f "$INSTALL_DIR/docs-builder" ]; then echo "docs-builder is already installed." printf "Do you want to update/overwrite it? (y/n): " read choice @@ -13,17 +45,28 @@ if [ -f /usr/local/bin/docs-builder ]; then esac fi -# Download the latest macOS binary from releases -curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip +echo "Downloading docs-builder for $OS/$ARCH..." + +# Download the appropriate binary +curl -LO "https://github.com/elastic/docs-builder/releases/latest/download/$BINARY" # Extract only the docs-builder file to /tmp directory # Use -o flag to always overwrite files without prompting -unzip -j -o docs-builder-mac-arm64.zip docs-builder -d /tmp +unzip -j -o "$BINARY" docs-builder -d /tmp # Ensure the binary is executable chmod +x /tmp/docs-builder -# Move the binary to a system path with force flag to overwrite -mv -f /tmp/docs-builder /usr/local/bin/docs-builder +# Move the binary to the install directory +echo "Installing docs-builder to $INSTALL_DIR..." +if [ "$USE_SUDO" = true ]; then + sudo mv -f /tmp/docs-builder "$INSTALL_DIR/docs-builder" +else + mv -f /tmp/docs-builder "$INSTALL_DIR/docs-builder" +fi + +# Clean up the downloaded zip file +rm -f "$BINARY" -echo "docs-builder has been installed successfully and is available in your PATH." \ No newline at end of file +echo "docs-builder has been installed successfully and is available in your PATH." +echo "You can run 'docs-builder --help' to see available commands." \ No newline at end of file