pkgsite

Although pkg.go.dev has been opensourced a few years ago, self-hosting a fully featured version of pkgsite for private packages is still a cumbersome process.

This repository provides a Helm chart to:

Deploy the pkgsite frontend.
Deploy, migrate and seed its PostgreSQL database, powered by the bitnami/postgresql Chart.
Optionally deploy a Redis cluster, used by the frontend to cache rendered pages. Powered by the bitnami/redis Chart.
Optionally deploy an athens-proxy instance, in order to provide access to private go modules.

Installing
Getting started
Uninstalling
Exposing the service
Advanced configuration

Installing

helm repo add pkgsite https://cezarguimaraes.github.io/pkgsite
helm install pkgsite pkgsite/pkgsite

Getting started

These steps will walk you through setting up a fully featured pkgsite deployment, including a go module proxy able to retrieve private Go packages hosted on Github.

Create a namespace to contain pkgsite resources.
```
kubectl create namespace pkgsite
```

(Optional) Configure the private go modules proxy

Create a secret to store a GITHUB_TOKEN

kubectl create secret -n pkgsite generic github-token --from-literal=token=$GITHUB_TOKEN

Create a values.yaml file to configure the proxy:

athens-proxy:
  enabled: true

  downloadMode: |
    downloadURL = "https://proxy.golang.org"

    mode = "redirect"

    download "github.com/YOURORGANIZATION/*" {
      mode = "sync"
    }

  configEnvVars:
    - name: ATHENS_GONOSUM_PATTERNS
      value: github.com/YOURORGANIZATION/*
    - name: ATHENS_GITHUB_TOKEN
      valueFrom:
        # this secret is expected to exist. Example:
        # kubectl create secret generic github-token --from-literal=token=$GITHUB_TOKEN
        secretKeyRef:
          name: github-token
          key: token
    - name: ATHENS_DOWNLOAD_MODE
      valueFrom:
        # this configMap is created by setting athens-proxy.downloadMode
        configMapKeyRef:
          name: athens-config
          key: download.hcl

Note the .athens-proxy.downloadMode property. This example configures athens-proxy to serve private packages from github.com/YOURORGANIZATION/*, while redirecting any other package to Go's default module mirror for improved performance and reduced costs.

Install the chart
1. Using the values.yaml file created on the previous step:
```
helm install pkgsite pkgsite/pkgsite -f values.yaml -n pkgsite
```
This can take a few minutes as the seed-db post-hook-install seeds the pkgsite's database.

Verify deployment status

kubectl get pod -n pkgsite
NAME                      READY   STATUS      RESTARTS   AGE
pkgsite-86566fc8b-hfzbs   1/1     Running     0          9m48s
pkgsite-postgresql-0      1/1     Running     0          9m48s
pkgsite-redis-master-0    1/1     Running     0          9m48s
pkgsite-setup-db-snxmb    0/1     Completed   0          9m36s

Browse your docs locally:

kubectl port-forward svc/pkgsite -n pkgsite 8080

Uninstalling

Uninstall the release
```
helm uninstall pkgsite
```

Cleanup Persistent Volume Claims

kukectl delete pvc -l app.kubernetes.io/instance=pkgsite

Exposing the service

This step will vary according to your cluster's networking. Some options are:

Update the serviceType to LoadBalancer
Enable and configure an Ingress resource
Configure an ingress using custom networking solutions such as Istio or Consul. Refer to their documentation for instructions.

⚠️ Take care to not expose private go modules documentation to the public internet.

Advanced configuration

All YAML snippets in this section should be included in your custom values.yaml file.

Seeded packages

You can change the list of packages that are seeded when the chart is installed:

seed:
  packages:
  - std@latest
  - golang.org/x/tools@latest
  - github.com/YOURORGANIZATION/YOURPACKAGE@all

Note you can seed all versions of a package, including std. It can, however, take a long time. Seeding packages is not necessary: users can request that any package be fetched by navigating to pkgsite.domain/<import-path>[@version].

Deployment settings

Find the complete list of deployment settings in the default values.yaml file.

PostgreSQL

Find the complete list of PostgreSQL settings in the chart's ArtifactHub page. Prefix parameters by postgresql:

postgresql:
  image:
    registry: my-private-container-registry.io

Redis

Find the complete list of Redis settings in the chart's ArtifactHub page. Prefix parameters by redis:

redis:
  architecture: replication

athens-proxy

Find the complete list of athens-proxy settings in the chart's Github Repository. Prefix parameters by athens-proxy:

athens-proxy:
  storage:
    type: disk
    disk:
      storageRoot: "/var/lib/athens"
      persistence:
        enabled: true
        accessMode: ReadWriteOnce
        size: 4Gi

cezarguimaraes/pkgsite