add info on releases to self-hosting docs

[chris48s]

The main thing going on in this PR is adding docs about tagged releases, but I updated a couple of other things (grouped docs about deploying from source together and docs about deploying with docker together, updated "now" to "vercel").

[chris48s]

@calebcartwright can you confirm this "releases" section covers all the points you think are important

[calebcartwright]

Apologies in advance as this won't be a succinct, direct answer to your question 😄 I feel like I need to get some clarity on direction before I can really comment on whether I feel we have complete documetation coverage here. Essentially, I'm still unclear if we're making any changes to what I'll call our "official" products, specifically as it relates to the server.

From my perspective, our official/released/supported products have consisted of the Shields.io service and the npm package, but the server/self-hosted hasn't been in that same tier.

Obviously given the open source nature of the repository, everyone has always had access to the source of the server code that powers the Shields.io service, and thus been able to deploy their own, and ~18 months ago we started building and publishing an image to DockerHub instead of only providing the Dockerfile for users to build the image themselves.However, my sense is that these actions were primarily about making it easier for someone to do their own self-hosting, as opposed to making the server a full blown "product" on par with the main service and npm package.

With that context around my current understanding, I have two primary points of concern/hesitation that will directly impact my thoughts on what I think should be documented:

1. Lack of clarity on the server/self-hosted offering, if any, particularly relative to the service and package
2. A reasonable person could interpret/assume things about the server/self-hosted offering that may not be true, particularly given the first bullet and some of the recent enhancements

My strong preference would be that as the core team we make a decision about the nature of our server/self-hosted offering, and then codify what our supported offerings are one way or the other (I think that should likely live outside the how-to-self-host-the-server doc though). Based on past discussions around the topic, I get the sense others my disagree that there's a lack of clarity and/or that there's a need for such an explicit decision. However, I'd really like to avoid ambiguity especially with the recent and ongoing enhancements around the releases of the server.

And to be clear, I'm not suggesting a thesis is needed here; I just think it's important to be explicit about whether the server is developed/maintained/etc. strictly for the Shields.io service with self-hosting/non-service use cases being a best effort and secondary, or if we're actually going to make the server itself as one of our core offerings along side the service and package, and users can expect a similar level of enhancement/support/etc.

Here's a few illustrative cases of why I think it's important to make it clear:

• We've historically rejected new badges that would only be available from self-hosted instances, e.g. those that required user/account-specific auth and would not be offerable via the Shields.io service (I forget the exact issues/cases, but hope others recall these discussions or have better issue-tracker-searching skills than I)
• We've historically declined (or at least de-prioritized) feature requests that are only relevant for self-hosted targets, but which have no utility for the service, for example running behind reverse proxies/serving on non-default paths (Running shields instance behind reverse proxy breaks page URLs #5894, How to set my 'path' when hosting my own server #4817), restricting access to the self-hosted instance at the server itself Locally Self hosted Docker returns internal error #4862 (comment) (few others I can't find ATM), etc.
• We've historically declined (or at least de-prioritized) deployment options that aren't relevant for the service hosting environment (OVH servers before, and now Heroku), e.g. Support for docker secrets #1778
• We've historically only offered very minimal support/troubleshooting for self-hosting issues (some of which is forced by the nature that we have no insight/access into self-hosting environments), e.g. Is it possible to connect to a private Jira Installation (on prem)? #5994, Setting up with Internal GitHub? #1753
• We don't do any testing/validation of the released server, and we don't used the released server for the Shields.io deployment artifact (heroku slug vs. docker image, we don't have functional tests for a self-hosted server configured with auth against different versions of tools, like SonarQube, etc.)

My sense is that our posture is really the former strategy from my description above (where we're Shields.io focused, other server releases/use cases are secondary), and all of those above positions and practices make perfect sense with that strategy. However, I'm not sure all of those would necessarily be tenable if our posture is actually the latter (server is a full blown product on par with service and package).

It's already not 100% clear to me as a maintainer what our posture actually is though, and I worry that the introduction of tags/releases in GitHub, versioned tags on published Docker images, change log, etc. without an explicit statement could really muddy the waters for users.

So to close out, and really reiterate, I'm primarily focused on getting clarity on our posture and documenting it accordingly, though if I'm mistaken and we are doing more with the server then I think we'll likely need some follow up discussions offline about the implications.

[chris48s]

That's a lot of text. I do have some thoughts on various bits of this and I've written some notes on it, but I'm going to be super-annoying and intentionally not reply to any of it here, except for one sentence 😄

I think that should likely live outside the how-to-self-host-the-server doc though

Bingo.
There's some stuff here that is worth talking about, but most of it seems like bigger wider issues and doesn't necessarily fit into a doc explaining how to set your own instance of Shields.

Lets accept the premise that we agree that allowing ourselves and our users to express the concept of "what version do I have" as server-2021-02-01 rather than 926f1e4 has value and we're going to do it (and given you've reviewed and approved #6069 and #6102 I think that's a reasonable base assumption).. What out of this do we need to deal with here to improve a document that tells you how to set up your own instance of shields (which is a document that already does exist and will continue to do so), and what can we move to another wider discussion?

[calebcartwright]

There's some stuff here that is worth talking about, but most of it seems like bigger wider issues and doesn't necessarily fit into a doc explaining how to set your own instance of Shields.

What out of this do we need to deal with here to improve a document that tells you how to set up your own instance of shields (which is a document that already does exist and will continue to do so), and what can we move to another wider discussion?

From my POV, if we want to keep this document and the discussion centered around setting up your own instance of Shields, then I don't think any of the above text belongs in this document. I'd note that things like the monorepo nature of repository, the versioning scheme for the npm package, cadence+description of server releases, etc. are not strictly related to the "what specific steps do I take to start my own Shields server" focus that this document currently has (which was why I made the comment about these topics potentially being better suited to a separate doc)

However, if we're going to broaden the scope of this document to also describe various aspects of releases and other information, as I'd suggest these proposed changes do, then I think it's only fair that the corresponding broadened scope be open for discussion as well.

Lets accept the premise that we agree that allowing ourselves and our users to express the concept of "what version do I have" as server-2021-02-01 rather than 926f1e4 has value and we're going to do it (and given you've reviewed and approved #6069 and #6102 I think that's a reasonable base assumption)

I've been raising these concerns repeatedly in various forums for a while now. I've accepted the collective decision that we're moving forward with some of these changes, and I've reviewed and approved because I felt the "how" (i.e. implementation) was a sound approach for the respective "what" (i.e. the change/enhancement). However, that doesn't mean that my main concern about clearly articulating and documenting the why behind the driver for making these changes has gone away.

To be honest, if the addition of documentation text that describes the new and enhanced releases isn't an appropriate forum to discuss/request additional docs about the releases, then I'm rather confused as to what would be an appropriate forum.

@calebcartwright can you confirm this "releases" section covers all the points you think are important

My position on this is overall theme is still the same:

• no, there's a couple other points about server releases that i think are important
• if we want to describe general, repo-wide release information like this then I think much, if not all, of this should live in a separate doc which this doc can link to

[chris48s]

The reason I'd suggest explaining some of this here is that step one of setting up your own install is getting some code or an image from somewhere. That does require making a choice so some level of explanation of what release assets exist, where you can find them and what the tradeoffs are is useful in making that decision.

I think I'm just going to close the PR and leave this document how it is for the moment though. Sounds like there's some bigger stuff to work out first (which needs more voices than just you and me). We can circle back to this in that context. Maybe if that drags out I'll do another PR just to pick out the non-controversial fixes (e.g: fix the now/vercel docs etc)

[shields-ci]

	Messages
📖	Thanks for contributing to our documentation. We ❤️ our documentarians!
📖	✨ Thanks for your contribution to Shields, @chris48s!

Generated by 🚫 dangerJS against 9afeee9