A golink is a short, memorable keyword/URL that redirects to a longer destination. Think a URL shortener but without the random short code (e.g. 2bjs09). In goku, each golink pairs an alias such as gh with a destination such as https://github.com. Once your network resolves the go hostname to goku (see Set up golinks on a LAN), opening http://go/gh takes you to that destination.
Golinks are increasingly commonplace in corporate environments (so much so one might develop muscle memory 😅) and goku brings that same experience to the homelab.
-
Run goku:
just run
or:
go run ./cmd/goku
-
Open the apps:
-
To require an admin login, set a password:
GOKU_ADMIN_PASSWORD=my-secret just runWithout GOKU_ADMIN_PASSWORD, the admin UI is open and does not show a logout button.
- Resolves exact aliases and placeholder patterns, including
{}and named placeholders. - Runs public redirects on
:9000and the admin UI and API on:9001. - Reports health as JSON on both ports and streams updates from
/ws/healthon the public port. - Lets you search, sort, add, edit, delete, enable, disable, and preview golinks from the admin UI.
- Accepts session, basic, and bearer authentication for admin and API requests.
- Reloads config changes from disk and writes admin and API changes back to
config/config.yaml. - Exposes Prometheus metrics at
/metricson the admin port.
- A golink is a saved redirect.
- An alias is the short path or pattern you type, such as
ghorr/{subreddit}. - A destination is the target URL or URL template.
Edit config/config.yaml:
aliases:
- alias: 'gh'
destination: 'https://github.com'
- alias: 'gh/{owner}/{repo}'
destination: 'https://github.com/{owner}/{repo}'
- alias: 'r/{subreddit}'
destination: 'https://www.reddit.com/r/{subreddit}'
- alias: 'yt/{}'
destination: 'https://www.youtube.com/results?search_query={}'
- alias: 't/{:=BarackObama}'
destination: 'https://twitter.com/@{}'- Single placeholder aliases can use
{}. - Multiple placeholders must be uniquely named.
- Destination placeholders must be defined by the alias pattern.
- Add a default with
{name:=value}or{:=value}. For thetalias above,http://go/tusesBarackObama, whilehttp://go/t/jovalleusesjovalleinstead.
Links such as http://go/gh work when DNS or a local hosts file resolves go to the goku server. A local domain such as go.home.arpa works too. Without local name resolution, use the server URL, for example http://localhost:9000/gh.
| Method | Path | Description |
|---|---|---|
GET |
/ |
Public status page |
GET |
/{path...} |
Golink redirect |
GET |
/preview |
Golink redirect preview |
GET |
/healthz |
Health JSON |
GET |
/ws/health |
Health WebSocket stream |
| Method | Path | Description |
|---|---|---|
GET |
/ |
Admin panel |
GET |
/login |
Login page (when password auth is enabled) |
POST |
/login |
Create admin session |
POST |
/logout |
Clear admin session |
GET |
/metrics |
Prometheus metrics |
GET |
/api/aliases |
List aliases |
POST |
/api/aliases |
Create/update alias |
POST |
/api/aliases/edit |
Edit alias |
POST |
/api/aliases/toggle |
Enable/disable alias |
POST |
/api/aliases/delete |
Delete alias |
POST |
/api/import |
Batch import aliases |
| Variable | Default | Description |
|---|---|---|
GOKU_API_PORT |
9000 |
Public endpoint port |
GOKU_ADMIN_PORT |
9001 |
Admin endpoint port |
GOKU_WEB_PORT |
9001 |
Admin port fallback when GOKU_ADMIN_PORT is unset |
GOKU_CONFIG |
config/config.yaml |
Config file path |
GOKU_PUBLIC_BASE_URL |
(empty) | Absolute public base URL used for admin preview links |
GOKU_ADMIN_USERNAME |
admin |
Username for basic auth |
GOKU_ADMIN_PASSWORD |
(empty) | Enables login page + session auth for admin UI |
GOKU_API_KEY |
(generated/file) | Admin API bearer token |
If you want links like http://go/gh on your LAN, set up local name resolution and route that hostname to goku.
-
Pick a local hostname.
- Recommended:
go.home.arpaor a domain you own. - You can use single-label
goif your LAN resolver supports it.
- Recommended:
-
Configure DNS, or use a hosts file as a fallback.
-
DNS: create an
A/AAAArecord for your chosen host pointing to the machine running goku or your reverse proxy. -
Hosts fallback (per client machine):
# /etc/hosts (macOS/Linux) 192.168.1.50 go go.home.arpa
-
-
Route traffic to goku's public port,
:9000.- If you run goku directly on the host, send HTTP traffic for
goto:9000. - If you use a reverse proxy, point that hostname to
http://127.0.0.1:9000. - If you use Traefik with Docker/service autodiscovery, make the golink redirect router target the public port (
9000). The admin/API port (9001) shows the directory and CRUD API, but it intentionally returns 404 for alias paths.
Minimal examples:
go.home.arpa { reverse_proxy 127.0.0.1:9000 }
server { listen 80; server_name go.home.arpa; location / { proxy_pass http://127.0.0.1:9000; } }
# Traefik labels (example) traefik.http.routers.goku.rule=Host(`go.home.arpa`) traefik.http.services.goku.loadbalancer.server.port=9000
- If you run goku directly on the host, send HTTP traffic for
-
Check the redirect.
- Open
http://go.home.arpa/gh(orhttp://go/ghif using single-label hostnames). - Run
curl -I http://go.home.arpa/ghand confirm a redirect response.
- Open
Set GOKU_ADMIN_PASSWORD to require a login for the admin UI. The API accepts the resulting session, basic authentication, or a bearer key.
Without GOKU_ADMIN_PASSWORD, the admin UI is open. You can still protect API endpoints with a bearer key.
The API key is generated on first run and stored at config/.api_key if not supplied via GOKU_API_KEY.
The generated file uses 0600 permissions. Startup logs report where the key came from, but never print its value.
Import and import-preview requests are limited to 1 MiB. Alias status checks send HEAD or ranged GET requests from the goku host to configured destinations, including private and loopback addresses. Treat access to the admin API as permission to make these probes, and do not expose the admin port to untrusted users.
just fmt
just test
just buildGoku arguably started as an itch I first scratched during an internship at Cisco, where I built an auto-correcting URL shortener and redirection tool for the intranet there. The first of its kind at the time, it was a massive hit among my peers. So much so that the idea stuck with me.
There have since been multiple solutions and iterations in my homelab including janky DNS scripts (rite of passage), some Traefik magic and a one-off Caddy config, but none satisfied the itch especially when faced with expanding scenarios like multi-level queries (e.g. t/TWS-4291/comments), so I embarked on rewriting the concept from scratch and in Go.
The name goku (悟空) is eternally recognizable for anyone familiar with DBZ and also means enlightenment through emptiness. Match made in heaven for this project.
Made with ❤️ and 🇩🇴☕ in NYC