GoShort

GoShort is a small, minimal URL shortener written in Go. It uses an embedded SQLite database and aims to be easy to run and operate.

Quick links

• Configuration: See example-config.yaml
• Docker image: ghcr.io/jlelse/goshort:latest

Running (Docker - preferred) ✅

The easiest and recommended way to run GoShort is via Docker. The official image is published to GitHub Packages.

Run the published image:

docker run -d \
 --name goshort \
 -p 8080:8080 \
 -v "$(pwd)/config:/app/config" \
 -v "$(pwd)/data:/app/data" \
 ghcr.io/jlelse/goshort:latest

If you prefer to build locally and run that image:

docker build -t goshort .
docker run -d \
 --name goshort \
 -p 8080:8080 \
 -v "$(pwd)/config:/app/config" \
 -v "$(pwd)/data:/app/data" \
 goshort

The service listens on port 8080 inside the container. Mount a config directory (containing config.yaml or config.json/config.toml) and a data directory for the SQLite database.

Building from source (when preferred) 🔧

Building from source is useful if you want to make changes, test locally, or don't want to use Docker.

Install Go (>= 1.26) then:

# build
go build -o goshort
# run tests
go test ./...
# run locally (ensure a config is available in ./config or ./config.yaml)
./goshort

Caddy reverse proxy (Docker Compose example) 🌐

Here's a minimal docker-compose.yml and Caddyfile that run GoShort behind Caddy (TLS + reverse proxy). Save the docker-compose.yml and Caddyfile next to your config and data directories.

docker-compose.yml:

services:goshort:image:ghcr.io/jlelse/goshort:latestrestart:unless-stoppedvolumes:- ./config:/app/config- ./data:/app/dataexpose:- "8080"networks:- webcaddy:image:caddy:2restart:unless-stoppedports:- "80:80"- "443:443"volumes:- ./Caddyfile:/etc/caddy/Caddyfile:ro- caddy_data:/data- caddy_config:/confignetworks:- webvolumes:caddy_data:caddy_config:networks:web:

Caddyfile (replace yourdomain.example with your domain):

yourdomain.example {
 reverse_proxy goshort:8080
}

Start the stack:

docker compose up -d

Caddy will handle TLS for you automatically and forward requests to the goshort service.

Configuration

Configuration can be done with a simple config.{json|yaml|toml} file in the working directory or a subdirectory config.

Required config values:

• password: Password to create, update or delete short links
• shortUrl: The short base URL (without trailing slash!)
• defaultUrl: The default URL to which should be redirected when no slug is specified

Optional config values:

• dbPath: Relative path where the database should be saved

See the example-config.yaml file for an example configuration.

Authentication

The preferred authentication method is Basic Authentication. If you try to create, modify or delete a short link, in the browser a popup will appear asking for username and password — enter just the password you configured. Alternatively you can append a URL query parameter password with your configured password.

Usage

You can either create, update or delete short links using a browser by visiting the endpoints below, or make HTTP POST requests.

• Create a new short link: /s
  • url: URL to shorten
  • (optional) slug: the preferred slug
• Update a short link: /u
  • slug: slug to update
  • new: new long URL
• Delete a short link: /d
  • slug: slug to delete

License

GoShort is licensed under the MIT license. See the LICENSE file for details.