Mirrors/velopack
1
0
Fork 0
mirror of https://github.com/velopack/velopack.git synced 2025-10-25 15:19:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add some deployment docs

Browse Source
This commit is contained in:
Caelan Sayler
2024-02-14 15:33:08 +00:00
parent ca933dcfe7
commit 013f8130c1
4 changed files with 126 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
docfx/docs/distributing/deploy-cli.md Normal file
View File

@@ -0,0 +1,41 @@
*Applies to: Windows, MacOS, Linux*
# Deployment CLI
The general process for deploying a Velopack release (`download -> pack -> upload`) can be greatly simplified by using the `download` and `upload` commands which are built into the `vpk` command line tool.
## Packing your new release with delta's
In order for delta's to be generated during the `pack` command, you need to first download the current latest release. This should be done with the download command:
```cmd
vpk download http --url https://the.place/you-host/updates
vpk pack -u YourAppId -v 1.0.1 -p {buildOutput}
```
There are providers for various sources, such GitHub, S3, HTTP, etc.
## Deploying releases
In the previous example, we used the `http` source, while that is very generic it does not provide any information about how to upload the releases, so in the following deployment example we will use [AWS S3](https://aws.amazon.com/s3/).
> [!TIP]
> Most cloud storage providers today have an S3-compatible API ([GCP](https://cloud.google.com/storage/docs/interoperability), [BackBlaze B2](https://www.backblaze.com/docs/cloud-storage-s3-compatible-api), [DigitalOcean](https://docs.digitalocean.com/products/spaces/how-to/use-aws-sdks/), [Linode](https://www.linode.com/docs/products/storage/object-storage/), [IBM Cloud](https://cloud.ibm.com/docs/cloud-object-storage?topic=cloud-object-storage-compatibility-api), and so forth) and can be used with this command - it is not limited to AWS.
Using AWS, you can [authenticate using the `aws` command line tool](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/creds-idc.html) or you can provide access keys as below.
If you are using AWS SSO, you should check the [AWS CLI SSO](https://aws.amazon.com/blogs/security/aws-single-sign-on-now-enables-command-line-interface-access-for-aws-accounts-using-corporate-credentials/) doc and [AWS session authentication](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html).
```cmd
vpk download s3 --bucket MyApp --region us-west-1 --keyId {accessKeyId} --secret {accessKeySecret}
vpk pack -u YourAppId -v 1.0.1 -p {buildOutput}
vpk upload s3 --bucket MyApp --region us-west-1 --keyId {accessKeyId} --secret {accessKeySecret}
```
Note that you can specify most of these argumentsas environment variables too. You can review the [AWS SDK environment variables here](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) and every `vpk` option can be provided as an environment variable too, to list these in the help text use `vpk -H` instead of `vpk -h`.
When using a non-AWS S3-compatible API (eg. BackBlaze B2), you need to specify an endpoint instead of a region:
```cmd
vpk download s3 --bucket MyApp --endpoint https://s3.eu-central-003.backblazeb2.com --keyId {accessKeyId} --secret {accessKeySecret}
vpk pack -u YourAppId -v 1.0.1 -p {buildOutput}
vpk upload s3 --bucket MyApp --endpoint https://s3.eu-central-003.backblazeb2.com --keyId {accessKeyId} --secret {accessKeySecret}
```

82
docfx/docs/distributing/overview.md
View File

@@ -1,5 +1,85 @@
*Applies to: Windows, MacOS, Linux* *Applies to: Windows, MacOS, Linux*
# Distributing Overview # Distributing Overview
Distributing with Velopack is extremely easy, it's usually just as simple as uploading your files somewhere that can be downloaded with HTTP. This means you could host them on an IIS or nodejs site, on shared file hosting such as AWS S3, Azure Storage, BackBlaze B2, or even for free on GitHub/GitLab releases if your project is open source.
WIP The general steps for creating and deploying a Velopack release are:
1. Download the latest published release (eg. 1.0.0).
0. Run `vpk pack` to create your new release (eg. 1.0.1).
0. Upload your newly created 1.0.1 assets.
0. Update the remote releases.{channel}.json to reflect the newly uploaded assets.
See also: [Deployment commands](deploy-cli.md) can make this process much easier.
## List of assets produced
After packing a release with Velopack, you should have something like the following in your output directory:
```
Releases
├── YourAppId-1.0.1-full.nupkg
├── YourAppId-1.0.1-delta.nupkg
├── YourAppId-Setup.exe
├── YourAppId-Portable.zip
├── releases.{channel}.json
├── assets.{channel}.json
└── RELEASES
```
### Full and delta nupkg's
These are the update packages that installed applications use to find/install the latest version. Full packages contain an entire replication of your input files, plus some files Velopack adds. A delta package is a diff from the previously created full package. You need to have the previous version (eg. 1.0.0 in the above example) downloaded and in the output directory for a delta to be created (in this case, `1.0.0->1.0.0`). There are helpful [deployment commands](deploy-cli.md) which can download the latest version for you, so that deltas will be generated automatically.
You must distribute these packages in the same folder as the `releases.{channel}.json` file for updates to work.
### Setup and portable
This is what your user should download and run to install your app. On MacOS, you'll get a `.pkg` instead of a `-Setup.exe`. On Linux, there is no setup produced - only a portable `.AppImage`. The reason for this is that `.AppImage`'s are completely portable to any relatively recent distro of linux.
### Release feed (`releases.{channel}.json`)
This file should be distributed in the same folder as the `nupkg` files are deployed. It contains a list of all available releases.
When you provide a HTTP url to `UpdateManager`, it will search for this file. For example, if you `new UpdateManager("https://the.place/you-host/updates")`, then UpdateManager will request for `https://the.place/you-host/updates/releases.{channel}.json`. The channel UpdateManager uses in the request is automatic, you can [read more here about channels](../packaging/channels.md).
For example, if you packed `1.0.0` and then `1.0.1` immediately after, the contents of this file might look like:
```json
{
"Assets": [
{
"PackageId": "YourAppId",
"Version": "1.0.1",
"Type": "Full",
"FileName": "YourAppId-1.0.1-full.nupkg",
"SHA1": "537EC0F4E1C4263A230353FAB4150216E5AF3724",
"Size": 1588612
},
{
"PackageId": "YourAppId",
"Version": "1.0.1",
"Type": "Delta",
"FileName": "YourAppId-1.0.1-delta.nupkg",
"SHA1": "9615D266DDBCADF3B9CD82BABF9DA571A0EE2B83",
"Size": 3606
},
{
"PackageId": "YourAppId",
"Version": "1.0.0",
"Type": "Full",
"FileName": "YourAppId-1.0.0-full.nupkg",
"SHA1": "69122BABCEEEF9F653BFE59D87DDAEF363F9476F",
"Size": 1588613
}
]
}
```
The releases file should always mirror what files are _actually available_ in the remote folder that contains the releases file. So if you delete a nupkg release from the remote server, you should delete it from your remote release file too. If you are deploying newly created local files to a remote server which already contains some releases, then you should copy the assets from your local file to the remote releases file.
> [!WARNING]
> This file is the only way that UpdateManager can discover releases, if you do not update it properly it may result in your users not getting updates.
It is tedious to update this file manually, so Velopack CLI provides deployment commands which can deploy assets and update this file automatically for you, as well as apply rentention policies around the number of releases to keep. [[Read more]](deploy-cli.md)
### Legacy release feed (`RELEASES`)
This releases format was used by Clowd.Squirrel and Squirrel.Windows, and is still produced by Velopack to allow you to migrate an application using one of those frameworks to Velopack. If you do not have any legacy users which need to migrate to Velopack, you can safely ignore this file.
### Assets file
This file contains a list of assets produced by the latest `pack` command. It is used by the [Velopack deployment commands](deploy-cli.md) to know which files should be uploaded. It can be ignored / deleted if you do not intend to use these commands to deploy releases and automatically update your release feed.

2
docfx/docs/distributing/toc.yml
View File

@@ -1,4 +1,6 @@
- name: Overview - name: Overview
href: overview.md href: overview.md
- name: Deployment CLI
href: deploy-cli.md
- name: CI - Github Actions - name: CI - Github Actions
href: github-actions.md href: github-actions.md

5
docfx/docs/index.md
View File

@@ -18,7 +18,6 @@ To enable your application to make full use of Velopack, you need to do 3 things
Yes, this is fully supported. Before installing updates, Velopack will prompt the user to install any missing updates. Yes, this is fully supported. Before installing updates, Velopack will prompt the user to install any missing updates.
- **How do I install the `vpk` tool? / I've installed the tool but it doesn't work** - **How do I install the `vpk` tool? / I've installed the tool but it doesn't work**
For now, you need to install `dotnet` runtime 6.0 or 8.0 for your platform, and then run `dotnet tool update -g vpk`. For now, you need to install `dotnet` runtime 6.0 or 8.0 for your platform, and then run `dotnet tool update -g vpk`.
If you get a message that it was installed successfully, but running it in your terminal results in a "binary/command not found" message, If you get a message that it was installed successfully, but running it in your terminal results in a "binary/command not found" message, it's probably because your PATH is not set-up properly. For windows, `%USERPROFILE%\.dotnet\tools` should be on the PATH. For macos, [see this issue](https://github.com/dotnet/sdk/issues/9415). In general, dotnet should set these paths up for you, but that is what you should check if things are not working.
it's probably because your PATH is not set-up properly. For windows, `%USERPROFILE%\.dotnet\tools` should be on the PATH. For macos, [see this issue](https://github.com/dotnet/sdk/issues/9415).
- **Can I use a 4 part version (1.0.0.0) instead of SemVer2?** - **Can I use a 4 part version (1.0.0.0) instead of SemVer2?**
Velopack only supports a 3 part version with tags and metadata following (1.0.0-build.23+metadata), following the SemVer2 standard. Some people choose to version with the date, 2024.01.12 for example. It's also possible to get automated git commit based versioning [using something like nbgv](https://github.com/dotnet/Nerdbank.GitVersioning). The reason Velopack supports SemVer2 and not traditional 4 part versions is that it's possible to provide a lot more information in SemVer2 versions, and it is not feasible for us to support both formats throughout the framework. Velopack only supports a 3 part version with tags and metadata (1.0.0-build.23+metadata) following the SemVer2 standard. Some people choose to version with the date, 2024.01.12 for example. It's also possible to get automated git commit based versioning [using something like nbgv](https://github.com/dotnet/Nerdbank.GitVersioning). The reason Velopack supports SemVer2 and not traditional 4 part versions is that it's possible to provide a lot more information in SemVer2 versions, and it is not feasible for us to support both formats throughout the framework.