Your own CDN, anywhere you want.

Architecture

Gimme is a thin, stateless Go service. It sits between your clients and an S3-compatible object store, handling authentication, semver resolution, and streaming. A reverse proxy in front is recommended for production.

Browser / CLI

→

Nginx / CDN optional

→

gimme :8080

version resolution

Redis / Valkey optional (tokens + cache)

→

S3 storage

Package naming convention

Objects are stored in S3 as <package>@<version>/<file>:

my-lib@2.1.0/my-lib.min.js
my-lib@2.1.0/my-lib.min.css
my-lib@2.1.1/my-lib.min.js   ← next patch

Semver partial resolution

A request for my-lib@2.1/file.js lists the package's versions in S3 (one entry per version, not per file) and serves the file from the highest matching version. If that version does not contain the file, the request returns 404. With Redis enabled, the resolved path is cached — S3 is only hit on a cache miss.

Quickstart

git clone https://github.com/ziggornif/gimme
cd gimme/examples/deployment/docker-compose/with-garage
docker compose up -d

admin:
  user: gimmeadmin
  password: change-me
port: 8080
secret: your-secret-at-least-32-chars-long
s3:
  url: s3.amazonaws.com     # or s3.fr-par.scw.cloud, etc.
  key: your-access-key
  secret: your-secret-key
  bucketName: gimme
  location: eu-west-1
  ssl: true

docker run -p 8080:8080 \
  -v "$(pwd)/gimme.yml:/config/gimme.yml" \
  ziggornif/gimme:latest

git clone https://github.com/ziggornif/gimme
cd gimme
cp gimme.example.yml gimme.yml
# Edit gimme.yml with your S3 credentials
make build && ./gimme

make watch

Your first upload in 3 steps

curl -s -X POST http://localhost:8080/tokens \
  -u gimmeadmin:gimmeadmin \
  -H 'Content-Type: application/json' \
  -d '{"name": "my-token", "expirationDate": "2027-12-31"}'

curl -X POST http://localhost:8080/packages \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@my-lib.zip" \
  -F "name=my-lib" \
  -F "version=1.0.0"
# → 201 Created

<script src="http://localhost:8080/gimme/my-lib@1.0.0/my-lib.min.js"></script>

Configuration

Config is loaded from gimme.yml (local directory or /config/gimme.yml inside Docker). Every value can be overridden by an environment variable — Viper maps them automatically with the GIMME_ prefix (e.g. GIMME_S3_URL, GIMME_ADMIN_USER).

admin:
  user: gimmeadmin
  password: gimmeadmin
port: 8080
secret: your-secret-at-least-32-chars-long
s3:
  url: your.s3.endpoint
  key: your-access-key
  secret: your-secret-key
  bucketName: gimme
  location: garage       # region as defined by your backend
  ssl: false             # set false for local Garage
metrics: true            # expose /metrics (Prometheus)

# Token store: "file" (default), "redis", or "postgres"
# tokenStore:
#   mode: file           # "file" | "redis" | "postgres"
#   pg_url: postgres://gimme:password@localhost:5432/gimme?sslmode=disable

# Redis — required when tokenStore.mode is "redis" or cache.enabled is true
# redis_url: redis://localhost:6379

# cache:
#   enabled: false       # optional version-resolution cache
#   type: redis
#   ttl: 3600
#   file_path: /tmp/gimme-tokens.enc  # used only when tokenStore.mode is "file"

Deployment

• 🐳

  Docker Compose + Garage

  Zero-setup stack with self-hosted Garage storage, Valkey cache and Prometheus/Grafana monitoring bundled in.

  View on GitHub
• ☁️

  Docker Compose + managed S3

  Connect to any managed provider (AWS S3, OVH, Scaleway, Cellar, R2). Monitoring included.

  View on GitHub
• ☸️

  Kubernetes

  Namespace, Deployment, Service and Ingress manifests. Liveness and readiness probes pre-configured.

  View on GitHub
• ⎈

  Helm chart

  Production-ready Helm chart published on GHCR. Secrets, Ingress, HPA and Redis cache configurable via values.yaml.

  View on GitHub
• ⚙️

  systemd

  Run as a Linux system service with automatic restarts and environment file support.

  View on GitHub

Helm chart

The Helm chart is published on GHCR (OCI) and provides a production-ready deployment with credentials in a dedicated Kubernetes Secret, optional Ingress with TLS, HPA and Redis cache.

Install

helm install gimme oci://ghcr.io/ziggornif/charts/gimme \
  --namespace gimme \
  --create-namespace \
  --set credentials.secret=<signing-secret-min-32-chars> \
  --set credentials.admin.user=<admin-user> \
  --set credentials.admin.password=<admin-password> \
  --set credentials.s3.key=<s3-key> \
  --set credentials.s3.secret=<s3-secret> \
  --set s3.url=<s3-endpoint-url>

Or with a values.yaml file:

helm install gimme oci://ghcr.io/ziggornif/charts/gimme \
  --namespace gimme --create-namespace \
  -f my-values.yaml

Minimal values.yaml

credentials:
  secret: "your-secret-at-least-32-chars-long"
  admin:
    user: "admin"
    password: "strongpassword"
  s3:
    key: "your-s3-access-key"
    secret: "your-s3-secret-key"

s3:
  url: "https://s3.example.com"
  bucketName: gimme
  location: eu-west-1
  ssl: true

Enable Ingress with TLS

ingress:
  enabled: true
  className: nginx
  host: cdn.example.com
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  tls:
    enabled: true
    secretName: gimme-tls

Enable Redis cache

cache:
  enabled: true
  type: redis
  ttl: 3600
  redisUrl: redis://my-redis-service:6379

Enable HPA (auto-scaling)

hpa:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

Upgrade / Uninstall

# Upgrade
helm upgrade gimme oci://ghcr.io/ziggornif/charts/gimme \
  --namespace gimme -f my-values.yaml

# Uninstall
helm uninstall gimme --namespace gimme

Single Docker container

docker run -p 8080:8080 \
  -v "$(pwd)/gimme.yml:/config/gimme.yml" \
  ziggornif/gimme:latest

Health probes

API Reference

Create a token

curl -s -X POST http://localhost:8080/tokens \
  -u gimmeadmin:gimmeadmin \
  -H 'Content-Type: application/json' \
  -d '{"name": "my-token", "expirationDate": "2027-12-31"}'

{"id": "550e8400-...", "name": "my-token", "token": "gim_4a7b9c2d1e3f...", "createdAt": "...", "expiresAt": "..."}

Upload a package

Package names may contain only letters, digits, ., _, and -. Versions must be full semver versions such as 1.0.0; prerelease and build metadata are accepted.

curl -X POST http://localhost:8080/packages \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@my-lib.zip" \
  -F "name=my-lib" \
  -F "version=1.0.0"
# → 201 Created

Serve a file

# Exact version — cached for 1 year
curl http://localhost:8080/gimme/my-lib@1.0.0/my-lib.min.js

# Partial alias — resolves to latest 1.0.x, cached 5 minutes
curl http://localhost:8080/gimme/my-lib@1.0/my-lib.min.js

# Read the SHA-384 SRI token without downloading the body
curl -I http://localhost:8080/gimme/my-lib@1.0.0/my-lib.min.js

Newly uploaded files expose their Subresource Integrity token through Gimme-Integrity. The package listing can copy ready-to-use JavaScript and CSS snippets; legacy objects remain available without the header.

The generated crossorigin="anonymous" attribute requires an Access-Control-Allow-Origin response header. Gimme defaults to *, so this works out of the box. Setting cors.allowed_origins to a fixed list silently breaks SRI for cross-origin consumers whose origins are not included.

Delete a package

curl -X DELETE http://localhost:8080/packages/my-lib@1.0.0 \
  -H "Authorization: Bearer $TOKEN"
# → 204 No Content

Only that exact version is deleted. Versions must be full semver; a partial or invalid version returns 400 Bad Request.

Caching

Two independent caching levels that compose naturally:

Level 1 — HTTP Cache-Control zero dependency

Gimme emits Cache-Control headers on every response. Any HTTP cache honours them automatically.

Compressible files are stored with Brotli and gzip variants during upload. Requests negotiate them with Accept-Encoding, and responses emit Vary: Accept-Encoding so browsers and intermediate caches keep each representation separate. Missing variants fall back to the identity object; older packages must be re-uploaded to gain compressed variants.

Every file response also carries ETag and Last-Modified. Gimme answers 304 Not Modified when If-None-Match matches, or when If-Modified-Since matches and If-None-Match is absent. Revalidating a partial version therefore transfers only headers when the file has not changed, instead of downloading the body again.

Level 2 — Internal Redis cache optional

When enabled, the resolved S3 path for partial versions is stored in Redis, skipping the package version listing (one entry per version, not per file) on repeat requests. File bodies are always streamed directly from S3 — only the path lookup is cached.

redis_url: redis://localhost:6379
cache:
  enabled: true
  type: redis
  ttl: 3600

Cache entries are invalidated when a package is deleted via DELETE /packages/:package. Partial-version entries expire naturally via TTL.

Monitoring

Every instance exposes a /metrics endpoint in OpenMetrics format. In addition to standard Go runtime metrics, gimme tracks:

A pre-configured Prometheus + Grafana stack ships with both Docker Compose examples. Once running: Prometheus at :9090, Grafana at :3000.