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 triggers a ListObjects call in S3, sorts all matching versions, and redirects to the highest patch. 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

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

Delete a package

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

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.

Level 2 — Internal Redis cache optional

When enabled, the resolved S3 path for partial versions is stored in Redis, skipping ListObjects 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.