Package Origin Overview

A guide for installing and configuring Package Origin.

Package Origin is a low resource, high throughput, software package service. Built to be trival to set up and keep running, Package Origin offers defaults that will suit most situations, with options to ensure complex environments are catered to.

Getting Started

To get started with Package Origin download the server for your combination of hardware and operating system. Expand the compressed file and launch the server:

./packageorigin

By launching the packageorigin binary, you are now running the default services. Package Origin will output details of the network address it is listening on and any activity.

Package Origin is a self contained single binary. There are no files to install. No configuration is required to get started.

Finding Packages

Use the -package flag to tell Package Origin where to look for packages.

In the command below, the path /pkgs/release will be searched for supported package files:

./packageorigin -package /pkgs/release

Packages are files with the extensions .nupkg, .spk, or .tar. The path passed to Package Origin will be recursively searched for packages. Any packages found will be cataloged and served.

Multiple paths can be joined and passed to the -package flag. This allows packages spread across different locations to be included in a single service:

./packageorigin -package /pkgs/release:/pkgs/beta

The package paths do not need to be public or exposed via a web server. Package Origin will read and serve the package files as needed.

Changing and Updating Packages

Package Origin will regularly search for new, removed, and changes packages in the provided paths. This behaviour is controlled by the -refresh flag. Pass a duration to the flag to control how often Package Origin should search. Passing zero, 0, will disable the searches.

Durations are written in hours and minutes. The following examples are all valid durations:

To tell Package Origin to search for changes once a day, pass twenty-four hours for the duration:

./packageorigin -refresh 24h

To disable automatic searches, pass zero for the duration:

./packageorigin -refresh 0

Immediate Scan

An immediate search for new, removed, and changed packages can be started by sending the packageorigin process a HUP (hang up) signal. On UNIX based computers, this can be sent using the killall command below:

killall -s HUP packageorigin

Network Interface and Port

Package Origin defaults to listening on all network interfaces on TCP/IP port 8080. Use the -listen flag to control which network interface and port to listen on. To listen only for localhost connections and on port 8123, use the command below:

./packageorigin -listen localhost:8123

Package Origin supports IPv4 and IPv6. To listen on port 8123 on the local loopback IPv6 address, pass the address as below:

./packageorigin -listen [::]:8123

Domains and the Base URL

Package Origin can serve from the root or a sub-path of a domain:

The default behaviour is to serve from the root of a domain. Package Origin will derive an absolute URL based on the request. If the request comes in through https://pkg.example.com, then this will be the domain used in the response.

To override this behaviour, or to ensure the base URL used in the response, use the flag -base and pass the absolute URL:

./packageorigin -base 'https://pkg.example.com'

For services originating from a sub-path, include the path in the absolute URL:

./packageorigin -base 'https://example.com/download/packages'

If -base contains a sub-path, Package Origin will only respond to requests that start from the exact sub-path, including any trailing slash. In this configuration, a reverse proxy is assumed to exist, to handle requests outside of the sub-path.

Transport Layer Security (TLS)

Many package managers rightly require encrypted connections using Transport Layer Security (TLS) certificates. This is supported by Package Origin.

Package Origin supports TLS using two flags: -tls-cert and -tls-key. Pass the path to the domain’s certificate chain and the corresponding certificate private key:

./packageorigin -tls-cert /certs/example_com-public.pem -tls-key /certs/example_com-private.pem

Typically a package service’s transport layer protocol is https. Tools such as nuget on Windows will report errors when trying to use a service via http and not https. The error will claim the service does not support requested features, this can be misleading. The error does not mention if the feature exists but is not offered via a secure connection.

When the -base flag is empty, Package Origin respects the HTTP header X-Forwarded-Proto header. You can run Package Origin without TLS and delegate the security layer to a reverse-proxy.

Guiding Visitors

When a visitor browses the base URL managed by Package Origin, a web page is shown. The page provides a simple overview of the package manager services available and how to configure the most popular clients.

You may want to replace this page with your own instructions or potentially redirect the customer to another URL. This is possible with the -guide flag.

The -guide flag accepts three possible values:

Redirect

To redirect the visitor to another web site, pass an absolute URL to the -guide flag:

./packageorigin -guide https://example.com/installing-our-packages

Static Site

To serve the contents of a directory from the base URL, pass a directory path to the -guide flag:

./packageorigin -guide ~/public/my-guide

The directory can contain multiple files and sub-directories, with files named index.html served as directory index pages.

The directory name disabled is reversed and can not be used as the flag’s value.

The behaviour allows a full static web site to be served alongside the package manager protocols supported by Package Origin. It is not unreasonable to use Package Origin as a specialised web server and serve a web site using this approach.

Disable Guide

To return a File Not Found (404) response, pass disable to the -guide flag:

./packageorigin -guide disable

Logging

Package Origin logs activity to standard output by default. This output can be redirected to a file using the -log flag. The following command redirects the log entries to a file:

./packageorigin -log /var/log/packageorigin.log

Package Origin will rotate, compress, and retain log files for a reasonable period. The default behaviour is suitable for most situations.

To avoid log files growing excessively large and filling all available storage space, a maximum size per log file is enforced. The flag -log-size accepts integers representing the maximum uncompressed file size in megabytes (MB).

When a log file reaches the maximum file size, the file is closed and a new log file is begun. The previous log file is renamed and stored alongside the current log file.

To avoid filling the storage space with previous log files, older log files are removed. This process is called rotation and is controlled by the -log-age flag. The -log-age flag’s value is an integer representing the maximum number of days to retain a log file. Log files older than this number of days will be removed during the next log rotation. Passing 0 to -log-age disables the removal of older log files; this is not recommended.

Rotated log files are compressed to save disk space. Compression can be disabled by passing false to the -log-compress flag; this is not recommended:

./packageorigin -log-compress=false

Limiting Services

By default, Package Origin runs all available services.

Services can be selectively enabled with the flag -enable-services. Services not passed with this flag, will not be enabled. Omit the flag to run all services.

To only run a container registry service, pass only container to the -enable-services flag:

./packageorigin -enable-services container

To run two services, a container and spk service, pass both to the -enable-services flag:

./packageorigin -enable-services container,spk

Services are provided as a comma separated list. The order is not important. The available services are:

The order of the services is not important.

Repository Tags

Package Origin can automatically manage common Container repository tags. The tags will be added to repositories where the tag is missing. The available automatic tags are:

To add the latest and prerelease tags to containers, pass a comma separated list of the tags to the -include-repository-tags flag:

./packageorigin -include-repository-tags latest,prerelease

The order of the tags is not important.

Cached Files

Package Origin will cache compressed copies of uncompressed container layers. These files are created when the container archive is read.

The need for a cache can be avoided by pre-compressing container layers.

The cache must not be deleted while Package Origin is running. The cache directory can be deleted when Package Origin is not running. Any required files will be recreated on first reading of a container archive.

To change the location of the cache, pass a directory path to the -cache flag:

./packageorigin -cache /tmp/packageorigin/cache

Stopping the Service

To stop the service, send the packageorigin process a TERM (terminate) signal. On UNIX based computers, this can be sent using the killall command below:

killall -s TERM packageorigin

Package Origin is a read-only service. Suddenly terminating the service does not risk damaging packages or files; only active connections with clients will be disrupted.