Docs on new signal deployment details

[minhkhul]

Description

Add deployment details to pipeline guide: CI/CD, staging test runs, cronicle setups.

[nmdefries]

You're fast! Thanks!

[nmdefries]

Waiting for #1983 to be approved before merging.

[korlaxxalrok]

We might consider keeping some of really specific details (hostnames, users, etc.) for our internal systems in a team-only or otherwise private location.

[nmdefries]

@korlaxxalrok I was thinking about that too, but I believe we already have these particular ones up on other public repos. Will double-check and link later today.

[nmdefries]

hostname publicly available here and here. User derivable here.

[nmdefries]

@korlaxxalrok which of these should be removed? Do we need to change any user or host names?

[korlaxxalrok]

Yeah, those are pretty well exposed already, so no point in making changes for them.

Generally, my instinct is that this kind of documentation should live privately "elsewhere" and we should link to it from our public assets. I realize the "elsewhere" part of this has never been solved, or when attempted to be solved has not been consistently adopted, but it is something we should still consider for the future and treat like a best practice when possible.

[melange396]

It doesnt hurt to scrub as much of the sensitive stuff as possible... Even if some bits of it are already "out there", reducing the number of current instances shrinks the attack surface (kinda) and makes it a little harder for a malicious actor to find useful information.

I definitely prefer having documentation like this in version control -- its easier to find, use, and see the timeline of changes. It puts instructions and details "next to" the code assets that are being discussed, and in a format closer to whats practical for developers and operations (as opposed to the complicated wysiwyg editor of gdocs).

We could create a new private documentation-only repository or even just a top-level /documentation directory in the existing private https://github.com/cmu-delphi/delphi-admin repo. It wouldnt be as nice as having the docs in the same repo as the code, but it would be protected and cross-references will be handled well by the github web ui (for privileged users).

[melange396]

ie:

• https://github.com/cmu-delphi/delphi-admin/issues/204
  (^ the issue title is shown for Delphi org members but is only shown as the bare url for a user without authN (and presumably un-authZ'd users too))

[korlaxxalrok]

Something like Docsify might be nice, for eventually building a docs site from Markdown files. I'd maybe push for a separate repo, to make it simpler to clone the repo without getting extra stuff (delph-admin comes with a lot of extra bits), to add access control, and to eventually make it easier to add CI to build a site from it.

We tried something like this before, but with a different tool (mkdocs), ultimately building it into a small site at https://delphi.cmu.edu/systems-handbook. There is a process to clone the repo, make changes, build it locally for review, and publish changes. It never caught on though, and the wheel kept going round.

[nmdefries]

I agree completely, great points. The "where" is definitely a problem. I wanted to put the "how to make an indicator" manual in this repo so it's close to all the indicator code.

Alternative ideas:

• Put documentation/manuals in relevant repo, but omit host/user/login details and just say "talk to Brian"
• Ditto but link to login details stored in a separate private repo
• Put all documentation/manuals in a dedicated private repo. I like that it'd be on GH, but harder to discover for a given topic
• Put all documentation/manuals in a dedicated folder in GDrive. Also not discoverable

[nmdefries]

@melange396 opened an issue for this. delphi-admin is private and so a good place to store sensitive info.

[dsweber2]

just a couple of comments/questions as someone who hasn't done deployment (so would have to be just going off these notes to do it).