Skip to content

docs: onboarding from the Connectors tab, pinned-tag docker run example - #7

Closed
ryanlitalien wants to merge 1 commit into
mainfrom
docs/onboarding-from-connectors-tab
Closed

ryanlitalien wants to merge 1 commit into
mainfrom
docs/onboarding-from-connectors-tab

Conversation

@ryanlitalien

@ryanlitalien ryanlitalien commented Sep 8, 2026 •

Copy link
Copy Markdown
Member

This adds the missing pieces for a studio going from "I have a connector.yml" to a running container, and standardizes on tag pinning per the existing decision to not pursue digest publication.

Changes to README.md.

Added a docker run example using the real published image, pinned to ghcr.io/butterstack/butterstack-connector:v0.2.0, mounting a real connector.yml read only at /etc/butterstack/connector.yml, which is the path the image's entrypoint already reads from by default.

Added a short Image and versions note stating releases are pinned by semver tag and why not to run :latest.

Added a Configure subsection explaining that a studio gets its connector.yml from their ButterStack project's Integrations > Connectors tab in the web app, which generates the file already scoped with their real endpoint and token, and that they then fill in the perforce and/or teamcity sections themselves with their own LAN details. No hardcoded URL path was added since the repo has no existing stable link pattern to reuse for that page.

Kept the existing local docker build example as is.

connector.example.yml was read against internal/config/config.go field by field (Config, Scopes, Toggles, Perforce, TeamCity structs and their yaml tags, plus Validate's requirements) and it already matches the real schema exactly, so it needed no changes.

Verification performed.

Ran go build ./... and go test ./internal/config/... -v from the repo root. Build succeeded and all 12 existing config tests passed.

Built the daemon binary and ran it against connector.example.yml directly. With the file's placeholder token it fails at config: token is not a connector token, which is well past YAML decode and yaml.KnownFields(true), confirming every field name and nesting in the example matches the real Config struct. With a syntactically valid token substituted in, it passed endpoint validation, token format validation, perforce and teamcity block validation, and scope checks, and only stopped when creating its log directory failed for filesystem-permission reasons unrelated to config schema, before any network dial was attempted. This confirms the example file decodes and validates cleanly against the daemon's own loader.

Nothing internal or private is in this diff: no internal hostnames, no studio or customer names, no live tokens or secrets, no Tailscale IPs. Every host/URL in the diff is either the real public ghcr.io image path, the real public wss://connect.butterstack.com endpoint already used elsewhere in this repo, or a generic placeholder like or your-studio.

…ample

Adds a docker run example for the published ghcr.io image pinned to v0.2.0,
an "Image and versions" note on tag-pinning policy, and a Configure
subsection describing how a studio downloads its connector.yml from the
ButterStack app's Integrations > Connectors tab and fills in its own
perforce/teamcity sections. connector.example.yml was checked field-by-field
against internal/config/config.go and already matched the real schema, so
no changes were needed there.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@ryanlitalien

Copy link
Copy Markdown
Member Author

Superseded by the clean-history PR opened from the same diff.

@ryanlitalien
ryanlitalien deleted the docs/onboarding-from-connectors-tab branch September 8, 2026 00:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant