Skip to content

Deployment

srcref can be used via the public service at www.srcref.com or self-hosted for private repositories and custom configurations.

Public Service

The easiest option — just use www.srcref.com. No setup required. Works with any public GitHub repository.

Environment Variables

All deployment methods support these environment variables:

# Environment variables control runtime behavior:
#
# PORT           - HTTP server port (default: 8080)
# PREFIX         - URL prefix for generated links (default: https://www.srcref.com)
# DEFAULT_BRANCH - Default GitHub branch (default: master)
# MAX_CACHE_SIZE - Maximum cached file entries (default: 2048)
# MAX_LENGTH     - Maximum file size to process (default: 5MB)
Variable Default Description
PORT 8080 HTTP server port
PREFIX https://www.srcref.com URL prefix for generated links
DEFAULT_BRANCH master Default branch when not specified
MAX_CACHE_SIZE 2048 Maximum cached file entries
MAX_LENGTH 5242880 (5MB) Maximum file size to process

Local Development

# Clone and build
git clone https://github.com/pambrose/srcref.git
cd srcref
./gradlew build -xtest

# Run the development server
./gradlew run

# The server starts at http://localhost:8080

Fat JAR

Build a self-contained JAR that includes all dependencies:

# Build the fat JAR
./gradlew buildFatJar

# Run it directly
java -jar build/libs/srcref-all.jar

# Or with custom environment variables
PORT=9090 PREFIX=https://srcref.mycompany.com java -jar build/libs/srcref-all.jar

Docker

Running with Docker

docker run -p 8080:8080 \
  -e PORT=8080 \
  -e PREFIX=https://srcref.example.com \
  -e MAX_CACHE_SIZE=4096 \
  -e DEFAULT_BRANCH=main \
  pambrose/srcref:latest

Docker Compose

version: "3.8"
services:
  srcref:
    image: pambrose/srcref:latest
    ports:
      - "8080:8080"
    environment:
      PORT: 8080
      PREFIX: "https://srcref.example.com"
      MAX_CACHE_SIZE: 4096
      DEFAULT_BRANCH: main
    restart: unless-stopped

Building the Docker Image

The project includes a multi-architecture Docker build (amd64/arm64) using Alpine Linux with OpenJDK 17 JRE:

make release

Heroku

srcref includes a system.properties file for Heroku's Java runtime (Java 17):

# Deploy to Heroku
heroku create your-srcref-app
heroku config:set PREFIX=https://your-srcref-app.herokuapp.com
git push heroku master

Endpoints Reference

Once deployed, these endpoints are available:

Path Purpose
/edit Main web form UI
/github Redirect to computed GitHub permalink
/github?edit Edit an existing srcref URL
/problem Error display with message
/ping Health check (returns pong)
/what About srcref
/cache Cache status table
/version Version and build info
/threaddump JVM thread dump

Health Checks

Use /ping for health checks — it returns pong with a text/plain content type. This endpoint is excluded from request logging to avoid noise.

Cache Monitoring

The /cache endpoint displays a table of all cached file entries with:

  • URL of the cached file
  • ETag value
  • Content length
  • Age since first cached
  • Time since last referenced
  • Number of hits

Architecture Overview

graph TD
    A[Client Browser] -->|srcref URL| B[Ktor CIO Server]
    B --> C{Route Handler}
    C -->|/edit| D[Web Form UI]
    C -->|/github| E[URL Resolution]
    E --> F[ContentCache]
    F -->|Cache Miss| G[GitHub Raw Content]
    F -->|Cache Hit + ETag| G
    G -->|200 OK| F
    G -->|304 Not Modified| F
    F --> H[Regex Line Matching]
    H --> I[302 Redirect to GitHub]
    C -->|/problem| J[Error Display]

The server uses:

  • Ktor CIO — non-blocking coroutine-based HTTP server
  • ContentCache — in-memory LRU cache with ETag-based revalidation
  • Background daemon — evicts stale cache entries every 5 minutes
  • Compression — gzip and deflate response compression
  • CallLogging — request logging (excludes health checks and bot probes)