docs: onboarding from the Connectors tab, pinned-tag docker run example - #8
Merged
Merged
Conversation
…ample notes Add a README section on creating a connector in ButterStack (Integrations > Connectors), filling in the connector.yml it hands out, and running the published image pinned by tag. State the tag-pinning policy for releases.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.