From 4ee866bd61d4cea57b1b919221b898e3fdfa089d Mon Sep 17 00:00:00 2001 From: Winni Neessen Date: Sat, 16 Mar 2024 10:27:56 +0100 Subject: [PATCH] Update README with detailed installation instructions The README file has been updated with thorough installation instructions. Changes range from introducing binary and package releases, including their verification using GPG signature, to refactoring the source code installation steps. Additionally, instructions for specific platforms like FreeBSD, Arch Linux, Debian/Redhat/Alpine, etc., have been improved for clarity. --- README.md | 97 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 64 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index b385556..5e193f3 100644 --- a/README.md +++ b/README.md @@ -36,80 +36,111 @@ There is a ready-to-use Docker image hosted on Github. $ docker run ghcr.io/wneessen/apg-go:main ``` -### Ports/Packages +### Binary releases/Packages +On the [Github release page](https://github.com/wneessen/apg-go/releases) you will always find pre-build binaries +for all supported OS and architectures. You will also find pre-built packages for the most common Linux distributions. +Each file is digitally signed via GPG. After downloading the corresponding file, make sure that the file is verified +with the GPG signature. The public GPG key is: +["Winni Neessen" (Software signing key) ](https://keys.openpgp.org/vks/v1/by-fingerprint/10B5700F5ECCB06532CEC873C3D38948DA536E89) + #### FreeBSD apg-go can be found as `/security/apg` in the [FreeBSD ports](https://cgit.freebsd.org/ports/tree/security/apg) tree. #### Arch Linux -Find apg-go in [Arch Linux AUR](https://aur.archlinux.org/packages/apg-go/). \ -Alternatively use the pre-build `zst`-package of the [latest release](https://github.com/wneessen/apg-go/releases) in +Find apg-go in [Arch Linux AUR](https://aur.archlinux.org/packages/apg-go/). Alternatively use the pre-build `zst`-package of the [latest release](https://github.com/wneessen/apg-go/releases) in +this git repository +#### Debian/Redhat/Alpine +Pre-build packages in `.deb`, `.rpm` and `.apk` format can be found on [release page](https://github.com/wneessen/apg-go/releases) in this git repository -### Binary releases -On the [Github release page](https://github.com/wneessen/apg-go/releases) you will always find pre-build binaries -for all supported OS and architectures. You will also find pre-built packages for the most common Linux distributions. -Each file is digitally signed via GPG. After downloading the corresponding file, make sure that the file is verified -with the GPG signature. The public GPG key is: -["Winni Neessen" (Software signing key) ](https://keys.openpgp.org/vks/v1/by-fingerprint/10B5700F5ECCB06532CEC873C3D38948DA536E89) - -#### Linux/BSD/MacOS +#### Binary installation on Linux/BSD/MacOS * Download release ```sh - $ curl -LO https://github.com/wneessen/apg-go/releases/download/v/apg-v--.tar.gz - $ curl -LO https://github.com/wneessen/apg-go/releases/download/v/apg-v--.tar.gz.sha256 + $ curl -LO https://github.com/wneessen/apg-go/releases/download/v/apg-go___.tar.gz + $ curl -LO https://github.com/wneessen/apg-go/releases/download/v/apg-go___.tar.gz.sig ``` -* Verify the checksum +* Import the GPG signing key ```sh - $ sha256 apg-v--.tar.gz - $ cat apg-v--.tar.gz.sha256 + $ gpg --keyserver keys.openpgp.org --recv-keys C3D38948DA536E89 + gpg: key C3D38948DA536E89: public key "Winni Neessen (Software signing key) " imported + gpg: Total number processed: 1 + gpg: imported: 1 ``` - **Make sure the checksum of the downloaded file and the checksum in the .sha256 match** +* Verify the signature + ```sh + $ gpg --verify apg-go___.tar.gz.sig apg-go___.tar.gz + gpg: Signature made Thu Mar 14 11:27:43 2024 CET + gpg: using EDDSA key 10B5700F5ECCB06532CEC873C3D38948DA536E89 + gpg: issuer "wn@neessen.dev" + gpg: Good signature from "Winni Neessen (Software signing key) " [unknown] + Primary key fingerprint: 10B5 700F 5ECC B065 32CE C873 C3D3 8948 DA53 6E89 + ``` + **Make sure the signature of the downloaded file verifies as "good"** * Extract archive ```sh - $ tar xzf apg-v--.tar.gz + $ tar xzf apg-__.tar.gz ``` * Execute ```sh - $ ./apg + $ ./apg -v + apg-go // A "Automated Password Generator"-clone v1.0.0 + OS: // Arch: + (C) 2021-2024 by Winni Neessen ``` #### Windows * Download release ```PowerShell - PS> Invoke-RestMethod -Uri https://github.com/wneessen/apg-go/releases/download/v/apg-v-windows-.zip -OutFile apg-v-windows-.zip - PS> Invoke-RestMethod -Uri https://github.com/wneessen/apg-go/releases/download/v/apg-v-windows-.zip.sha256 -OutFile apg-v-windows-.zip.sha256 + PS> Invoke-RestMethod -Uri https://github.com/wneessen/apg-go/releases/download/v/apg-go__windows_.zip -OutFile apg--windows-.zip + PS> Invoke-RestMethod -Uri https://github.com/wneessen/apg-go/releases/download/v/apg-go__windows_.zip.sig -OutFile apg--windows-.zip.sig ``` -* Verify the checksum +* Import the GPG signing key ```PowerShell - PS> Get-FileHash apg-v-windows-.zip | Format-List - PS> type apg-v-windows-.zip.sha256 + PS> gpg --keyserver keys.openpgp.org --recv-keys C3D38948DA536E89 + gpg: key C3D38948DA536E89: public key "Winni Neessen (Software signing key) " imported + gpg: Total number processed: 1 + gpg: imported: 1 ``` - **Make sure the checksum of the downloaded file and the checksum in the .sha256 match** +* Verify the signature + ```PowerShell + PS> gpg --verify apg-go___.tar.gz.sig apg-go___.tar.gz + gpg: Signature made Thu Mar 14 11:27:43 2024 CET + gpg: using EDDSA key 10B5700F5ECCB06532CEC873C3D38948DA536E89 + gpg: issuer "wn@neessen.dev" + gpg: Good signature from "Winni Neessen (Software signing key) " [unknown] + Primary key fingerprint: 10B5 700F 5ECC B065 32CE C873 C3D3 8948 DA53 6E89 + ``` + **Make sure the signature of the downloaded file verifies as "good"** * Extract archive ```PowerShell - PS> Expand-Archive -LiteralPath apg-v-windows- + PS> Expand-Archive -LiteralPath apg--windows-.zip ``` * Execute ```PowerShell - PS> cd apg-v-windows- PS> apg.exe ``` ### Sources * Download sources - ```sh + ```shell $ curl -LO https://github.com/wneessen/apg-go/archive/refs/tags/v.tar.gz ``` * Extract source - ```sh + ```shell $ tar xzf v.tar.gz ``` -* Build binary - ```sh +* Download dependencies + ```shell $ cd apg-go- - $ go build -o apg ./... + $ go mod tidy + $ go mod download + $ go mod verify + ``` +* Build binary + ```shell + $ go build -o apg github.com/wneessen/apg-go/cmd/apg ``` * Execute the brand new binary - ```sh + ```shell $ ./apg ```