Pkgbot Package Forwarding Service for Golang

Table of Contents

• Introduction
• How to Set Up Pkgbot
• Getting and Installing a Pkgbot License
• Submit Your Host
• Frequently Asked Questions

Pkgbot helps authors of Golang packages by saving them from vendor lock-in while allowing them to use their brand's domain name in package names.

package main

import (
    "flag"
    "fmt"
    "math"

    "github.com/edw/tmpllib"
    "poseur.com/tmpllib"
)

Pkgbot works with domain names under your administrative control for either FQDNs where 1) a CNAME or A record exists and is being used to serve content via HTTPS and 2) no CNAME or A record currently exists. Please review the instructions for installation before purchasing a license; we want to make sure you have a positive experience with Pkgbot.

There are two basic usage scenarios for Pkgbot. The first is when you want to prefix your Golang modules with a domain name that is not currently in use. The second scenario is when you are using the domain name.

Regardless of which case you find yourself in, please read this section in full.

Case 1. An unused domain name

In this case, you’re Example, LLC and decide to start publishing your Golang API module as code.example.com/api/v1/. You are not currently doing anything with the code.example.com domain name.

Step 1. Add a CNAME DNS record pointing code.example.com to code.pkgbot.dev.

Step 2. Add at least one TXT DNS record describing a mapping of module names to repositories. For example:

"pkgbot.dev(10)=/ git https://github.com/examplellc/"

This record tells Pkgbot that all of your modules are Git repositories as part of your company’s GitHub account. When a programmer performs a go get -u code.example.com/api/v1/cmd/tool, they will be redirected to the https://github.com/examplellc/api repository.

This may not be what you want.

It may be the case that this module lives in the https://github.com/examplellc/api repository, because you haven’t yet released version two. If that’s the case, you may want to use the following TXT records:

"pkgbot.dev(2)=/ git https://github.com/examplellc/"
"pkgbot.dev(1)=/api/v1 git https://github.com/examplellc/api"

And then, when you release version two, you can change your configuration to something like this:

"pkgbot.dev(2)=/ git https://github.com/examplellc/"
"pkgbot.dev(1)=/api/v1 git https://github.com/examplellc/api"
"pkgbot.dev(1)=/api/v2 git https://github.com/examplellc/api-v2"

The number in parentheses is, you may have guessed, a priority. Pkgbot scans your rules from lowest priority to highest.

Now let’s say your team falls in love with Sourcehut and wants to migrate the company’s repositories from GitHub. No problem! Let’s further say that they decide that, since they’re moving the “official” home of their repositories, they want to to fix the naming of their version one API. Again, no problem! Just update your DNS configuration:

"pkgbot.dev(0)=/ git https://git.sr.ht.com/~examplellc/"
"pkgbot.dev(0)=/api/v1 git https://git.sr.ht/~examplellc/api-v1"
"pkgbot.dev(-1)=/api/v2 git https://git.sr.ht/~examplellc/api-v2"

These priorities have been chosen so that the new rules preempt the old rules, as Pkgbot may continue to see the old rules due to DNS caching.

Case 2. An in-use domain name

Let’s say code.example.com is already being used. Specifically, there’s already an A, AAAA, or CNAME DNS record already associated with it. You should set up TXT records exactly as described above, but instead of setting up a CNAME record, you need to proxy requests from your server to code.pkgbot.dev.

Below is an example NGINX configuation that redirects only requests for package metadata:

server {
  server_name code.example.com;

  listen 443 ssl default_server;
  listen [::]:443 ssl default_server;

  if ( $arg_go-get = 1 ) {
    rewrite ^ "/go-module-proxy$uri?$args" break;
  }

  location /go-module-proxy/ {
    rewrite ^/go-module-proxy(/.*)$ $1 break;
    proxy_set_header Host $host;
    proxy_pass https://code.pkgbot.dev/;
  }

}

A license takes the form of a TXT DNS record that is locked to a domain name. Here is the license record for poseur.com:

"pkgbot.dev:license=FOREVER STANDARD c678c3...4f2de4"

In this case, the license never expires, thus the FOREVER. Licenses are available for terms of one year, five years, and, as this one is, the rest of eternity.

This record should be installed alongside the TXT records described in the set up documentation.

Eventually, we're going to set up an online store to automate the licensing process, but for now, if you'd like to purchase a license, please send a message to licenses@pkgbot.dev. We can take payment in all the usual ways, and if your CFO needs an invoice or absolutely needs to cut us a check, we can handle that.

We're currently located on the East Coast of the US, and you can expect less than an hour turnaround during normal business hours, ET.

As you can tell, the commerce side of things is a work in progress, but this was an important part of product design process: Once installed, require zero maintenance: The license can be validated by the Pkgbot servers without consulting any back-end systems.

Enter the fully-qualified domain name you want to use for your packages, and we'll generate a Let's Encrypt certificate as soon as you've added a CNAME DNS record pointing to code.pkgbot.dev.

Submission result: None yet.

Once your fully-qualified domain name has been accepted, we'll set up an HTTP server and verify that it points to code.pkgbot.dev. Once we've done so, we'll get a certificate from Let's Encrypt and start up an HTTPS server. At that point, you will be able to verify that Pkgbot is working by visiting the site in your web browser. Once you've set up your TXT DNS records, you'll be able to publicly use your domain name for package names.

Why should I forward requests to Pkgbot when I can just hard code meta tags into my company's corporate web site on the appropriate pages?

Great question! If you the development team is in complete control of your company's corporate web site (example.com)— or developer-focused web site (coderz.example.com) and can ensure that pages exist in all the right places and the proper meta tags are properly placed and preserved through edits and redesigns, then you don't need Pkgbot.

However, if you don't want to worry about such things, try Pkgbot.

Who created and runs Pkgbot?

Pkgbot is a service of Edwin Watkeys. He's been programming since shortly after his parents brought home an Apple ][+ back in the early Eighties. He fell in love with Golang after hunting down one too many segmentation violations in code that reads arrays of floating point numbers. Golang, in Edwin's opinion, is a great balance between assembly language and Scheme.

What inspired him to write Pkgbot?

It's a funny thing: One of the great things about Git vis-à-vis legacy version control systems was that it was distributed, yet here we are in 2020 and everybody feels the need to make GitHub their project's central repository. There's nothing wrong with that per se, but what happens when Google Microsoft buys GitHub and maybe you don't want your code to live there anymore? Or maybe GitLab or sourcehut has caught your attention, but everyone refers to your code based on the incidental fact that you use GitHub to manage your projects? You don't bake the text editor you use into your naming process; why do the same with your developer collaboration platform?

Again, GitHub isn't the enemy. The enemy is lock-in. You and your organization should be able to make choices about where you do your development independent of what you name your packages.

It's not inconceivable that a CEO or board member might look at you API efforts and say, "Ugh, what's this 'sr.ht' in this sample code? What are you weird? Bad optics, ditch sourcehut." And this person, while you want to kill them, they're not necessarily wrong. The better solution is to decouple your development tools from the product naming.

Where does Pkgbot development take place?

On sourcehut.

What technologies is Pkgbot based on?

The core of Pkgbot is written in Golang, of course. It has no external dependencies. Certs are managed by Certbot, whose name inspired Pkgbot's. In a concession to the times, Pkgbot is deployed in Docker containers that run at Linode on Linux boxes.

What about privacy and stuff like that?

Pkgbot does not keep usage statistics or collect any data on our customers or the people who use our customer's packages. This site doesn't even use any analytics — check out the HTML.

Your licenses aren't cheap.

That's not a question. Anyway, the owner of Pkgbot has spent over a decade in digital marketing and advertising. He's pretty sure he could find a way to pay the rent by collecting and selling analytics around a service like this, not to mention the revenue he could bring in by putting ads everywhere. But that is icky and gross and he'd much rather make money by providing a useful service to people and organizations who feel it's valuable.

If you have to spend an hour a year dealing with this, Pkgbot will pay for itself, especially if you buy a forever license.

We're a non-profit; can you give us a break on pricing?

Probably. Just ask.

I'm just a hobbyist; how about giving me a break on pricing?

Maybe. It doesn't hurt to ask.