Skip to content

Bring deployment playbook information back into repo#185

Open
BenjaminPelletier wants to merge 1 commit intomasterfrom
docs-deployment
Open

Bring deployment playbook information back into repo#185
BenjaminPelletier wants to merge 1 commit intomasterfrom
docs-deployment

Conversation

@BenjaminPelletier
Copy link
Member

This PR outlines a plan to bring the ~current content of the wiki pages back into the repo so changes to code can be synchronized with changes to documentation (and vice-versa). The content of Deployment is brought in with this PR, and the plan would be to bring the content of Maintenance and Troubleshooting in with future PRs.

The list of things that live in the repo is also improved by adding links -- this should improve reader experience if they see that the thing they're interested is in the repo somewhere, but it's not clear where.

@hcooper hcooper self-requested a review March 23, 2026 06:57
Copy link
Contributor

@hcooper hcooper left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

playbook structure LGTM - but this doc has a bunch of old & broken information in it.

I've been through it and worked on the general readability and contextual advice a new developer might want. It's up on the GH wiki:
https://github.com/RopeWiki/app/wiki/Site-Deployment (not to stay - just because I find it much easier iteratively editing there).

Compared to the original the main technical differences are:

  • dumped windows specific instructions in favor of mentioning WSL. It seems the de facto approach for linuxy things on windows these days.
  • reformat command blocks to make them copy-and-pasteable
  • removed defunct port 22002 from firewall rules
  • never been sure what "setup firewall by importing rules" meant so removed it (TBH not sure firewall setup should be in the doc at all. I was thinking some other production-specific doc might make sense, keeping this one as generic developer docs).
  • pruned old advice about docker versions and rng. After multiple fresh installs in a modern environment in the last 3+ years I haven't ever run into these issues.
  • get_sql_backup_legacy is broken - replaced with direct rsync command.
  • get_images_legacy is broken - replaced with direct rsync command.
  • Note: looks like proxy_config in site_configs is defunct and can references can be purged.
  • removed references to accessing the webserver on port 8080 as that was removed a while ago IIRC.
  • updated TLS instructions to describe how production has worked since ~2023 but kept details of how deploy_tool is meant to work.

Approving this PR (since it's the same as what we had before), but feel free to update the PR with any of the newer changes or anything else docy you want.

@BenjaminPelletier
Copy link
Member Author

Thanks, sounds good and I think we're on the same page, but to make sure: do you support the following sequence of events? (if not, please let me know which ones you don't like/support)

  1. Merge this PR as-is
  2. Immediately create a new PR with the Site Deployment wiki content updates from last night (ideally you'd create this PR, but I'm happy to be the surrogate creator if you'd prefer)
  3. (simultaneous with 2) Add a banner note to the top of the Site Deployment wiki page saying that this document is a working scratchpad and the canonical/real/current content should be found in the repo (with link)
  4. Merge new PR after any iteration needed
  5. Keep banner note on Site Deployment wiki page saying it is a scratchpad, but clear all content below that (so the next person doesn't start editing from non-canonical content)

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.

2 participants