F2.Deployment.Builder 0.0.12-testing

F2 Deployment Builder tool

The F2 Deployment Builder tool, f2deploy, is a dotnet tool for building and deploying applications, principally to Raspberry Pi. Run this tool on your dev machine, in the directory where your source code is, to build a package and optionally upload it to the internet.

Installation

Follow the instructions to install the tool F2.Deployment.Builder. TL;DR:

dotnet tool install -g F2.Deployment.Builder

You can also install this as a local tool if you need to. Note that sometimes IDEs can create bad dotnet-tools.json files which might interfere with running this tool as a local tool.

Check the tool runs by just running it: dotnet f2deploy.

Environment requirements

To upload packages with f2deploy you need to provide a Bitbucket App Password. To create an App Password:

• Note your bitbucket username, visible in your Bitbucket account settings under the "Bitbucket profile settings" section.
• Go to https://bitbucket.org/account/settings/app-passwords/
• Click "Create app password"
• Tick the "Repositories / Write" tickbox; give it a label like "F2 Deployment Tool", and click Create
• give the password to the f2deploy tool using dotnet f2deploy auth set --user {username} --pass {password}

The credentials are saved in plaintext on your local machine.

Project requirements

To use f2deploy, your project must follow some conventions:

• a publish profile must exist in the Properties\PublishProfiles\f2deploy.pubxml
• the publish profile must specify <PublishProvider>FileSystem</PublishProvider>
• the publish profile must specify an output path which includes the string f2deploy
• the publish profile must target a linux runtime, e.g. linux-arm64
• the project must contain an application manifest template file f2.manifest.template.json in the project root directory
• the project must build an executable with a "compliant name". The name can be set using an <AssemblyName> tag inside a <PropertyGroup> in the project (csproj) file.

Naming is discussed in the next section. Sample pubxml and manifest template file content is provided at the end of this document.

In addition to the above requirements, there are some strong recommendataions:

• the pubxml should be checked in to git
  • the default .NET .gitignore ignores pubxml files, because if you use a publish method other than local filesystem, they can contain secrets in plaintext. Your f2deploy.pubxml should not need to contain plaintext secrets.
  • f2deploy will warn you if your f2deploy.pubxml is ignored by git.
• the pubxml should not specify <PublishSingleFile>true</PublishSingleFile>
  • f2deploy contains special undocumented behaviour for single-file publishes
• for ASP.NET server projects, specify the public port to bind when deployed by creating an appsettings.Production.json file

Naming

The project naming conventions are

• All names must be representable in ASCII
• C# Namespaces should follow the framework design guidelines, example F2.Deployment.DeploymentServer
• The project (csproj) file name should match the project's root namespace, example F2.Deployment.DeploymentServer.csproj
• The "application name" is considered to be the final token of the namespace, example DeploymentServer
• The assembly name should be the application name in lowercase, example deploymentserver. (Note that this does not follow the framework design guideline recommendation for assembly names.)

The assembly name convention is chosen such that the executable name will not be mangled by linux tools, e.g. systemd or htop.

Packages and versions

The f2deploy tool ensures that applications and packages are built such that all the version identifiers are consistent:

• the package archive name, {name}-{version}.zip
• the .NET assembly metadata version
• the manifest JSON file

The version is SemVer-compliant; the prerelease part is automatically generated based on the current git branch, and the numeric part is specified when invoking f2deploy.

Building and packaging

A package can be built with the dotnet f2deploy build command.

Parameters:

• --targetVersion, -v (required): specifies the numeric part of the SemVer-compliant version to build.
• --target, -t (optional): specifies the path to the project to build; if omitted, builds the project in the current directory.

The build command builds and publishes the project (i.e. dotnet publish) with the specified version, zips the published application using the naming scheme convention, and saves the zip package in the repo's .\binaries directory.

Deploying

A package can be uploaded to bitbucket with the dotnet f2deploy deploy command.

Parameters:

• --no-build: skips building, and uploads a previously-built package
• --targetVersion, -v (required): specifies the numeric part of the SemVer-compliant version to build.
• --target, -t (optional): specifies the path to the project to build; if omitted, builds the project in the current directory.

The publish command builds the package, per f2deploy build above, unless --no-build was specified, and uploads the package to the Bitbucket downloads for the repo which is set as the git remote.

Authentication details must be set before uploading will work.

Auth

Authentication can be set with dotnet f2deploy auth set

Parameters:

• --user: your bitbucket username
• --pass: a generated app password

Authentication can be checked with dotnet f2deploy auth check.

File templates

Pubxml

If you have access to Visual Studio, the GUI for creating/editing pubxml can be opened by right-clicking the project in the solution explorer and selecting "Publish…".

This pubxml is suitable for an ASP.NET webserver. It may behave unpredictably for other kinds of projects.

Place the following XML in a file at .\Properties\PublishProfiles\f2deploy.pubxml relative to the CSPROJ.

<?xml version="1.0" encoding="utf-8"?>
<Project>
  <PropertyGroup>
    <DeleteExistingFiles>true</DeleteExistingFiles>
    <ExcludeApp_Data>false</ExcludeApp_Data>
    <LaunchSiteAfterPublish>false</LaunchSiteAfterPublish>
    <LastUsedBuildConfiguration>Release</LastUsedBuildConfiguration>
    <LastUsedPlatform>ARM64</LastUsedPlatform>
    <PublishProvider>FileSystem</PublishProvider>
    <PublishDir>bin\Release\net6.0\publish\f2deploy\</PublishDir>
    <PublishUrl>bin\Release\net6.0\publish\f2deploy\</PublishUrl>
    <WebPublishMethod>FileSystem</WebPublishMethod>
    <_TargetId>Folder</_TargetId>
    <SiteUrlToLaunchAfterPublish />
    <TargetFramework>net6.0</TargetFramework>
    <SelfContained>false</SelfContained>
    <RuntimeIdentifier>linux-arm64</RuntimeIdentifier>
  </PropertyGroup>
</Project>

Also it is strongly suggested to "git-unignore" the file by adding the following line to the relevant .gitignore:

!f2deploy.pubxml

Manifest template

Place the following JSON in .\f2.manifest.template.json relative to the CSPROJ.

{
  "ManifestFileVersion": "2.0",
  "Service": {"ServiceDescription": " --THIS TEXT WILL BE THE SYSTEMD SERVICE DESCRIPTION-- ", }
}

If you don't want a systemd service to run your application, set the service property to null:

{
  "ManifestFileVersion": "2.0",
  "Service": null
}

Appsettings

Use the ASP.NET "appsettings" convention to set settings which are "part of the application" (as opposed to "configuration" which cannot be known when authoring the application).

One common example is setting the default host port to bind when in production, by creating a file called appsettings.Production.json

{ "urls": "http://*:5000" }