Skip to content

README.md

Latest commit

 

History

History
227 lines (162 loc) · 4.46 KB

README.md

File metadata and controls

227 lines (162 loc) · 4.46 KB

Examples

Integration examples and configuration templates for hadlink.

For deployment instructions, see DEPLOYMENT.md.

Contents

CI Integration

Bash Script for CI/CD Pipelines

See ci-integration.sh for a complete example of integrating hadlink into CI/CD pipelines.

Usage:

# In your CI pipeline
export HADLINK_API="https://hadlink.home/api/create"
export HADLINK_KEY="ci"
export BUILD_URL="http://jenkins.local/job/foo/123/console"

./ci-integration.sh

The script creates a short link and uses it in notifications.

GitHub Actions Example

name: Build
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build
        run: make build

      - name: Create short link
        env:
          HADLINK_API: ${{ secrets.HADLINK_API }}
          HADLINK_KEY: ${{ secrets.HADLINK_KEY }}
        run: |
          BUILD_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          SHORT=$(curl -s "$HADLINK_API" \
            -H "X-API-Key: $HADLINK_KEY" \
            -d "url=$BUILD_URL" | jq -r '.short')
          echo "Build results: $SHORT"

GitLab CI Example

build:
  script:
    - make build
  after_script:
    - |
      SHORT=$(curl -s "$HADLINK_API" \
        -H "X-API-Key: $HADLINK_KEY" \
        -d "url=$CI_PIPELINE_URL" | jq -r '.short')
      echo "Pipeline: $SHORT"

Configuration

Example Configuration File

See config.example.env for all available environment variables.

Minimal Configuration

# Required — generate with: openssl rand -hex 16
export HADLINK_SECRET=<your-secret>

# Optional
export HADLINK_PORT=8443
export HADLINK_STORAGE=/var/lib/hadlink/hadlink.db
export HADLINK_BASE_URL=https://s.example.com

Behind a Reverse Proxy

When running behind nginx, Caddy, or another reverse proxy, enable X-Forwarded-For trust:

# Environment variable
export HADLINK_TRUST_PROXY=true

Important: Only enable this when:

  • hadlink is behind a trusted reverse proxy (nginx, Caddy, etc.)
  • The proxy correctly sets the X-Forwarded-For header
  • Direct access to hadlink is blocked (only proxy can reach it)

When disabled (default), rate limiting uses the direct socket address, which would be the proxy's IP if behind a reverse proxy.

Monitoring Integration

Grafana Alert Example

# Grafana alert annotation
message: |
  Disk usage critical on {{ $labels.instance }}
  Details: {{ $labels.short_url }}

Where short_url is pre-generated for each dashboard panel.

Uptime Kuma Integration

Use hadlink to create stable links for incident response:

# In alert webhook
INCIDENT_URL="https://status.example.com/incident/123"
SHORT=$(curl -s "$HADLINK_API" \
  -H "X-API-Key: monitoring" \
  -d "url=$INCIDENT_URL" | jq -r '.short')

# Include $SHORT in SMS/email notifications

QR Code Generation

Create QR codes for physical infrastructure:

#!/bin/bash
# Generate QR code for router admin page

ADMIN_URL="http://192.168.1.1"
SHORT=$(curl -s "$HADLINK_API" \
  -H "X-API-Key: infra" \
  -d "url=$ADMIN_URL" | jq -r '.short')

# Generate QR code
qrencode -o router-admin.png "$SHORT"

# Print and affix to device

Testing the API

See the API Specification for complete endpoint documentation.

Create a short link

curl -X POST http://localhost:8443/api/create \
  -H "X-API-Key: test" \
  -d "url=https://example.com/very/long/path"

Response:

{
  "short": "http://localhost:8080/8F3kP2Q"
}

Resolve a short link

curl -I http://localhost:8080/8F3kP2Q

Response:

HTTP/1.1 302 Found
Location: https://example.com/very/long/path

Advanced Usage

Namespace Separation

Use different API keys for different services:

api_keys:
  - name: ci
    key: "ci-secret-key"
  - name: monitoring
    key: "monitoring-secret-key"
  - name: infra
    key: "infra-secret-key"

Then track usage by key in logs.

Rate Limit Tuning

For high-volume automated systems:

rate_limit:
  per_ip: 100
  window: 60
  per_subnet: 500

Or disable for authenticated keys in code.