Skip to content

Commit

Permalink
chore: native binaries installation docs and cd refinements (#442)
Browse files Browse the repository at this point in the history
* docs: updating installation docs

* docs: update docs

* docs: update docs

* docs: update docs - PR reviewa

* docs: update docs on supported architectures

* docs: tweak wording

* refactor: removing choco; updating snapshots and doctor; tweaking CD

* chore: patch pre-commit ignores for vendor folder

* chore: patching portability test

---------

Co-authored-by: Neil Campbell <[email protected]>
Co-authored-by: Altynbek Orumbayev <[email protected]>
  • Loading branch information
3 people authored Sep 19, 2024
1 parent 7162a62 commit 3f13704
Show file tree
Hide file tree
Showing 20 changed files with 74 additions and 376 deletions.
97 changes: 3 additions & 94 deletions .github/workflows/publish-release-packages.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ name: Publish packages to public repositories
on:
workflow_call:
inputs:
wheelArtifactName:
artifactName:
required: true
type: string
description: "The github artifact holding the wheel file which will be published"
Expand All @@ -16,11 +16,6 @@ on:
default: true
type: boolean
description: "Publish to brew repository"
do_chocolatey:
required: false
default: true
type: boolean
description: "Publish to Chocolatey repository"
do_snap:
required: false
default: true
Expand All @@ -31,32 +26,6 @@ on:
default: true
type: boolean
description: "Publish to Winget repository"
workflow_dispatch:
inputs:
release_version:
required: true
type: string
description: "The release version that will be published (e.g. 0.1.0). Note this is not the tag version."
do_brew:
required: false
default: true
type: boolean
description: "Publish to brew repository"
do_chocolatey:
required: false
default: true
type: boolean
description: "Publish to Chocolatey repository"
do_winget:
required: false
default: true
type: boolean
description: "Publish to Winget repository"
do_snap:
required: false
default: true
type: boolean
description: "Publish to snap repository"

jobs:
publish-brew:
Expand All @@ -66,84 +35,24 @@ jobs:
- name: Checkout source code
uses: actions/checkout@v4

# Download either via release or provided artifact
- name: Download wheel from release
if: ${{ github.event_name == 'workflow_dispatch' }}
run: gh release download v${{ inputs.release_version }} --pattern "*.whl" --dir dist
env:
GH_TOKEN: ${{ github.token }}

- name: Download wheel from artifact
if: ${{ github.event_name == 'workflow_call' }}
uses: actions/download-artifact@v4
with:
name: ${{ inputs.wheelArtifactName }}
path: dist

- name: Download macOS binary from release
if: ${{ github.event_name == 'workflow_dispatch' }}
run: gh release download ${{ inputs.release }} --pattern "*-brew.tar.gz" --dir dist
- name: Download binary artifact from release
run: gh release download v${{ inputs.release_version }} --pattern "*-brew.tar.gz" --dir dist
env:
GH_TOKEN: ${{ github.token }}

- name: Download macOS binary from artifact
uses: actions/download-artifact@v4
if: ${{ github.event_name == 'workflow_call' }}
with:
name: ${{ inputs.binaryArtifactName }}
path: dist

- name: Set Git user as GitHub actions
run: git config --global user.email "[email protected]" && git config --global user.name "github-actions"

- name: ls dist folder
run: ls -la dist

- name: Update homebrew cask
run: scripts/update-brew-cask.sh "dist/algokit*-py3-none-any.whl" "dist/algokit*-macos_arm64-brew.tar.gz" "dist/algokit*-macos_x64-brew.tar.gz" "algorandfoundation/homebrew-tap"
env:
TAP_GITHUB_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}

publish-chocolatey:
runs-on: windows-latest
if: ${{ inputs.do_chocolatey }}
steps:
- name: Checkout source code
uses: actions/checkout@v4

# Download either via release or provided artifact
- name: Download release
if: ${{ github.event_name == 'workflow_dispatch' }}
run: gh release download v${{ inputs.release_version }} --pattern "*.whl" --dir dist
env:
GH_TOKEN: ${{ github.token }}

- name: Download artifact
if: ${{ github.event_name == 'workflow_call' }}
uses: actions/download-artifact@v4
with:
name: ${{ inputs.artifactName }}
path: dist

- name: Update chocolatey files
id: update_chocolatey_files
run: scripts/update-chocolatey-package.ps1

- name: Build package
uses: crazy-max/ghaction-chocolatey@v2
with:
args: pack --version ${{ steps.update_chocolatey_files.outputs.version }} .\scripts\chocolatey\algokit\algokit.nuspec

- name: Set API key
uses: crazy-max/ghaction-chocolatey@v2
with:
args: apikey --api-key ${{ secrets.CHOCOLATEY_API_KEY }} -source https://push.chocolatey.org/

- name: Push package
uses: crazy-max/ghaction-chocolatey@v2
with:
args: push --source https://push.chocolatey.org/

publish-winget:
runs-on: windows-latest
if: ${{ inputs.do_winget }}
Expand Down
2 changes: 2 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ repos:
additional_dependencies: []
minimum_pre_commit_version: "0"
files: "^(src|tests)/"
exclude: "^src/algokit/core/_vendor/"
- id: mypy
name: mypy
description: "`mypy` will check Python types for correctness"
Expand All @@ -32,3 +33,4 @@ repos:
additional_dependencies: []
minimum_pre_commit_version: "2.9.2"
files: "^(src|tests)/"
exclude: "^src/algokit/core/_vendor/"
86 changes: 49 additions & 37 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,18 +86,23 @@ This is an open source project managed by the Algorand Foundation. See the [cont

The key required dependency is Python 3.10+, but some of the installation options below will install that for you. We recommend using Python 3.12+, as the `algokit compile python` command requires this version.

AlgoKit also has some runtime dependencies that also need to be available for particular commands.

> **Note**
> You can still install and use AlgoKit without these dependencies and AlgoKit will tell you if you are missing one for a given command.
> You can still install and use AlgoKit without these dependencies, and AlgoKit will tell you if you are missing one for a given command.
- **Git**: Essential for creating and updating projects from templates. Installation guide available at [Git Installation](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
- **Docker**: Necessary for running the AlgoKit LocalNet environment. Docker Compose version 2.5.0 or higher is required. See [Docker Installation](https://docs.docker.com/get-docker/).
- **Node.js**: For those working on frontend templates or building contracts using TEALScript. **Minimum required versions are Node.js `v18` and npm `v9`**. Instructions can be found at [Node.js Installation](https://nodejs.org/en/download/).

> **Note**
> If you have previously installed AlgoKit using `pipx` and would like to switch to a different installation method, please ensure that
> you first uninstall the existing version by running `pipx uninstall algokit`. Once uninstalled, you can follow the installation instructions for your preferred platform.
## Cross-platform installation

AlgoKit can be installed using OS specific package managers, or using the python tool [pipx](https://pypa.github.io/pipx/) see below for specific installation instructions.
AlgoKit can be installed using OS specific package managers, or using the python tool [pipx](https://pypa.github.io/pipx/).
See below for specific installation instructions.

### Installation Methods

- [Windows](#install-algokit-on-windows)
- [Mac](#install-algokit-on-mac)
Expand All @@ -107,50 +112,36 @@ AlgoKit can be installed using OS specific package managers, or using the python
## Install AlgoKit on Windows

> **Note**
> This method will install the most recent python3 version [via winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/). If you already have python 3.10+ installed, you may [prefer to use pipx directly instead](#install-algokit-with-pipx-on-any-os) so you can control the python version used.
> AlgoKit is supported on Windows 10 1709 (build 16299) and later.
> We only publish an x64 binary, however it also runs on ARM devices by default using the built in x64 emulation feature.
1. Ensure prerequisites are installed

- [WinGet](https://learn.microsoft.com/en-us/windows/package-manager/winget/) (should be installed by default on recent Windows 10 or later)
- [Git](https://github.com/git-guides/install-git#install-git-on-windows) (or `winget install git.git`)
- [Docker](https://docs.docker.com/desktop/install/windows-install/) (or `winget install docker.dockerdesktop`)
> **Note**
> See [our LocalNet documentation](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/localnet.md#prerequisites) for more tips on installing Docker on Windows
2. Install using WinGet

1. Install python: `winget install python.python.3.11`
2. Restart the terminal to ensure Python and pip are available on the path

> **Note**
> Windows has a feature called **App Execution Aliases** that provides redirects for the Python command that guide users to the
> Windows Store. Unfortunately these aliases can prevent normal execution of Python if Python is installed via other means, to disable them
> search for **Manage app execution aliases** from the start menu, and then turn off entries listed as
> **App Installer python.exe** or **App Installer python3.exe**.
3. Install pipx:
2. Install using winget

```
pip install --user pipx
python -m pipx ensurepath
```

4. Restart the terminal to ensure pipx is available on the path
5. Install AlgoKit via pipx: `pipx install algokit`
6. Restart the terminal to ensure AlgoKit is available on the path
```shell
winget install algokit
```

3. [Verify installation](#verify-installation)

### Maintenance

Some useful commands for updating or removing AlgoKit in the future.

- To update AlgoKit: `pipx upgrade algokit`
- To remove AlgoKit: `pipx uninstall algokit`
- To update AlgoKit: `winget upgrade algokit`
- To remove AlgoKit: `winget uninstall algokit`

## Install AlgoKit on Mac

> **Note**
> This method will install Python 3.10 as a dependency via Homebrew. If you already have python installed, you may prefer to use `pipx install algokit` as explained [here](#install-algokit-with-pipx-on-any-os).
> AlgoKit is supported on macOS Big Sur (11) and later for both x64 and ARM (Apple Silicon)

1. Ensure prerequisites are installed

Expand All @@ -160,7 +151,12 @@ Some useful commands for updating or removing AlgoKit in the future.
> **Note**
> Docker requires MacOS 11+

2. Install using Homebrew `brew install algorandfoundation/tap/algokit`
2. Install using Homebrew

```shell
brew install algorandfoundation/tap/algokit
```

3. Restart the terminal to ensure AlgoKit is available on the path
4. [Verify installation](#verify-installation)

Expand All @@ -173,18 +169,29 @@ Some useful commands for updating or removing AlgoKit in the future.

## Install AlgoKit on Linux

1. Ensure prerequisites are installed

- [Python 3.10+](https://www.python.org/downloads/)
> **Note**
> AlgoKit is compatible with Ubuntu 16.04 and later, Debian, RedHat, and any distribution that supports [Snap](https://snapcraft.io/docs/installing-snapd), but it is only supported on x64 architecture; ARM is not supported.

> **Note**
> There is probably a better way to install Python than to download it directly, e.g. your local Linux package manager
1. Ensure prerequisites are installed

- [pipx](https://pypa.github.io/pipx/#on-linux-install-via-pip-requires-pip-190-or-later)
- [Snap](https://snapcraft.io/docs/installing-snapd) (should be installed by default on Ubuntu 16.04.4 LTS (Xenial Xerus) or later)
- [Git](https://github.com/git-guides/install-git#install-git-on-linux)
- [Docker](https://docs.docker.com/desktop/install/linux-install/)

2. Continue with step 2 in the following section to install via [pipx](#install-algokit-with-pipx-on-any-os)
2. Install using snap

```shell
snap install algokit --classic
```

3. [Verify installation](#verify-installation)

### Maintenance

Some useful commands for updating or removing AlgoKit in the future.

- To update AlgoKit: `snap refresh algokit`
- To remove AlgoKit: `snap remove --purge algokit`

## Install AlgoKit with pipx on any OS

Expand All @@ -195,7 +202,12 @@ Some useful commands for updating or removing AlgoKit in the future.
- [Git](https://github.com/git-guides/install-git)
- [Docker](https://docs.docker.com/get-docker/)

2. Install using pipx `pipx install algokit`
2. Install using pipx

```shell
pipx install algokit
```

3. Restart the terminal to ensure AlgoKit is available on the path
4. [Verify installation](#verify-installation)

Expand Down
39 changes: 0 additions & 39 deletions scripts/chocolatey/algokit/README.md

This file was deleted.

33 changes: 0 additions & 33 deletions scripts/chocolatey/algokit/algokit.nuspec

This file was deleted.

Binary file removed scripts/chocolatey/algokit/algorand-logo-512.png
Binary file not shown.
Loading

1 comment on commit 3f13704

@github-actions
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Coverage

Coverage Report
FileStmtsMissCoverMissing
src/algokit
   __init__.py15753%6–13, 17–24, 32–34
   __main__.py440%1–7
src/algokit/cli
   __init__.py47394%31–34
   codespace.py50982%28, 114, 137, 150–155
   completions.py108992%63–64, 83, 93–99
   dispenser.py121199%77
   doctor.py53394%146–148
   explore.py631576%35–40, 42–47, 85–92, 113
   generate.py70396%76–77, 155
   goal.py47198%79
   init.py3102492%491–492, 497–498, 501, 522, 525–527, 538, 542, 600, 626, 655, 688, 697–699, 702–707, 720, 739, 751–752
   localnet.py1523279%65, 86–113, 133–137, 170, 182, 197–207, 220, 271, 292–293
   task.py34391%25–28
src/algokit/cli/common
   utils.py37295%137, 139
src/algokit/cli/project
   bootstrap.py32197%33
   deploy.py1172083%47, 49, 102, 125, 147–149, 270, 277, 291–299, 302–311
   link.py891682%60, 65–66, 101–105, 115–120, 148–149, 218–219, 223
   list.py33585%21–23, 51–56
   run.py46296%38, 174
src/algokit/cli/tasks
   analyze.py81199%81
   assets.py821384%65–66, 72, 74–75, 105, 119, 125–126, 132, 134, 136–137
   ipfs.py51884%52, 80, 92, 94–95, 105–107
   mint.py1061586%51, 73, 100–103, 108, 113, 131–132, 158, 335–339
   send_transaction.py651085%52–53, 57, 89, 158, 170–174
   sign_transaction.py59886%21, 28–30, 71–72, 109, 123
   transfer.py39392%26, 90, 117
   utils.py1144660%29–37, 43–46, 78–79, 103–104, 128–136, 155–165, 212, 261–262, 282–293, 300–302, 324
   vanity_address.py561082%41, 45–48, 112, 114, 121–123
   wallet.py79495%21, 66, 136, 162
src/algokit/core
   codespace.py1756861%34–37, 41–44, 48–71, 111–112, 125–133, 191, 200–202, 210, 216–217, 229–236, 251–298, 311–313, 338–344, 348, 395
   conf.py57984%12, 24, 28, 36, 38, 73–75, 80
   dispenser.py2022687%92, 124–125, 142–150, 192–193, 199–201, 219–220, 260–261, 319, 333–335, 346–347, 357, 370, 385
   doctor.py65789%67–69, 92–94, 134
   generate.py50394%44, 85, 103
   goal.py65494%21, 36–37, 47
   init.py671085%53, 57–62, 70, 81, 88, 108–109
   log_handlers.py68790%50–51, 63, 112–116, 125
   proc.py45198%99
   sandbox.py2632391%32, 89–92, 97, 101–103, 153, 201–208, 219, 590, 606, 631, 639
   typed_client_generation.py1702088%62–64, 103–108, 132, 135–138, 156, 159–162, 229, 232–235
   utils.py1504073%50–51, 57–69, 125–131, 155, 158, 164–177, 206–208, 237–240, 262
src/algokit/core/_vendor/auth0/authentication
   token_verifier.py15711129%16, 45, 58, 73–85, 98–107, 119–124, 136–137, 140, 170, 178–180, 190–199, 206–213, 227–236, 258, 280–287, 314–323, 333–444
src/algokit/core/compilers
   python.py28582%19–20, 25, 49–50
src/algokit/core/config_commands
   container_engine.py412149%24, 29–31, 47–76
   version_prompt.py921485%37–38, 68, 87–90, 108, 118–125, 148
src/algokit/core/project
   __init__.py53394%50, 86, 145
   bootstrap.py120893%47, 126–127, 149, 176, 207–209
   deploy.py69987%108–111, 120–122, 126, 131
   run.py1321390%83, 88, 97–98, 133–134, 138–139, 143, 147, 277–278, 293
src/algokit/core/tasks
   analyze.py93397%105–112, 187
   ipfs.py63789%58–64, 140, 144, 146, 152
   nfd.py491373%25, 31, 34–41, 70–72, 99–101
   vanity_address.py903462%49–50, 54, 59–75, 92–108, 128–131
   wallet.py71593%37, 129, 155–157
src/algokit/core/tasks/mint
   mint.py74988%123–133
   models.py921782%50, 52, 57, 71–74, 81–90
TOTAL491376884% 

Tests Skipped Failures Errors Time
499 0 💤 0 ❌ 0 🔥 24.433s ⏱️

Please sign in to comment.