Deployment

A practical guide to deploying Package Origin with your own packages.

Preparing Packages

The first step is to gather or prepare software packages to distribute. Package Origin supports a range of packaging formats, including .tar (containers), .spk (Synology Packages), and .nupkg (NuGet) files. If you need help creating these packages, please get in touch. Miln offers consulting and can help.

An Important Decision

Once you have your software packages ready, you need to settle upon the domain and optional path, the Uniform Resource Identifier (URI), of your package service.

This decision is important. Once in use by customers, changing the URI is difficult. The difficultly is because package managers tend to handle redirections poorly.

When a web site or page needs moving, web clients can be relied upon to follow http redirection responses. Unfortunately, package managers are not so robust and do not expect repositories and services to change.

Changing the URI will require all your customers to change their package manager configurations. This is an imposition, and a support burden, you should avoid.

Advice

Given the difficultly of changing the URI once publicised, the URI should be:

Examples of good domains are:

Examples of poor domains are:

Using a dedicated domain or sub-domain is good practice and recommended. This will increase your options for hosting and dealing with increases in future traffic.

Ideally, a path is not needed. If you do need to use a path, these are examples of reasonable paths:

Note the lack of a trailing slash /. Where possible, arrange for Package Origin to serve from the simplest possible path. Focus on keeping the URI simple for customers.

Customers will have to enter the URI into their package manager. Keep this in mind when deciding. Keep the URI simple and short.

Hosting

Where Package Origin runs will depend on your organisation’s existing infrastructure.

Dedicated Server

Package Origin can be run on a dedicated server, exposed to the Internet, and left to handle traffic directly. While possible, this configuration is less common.

The following command will launch Package Origin, serving secure connections via https, and offering packages found in the current directory:

./packageorigin -listen :443 -tls-cert mycert.pem -tls-key mykey.pem

This configuration assumes:

Behind a Proxy

Package Origin is most commonly run behind a reverse web proxy. The proxy is responsible for handling incoming connections and passing them to a range of services.

Caddy Server

Caddy is a popular choice for managing web traffic. The following examples show how to deploy Package Origin behind Caddy.

Caddy with a Domain

Let’s assume Package Origin is running on a server with the internal IP address of 192.168.1.10 with the command:

./packageorigin -listen :8080 -base https://pkg.example.com

The corresponding Caddy configuration will be:

pkg.example.com {
	proxy / 192.168.1.10:8080 {
		transparent
	}
}
Caddy with a Domain and Path

Let’s now assume Package Origin needs to serve packages from https://example.com/pkgs. As before, we will assume Package Origin is running on a server with the internal IP address of 192.168.1.10 with the command:

./packageorigin -listen :8080 -base https://example.com/pkgs

The corresponding Caddy configuration now includes the path and will be:

example.com {
	proxy /pkgs 192.168.1.10:8080 {
		transparent
	}
}

Note the -base value passed to Package Origin lacks a trailing slash. This is matched in the Caddy proxy configuration. This ensures requests to https://example.com/pkgs and https://example.com/pkgs/ are handled appropriately by Package Origin.