phil-harmoniq / netpkg-tool

Bundle .NET Core applications into convenient Linux binaries.

netpkg-tool

Download

Released Binary

Pre-packaged versions of netpkg-tool are available from the releases tab:

# Github releases are tagged with their version (ex: 0.3.10)
wget https://github.com/phil-harmoniq/netpkg-tool/releases/download/0.3.10/netpkg-tool
chmod a+x ./netpkg-tool

# Place netpkg-tool somewhere on your $PATH (Optional)
mv ./netpkg-tool ~/.local/bin

Docker Image

netpkg-tool is also available as a Docker image if you don't want to install any dependencies:

# Pull the latest netpkg-tool Docker image
docker pull philharmoniq/netpkg-tool

For more information, see the Docker README.

Build From Source

To build netpkg-tool from source, run build.sh and specify a destination folder:

git clone https://github.com/phil-harmoniq/netpkg-tool
./netpkg-tool/build.sh ~/Desktop

Examples

Packaging a simple "Hello World" app:

git clone https://github.com/phil-harmoniq/Hello
netpkg-tool Hello ~/Desktop
~/Desktop/Hello one two three

Packaging a default ASP.NET Core MVC template:

dotnet new mvc -n aspnet-src
netpkg-tool aspnet-src . -n aspnet-pkg
./aspnet-pkg

Optional Flags

ASP.NET

ASP.NET is picky about where its content root directory is located. By default, it searches for wwwroot in Directory.GetCurrentDirectory(). Using netpkg-tool on an unmodified ASP.NET project will result in your web app being unable to locate any of its assets. A simple workaround would be to check for the existence of an environment variable set by netpkg-tool, like $NET_PKG, and setting the content directory to the Assembly location if it exists. This will allow the project's content to be found regardless of whether it's packaged up or being run with dotnet run. Example:

public class Program
{
    public static void Main(string[] args)
    {
        var assembly = Assembly.GetExecutingAssembly().Location;
        var pkgEnv = Environment.GetEnvironmentVariable("NET_PKG");

        if (string.IsNullOrEmpty(pkgEnv))
            BuildWebHost(args, Directory.GetCurrentDirectory()).Run();
        else
            BuildWebHost(args, Path.GetDirectoryName(assembly)).Run();
    }

    public static IWebHost BuildWebHost(string[] args, string root) =>
        WebHost.CreateDefaultBuilder(args)
            .UseContentRoot(root)
            .UseStartup<Startup>()
            .Build();
}

Details

Using netpkg-tool will restore and compile your project based on settings in your *.csproj file. By default, netpkg-tool will use Framework Dependent Deployment to compile your project. To use Self-Contained Deployment, use the --scd flag. The full process for netpkg-tool:

1. Restore project dependencies
2. Compile .NET Core app
3. Create AppDir and transfer files
4. Run appimagetool on created AppDir
5. Delete temporary files

Dependencies

• .NET Core 2.0 SDK: Per-distro RID tags were replaced with the universal linux-x64 RID, simplifying the Linux build process. Earlier versions should work with netpkg-tool but only using Framework Dependent Deployment.
• appimagetool: (Included) Bundles Linux applications into AppImages, currently utilizes version 9 of appimagetool.
• Shell.NET: (Included) .NET Standard library for interacting with Bash.

Contributing

If you have a feature request or issue, feel free to submit an issue. A pull request would be even better! Pull requests should target the develop branch.

Mono

While this project is mainly aimed at Microsoft's new .NET Core ecosystem, it should be possible to eventually make this tool work with Mono. Mono support is planned but no exact ETA can be given until the core utility is in a more stable state.

Disclaimer

The netpkg-tool project is still in alpha development. Names, commands, and features are subject to change. Please keep this in mind when using this utility.