s3-gateway/README.md

# s3-gateway

Downstream build pipeline that produces **de-branded
[versitygw](https://github.com/versity/versitygw) releases** — the
upstream Versity S3 Gateway with Versity trademarks and logos removed
from the admin web UI.

Same pattern as [`scoutfs-build`](../scoutfs-build): pull an upstream
release **tag**, apply our **patch series** scoped to that tag, build
with upstream's GoReleaser, and publish to **Gitea Releases**.

Artifact names are intentionally **unchanged** — the binary stays
`versitygw` and the deb/rpm packages stay `versitygw`, so builds are
drop-in compatible with existing configs, systemd units, and the
`versitygw` CLI. Only the embedded web UI is rebranded to "S3 Gateway".

```
 upstream tag (vX.Y.Z)            this repo
 github.com/versity/versitygw     patches/<tag>/*.patch
        │                                │
        ▼                                ▼
   ci/clone-source.sh  ───►  ci/apply-patches.sh  ───►  ci/build.sh  ───►  ci/publish-release.sh
   (shallow clone tag)      (git am --3way)            (goreleaser)        (Gitea release assets)
```

`ci/support-matrix.yaml` records which upstream versions have a curated
patch set and maps each to its patch directory.

## Layout

```
s3-gateway/
├── ci/
│   ├── support-matrix.yaml   # upstream tag -> patch directory (registry)
│   ├── clone-source.sh       # shallow-clone upstream versitygw at a tag
│   ├── apply-patches.sh      # git am --3way patches/<tag>/*.patch
│   ├── build.sh              # goreleaser release (binaries + deb/rpm)
│   ├── publish-release.sh    # upload dist/* to a Gitea release
│   └── run.sh                # local end-to-end: clone + patch + build one tag
├── patches/
│   └── v1.5.0/
│       └── 0001-webui-debrand.patch
├── .gitea/workflows/build.yml
└── docs/multi-version-pipeline.md
```

## Build locally

Prerequisites: `git`, `go`, and [`goreleaser`](https://goreleaser.com).

```bash
# Build one upstream tag end-to-end → artifacts in src/dist/
VGW_TAG=v1.5.0 bash ci/run.sh

# Fast offline build against a local upstream clone:
VGW_REPO_URL="/path/to/versitygw" VGW_TAG=v1.5.0 bash ci/run.sh
```

Or run the steps individually:

```bash
VGW_TAG=v1.5.0 bash ci/clone-source.sh   # → src/
VGW_TAG=v1.5.0 bash ci/apply-patches.sh  # git am the series onto src/
VGW_TAG=v1.5.0 bash ci/build.sh          # goreleaser → src/dist/
```

`src/` and `src/dist/` are gitignored.

## Patches

Patch sets live in `patches/<dir>/` as `git format-patch` files and are
applied with `git am --3way`, in filename order. The directory for a
tag comes from the `patches:` field in `ci/support-matrix.yaml`
(defaults to the tag name).

Currently maintained:

| Upstream tag | Patch set     | Contents                          |
|--------------|---------------|-----------------------------------|
| `v1.5.0`     | `v1.5.0/`     | `0001-webui-debrand.patch`        |

### What the de-brand patch does

- Sidebar/login logos → a plain **"S3 Gateway"** wordmark.
- Page titles: "VersityGW Dashboard" → "Dashboard" (Buckets/Users/Explorer too).
- Browser tab titles → "S3 Gateway – …".
- Removes the sidebar **Resources** section (external `github.com/versity` links).
- Replaces the Versity favicon with a neutral SVG; deletes the Versity logo PNGs.
- Removes the visible "© Versity Software Inc." footer from the login page.

Deliberately **kept** (license compliance): the per-file Apache-2.0
license headers — which carry the upstream copyright notice as an HTML
comment at the top of each file — and the `NOTICE` file. Upstream is
Apache-2.0; the de-brand strips the visible Versity *trademarks* (logos,
wordmarks, and the login footer) while preserving the *copyright* notice
in the source headers.

## Adding / refreshing a version

When upstream cuts a new release you want a build of, you rebase the
patch series onto it and add a patch directory. See
[docs/multi-version-pipeline.md](docs/multi-version-pipeline.md) for the
full recipe. In short:

```bash
# Rebase the series onto the new tag, re-export into patches/vX.Y.Z/
git clone https://github.com/versity/versitygw && cd versitygw
git -c core.autocrlf=false checkout -b debrand vX.Y.Z
git am --3way /path/to/s3-gateway/patches/<prev>/*.patch   # resolve any conflicts
git format-patch --binary vX.Y.Z..HEAD -o /path/to/s3-gateway/patches/vX.Y.Z/
```

Then add the tag to `ci/support-matrix.yaml`, commit, and build it (see
below).

## CI

`.gitea/workflows/build.yml` builds **one version per run** and
publishes it to a Gitea release in this repo. It triggers two ways — no
scheduled/cron builds:

- **By new tag** — push a `vX.Y.Z` tag to this repo; CI builds upstream
  versitygw `vX.Y.Z` with `patches/vX.Y.Z/`.
- **One-shot** — run the **build** workflow manually (workflow_dispatch)
  and enter the upstream tag to build.

Configuration:

- **Runner**: any Linux runner (`runs-on: ubuntu-latest`). The Go
  toolchain comes from the `golang` container, so the runner only needs
  Docker.
- **Secret**: `TOKEN_GITEA` — a Gitea PAT with **write:repository**
  (clones this repo + creates releases / uploads assets).
- **Variable (optional)**: `VGW_REPO_URL` to override the upstream URL.

## License

Apache-2.0, matching versitygw upstream. Upstream copyright and
`NOTICE` are retained in every build.