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.
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:
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.
-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
.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
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:
- Domain root example:
- Domain sub-path example:
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'
-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-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.
-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.
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 accepts three possible values:
- An absolute URL to redirect the visitor to;
- A directory path to serve static files from;
disableto return a File Not Found (404) response.
To redirect the visitor to another web site, pass an absolute URL to the
./packageorigin -guide https://example.com/installing-our-packages
To serve the contents of a directory from the base URL, pass a directory path to the
./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.
To return a File Not Found (404) response, pass
disable to the
./packageorigin -guide disable
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
-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:
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
./packageorigin -enable-services container
To run two services, a container and spk service, pass both to the
./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.
Package Origin can automatically manage common Container repository tags. The specified tags will automatically be added to repositories where the tag is missing.
To add the latest and prerelease tags to containers, pass a comma separated list of the tags to the
./packageorigin -include-repository-tags latest,prerelease
The order of the tags is not important.
The available automatic tags are:
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
./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.