vanity

Vanity

Low-configuration server for Go package vanity URLs.

• Description
  • Vanity URLs?
• Installation
• Configuration
• Alternatives
• Licensing & thanks

Description

vanity supports both GitHub and Gitea/Gogs (at the same time). It allows you to set a default service (of either kind), and only explicitly configure packages that aren't at the corresponding location on that service.

The idea is, you set up a default service, and then you only have to explicitly configure that are hosted on the other service, or have a different repo name (e.g. package mydomain/pants lives at git.mydomain.tld/go-pants).

Out of the box, you only need to set the hostname for the server your vanity URLs live on and your GitHub username. If you're using Gitea/Gogs, you also need to set the hostname of your Gitea/Gogs server. That's it. All requests will be redirected to that service by default.

Vanity URLS?

A "vanity URL" is a custom import path for your Go package, such as go.deanishe.net/aw, that isn't the URL the code is actually hosted at (that package currently lives at github.com/deanishe/awgo). Typically, the vanity URL is on your own domain (hence the "vanity"). There are several advantages to vanity URLs:

• They're cool (assuming your domain name isn't stupid);
• They imply a certain seriousness (again, assuming your domain name isn't stupid) — it's not just some random, free GitHub account; and most importantly …
• Your packages aren't tied to someone else's service/domain. You can move your package(s) from GitHub to Bitbucket, Gitlab or your own server without breaking anyone's build.

Installation

go get -u go.deanishe.net/vanity

Configuration

vanity is designed to work with minimal configuration, but you will at least have to set the root hostname(+/path) for your vanity URLs (flag -root) and your GitHub username (-github.username). If you're using Gitea by default, you need to tell vanity that via the -gitea flag, and set your Gitea server's hostname (-gitea.hostname) and username (-gitea.username). For example:

vanity -root=go.deanishe.net -github.username=deanishe

Thanks to ff, all configuration options can be specified via command-line flag, configuration file or environment variable, so the above is equivalent to:

ROOT=go.deanishe.net GITHUB_USERNAME=deanishe vanity

Or can be specified in a configuration file (vanity -conf path/to/vanityrc):

# vanityrc
root             go.deanishe.net
github.username  deanishe

# redirect go.deanishe.net/aw to github.com/deanishe/awgo
github.repo aw|awgo

Use vanity -sample.config and vanity -sample.env to dump a sample config file or env file respectively, which contains all options and descriptions thereof.

A selection of related config files for systemd, rsyslog etc. are available in the extras directory.

Alternatives

Check out these other servers that do (more or less) the same thing. One of them might better fit your needs.

• jonnrb/vanity/vanityserver — requires explicit configuration of every package
• bigwhite/govanityurls — requires explicit configuration of every package
• vaingogh — set-and-forget, but GitHub-only
• nginx config by @jessfraz — zero per-package configuration, but only (easily) supports one service
• and more…

Licensing & thanks

This program is released under the MIT licence.

It is based on:

• go-chi/chi for the HTTP stuff
• peterbourgon/ff for the CLI/config goodness
• jonnrb/vanity for the go get and godoc gubbins