From 8676de2cc606de4d870b9c8fa487475058900940 Mon Sep 17 00:00:00 2001 From: "Chris (wolcen) Thompson" Date: Tue, 14 Nov 2023 14:25:43 -0500 Subject: [PATCH] Update basic Drutopia documentation --- tools/creating-new-drutopia-site.md | 2 +- tools/deploying-drutopia-updates.md | 89 +++++++++++++++++++++-------- 2 files changed, 67 insertions(+), 24 deletions(-) diff --git a/tools/creating-new-drutopia-site.md b/tools/creating-new-drutopia-site.md index 9141f3e..11bfbc0 100644 --- a/tools/creating-new-drutopia-site.md +++ b/tools/creating-new-drutopia-site.md @@ -5,7 +5,7 @@ Agaric manages a large number of Drupal, primarily [Drutopia](https://drutopia.o Please see [the Drutopia Platform README for an overview of hosting and deploying Drutopia sites](https://gitlab.com/drutopia-platform/drutopia_host#introduction ) If you won't be deploying, skip overall setup. -Following this guide requires a working [DDEV](https://ddev.readthedocs.io/en/latest/) installation. See also the [general Git setup](git-setup) if you have not yet. +Following this guide requires a working [DDEV](https://ddev.readthedocs.io/en/latest/) installation. Deploying to Drutopia will require a locally installed composer, as well as ansible. See also the [general Git setup](git-setup) if you have not yet. ## Overall setup diff --git a/tools/deploying-drutopia-updates.md b/tools/deploying-drutopia-updates.md index b1d1aba..25f5bea 100644 --- a/tools/deploying-drutopia-updates.md +++ b/tools/deploying-drutopia-updates.md @@ -2,21 +2,19 @@ ## Prerequsites -A bit more PHP than you need, but this will definitely get you ready for composer and friends: +Ensure you have at least PHP 7.2.5 installed. An 8.x version is recommended. -@TODO Switch these commands to PHP 8.1? - -```bash -sudo apt-get install ansible rsync php7.4 php7.4-gd php7.4-mysql php7.4-xml php7.4-curl php7.4-fpm php7.4-sqlite3 php7.4-cli +```shell +sudo apt-get install ansible rsync php8.1-cli ``` Then follow the commands from: [getcomposer.org/download](https://getcomposer.org/download/) -And then: +Including the recommended: -```bash +```shell sudo mv composer.phar /usr/local/bin/composer ``` @@ -30,56 +28,101 @@ Finally, [clone needed Drutopia repositories locally according to the recommende Now you are ready for deploying Drutopia updates on a regular basis. -## Ensure you are up-to-date +## Configure live to reach test instance -```bash +**These instructions are no longer recommended. The Drutopia member role will set up the SSH connection along with the sync script (`sync_to_test.sh`).** + +Log into the server on the live side, and check if you can reach the test side from there: + +```shell +ssh {site}_live@drutopia.org # If using our ssh-config: d-{site}-live +ssh {site}_test@drutopia.org # d-{site}-test is not available here! +# If that command fails, create an ssh key: +ssh-keygen +cat ~/.ssh/id_rsa.pub +``` +Copy the output of the cat command and disconnect (ctrl+d). Then add that public key to the authorized_hosts on the test side: + +```shell +ssh {site}_test@drutopia.org +vi ~/.ssh/authorized_hosts +``` +`shift+g` to get to the bottom, `o` to get into add mode on a new line, `ctrl+shift+p` (or appropriate) to paste the key, then `{esc}` to exit insert more, and `:wq` to write changes and quit. + +Re-test reaching the server from the live side. This time you will have to accept the host key verification for drutopia.org which should be: `SHA256:MQXYY1PcuEgnIdyYawJSNZHbvLMwBXOx5CyDBvNSBmI.` + +## Perform a sync to test + +Log into the live version of the site and perform a sync of the db and files to the test instance: + +```shell +ssh {site}-live@drutopia.org # If using our ssh-config: d-{site}-live +sync_to_test.sh +``` + +## Ensure you are up-to-date with all hosting repositories + +```shell cd ~/Projects/drutopia-platform/drutopia_host/hosting_private ahoy git-pull-all ``` -```bash +## Creating new site hosting entries + +You can use ahoy to build a templated YAML snippet for yourself: + +```shell ahoy new-site example ``` -And, following the instructions that provides, copy the +Following the instructions this command provides to pull the newly created file into the vault. -```bash -ansible-vault edit host_vars/elizabeth.mayfirst.org/vault.yml +## Finding the site name and identify builds + +```shell +## Determine the build to deploy +ahoy vault-view +# Without ahoy: +ansible-vault view host_vars/elizabeth.mayfirst.org/vault.yml ``` +Search for the site you are deploying. The `drutopia_version: ` key will identify the build to deploy in the next step. + If using typical `sitename-test.drutopia.org` and `sitename-live.drutopia.org` domains pending the real site domain, add the subdomains to drutopia.org through the [May First control panel](https://members.mayfirst.org/cp/) -## Prepare appropriate base +## Prepare the appropriate base build -```bash +Using ahoy, specify the name of the build to create as an argument to `ahoy deploy-build`: + +```shell ahoy deploy-build next ``` ## Deploy your site -```bash +```shell ahoy deploy-site example_test ``` -And you can share back the record of the deployments in the `build_artifacts` repository with this: +And you can then share back the record of the deployments in the `build_artifacts` repository with: -```bash +```shell ahoy artifacts ``` ## Putting it all together -```bash +```shell cd ~/Projects/drutopia-platform/drutopia_host/hosting_private ahoy git-pull-all -ahoy deploy-build next +ahoy deploy-build stable ahoy deploy-site example_live ahoy artifacts ``` ## If you need to override site configuration: -```bash +```shell ahoy deploy-site-force example_test ``` @@ -87,7 +130,7 @@ ahoy deploy-site-force example_test If you have new content on the live site that you want to see how your code works with, or if you have created entities on the test site that block the removal of configuration you changed your mind about, you will want to sync from live to test. -```bash +```shell ssh d-example-live sync_to_test.sh ``` @@ -98,7 +141,7 @@ This handles making a paranoia dump of the test site in `~/backups`, dropping th To try to keep various Drutopia-based distributions from diverging too much, at least insofar as available modules, even if they aren't installed, we can use the **meld** (`sudo apt-get install meld`) diff tool to compare and share when posssible. -```bash +```shell meld ~/Projects/agaric/sites/crla/crla-org/composer.json ~/Projects/agaric/sites/geo/composer.json ~/Projects/drutopia-platform/build_source/composer.json ~/Projects/agaric/sites/agaric-com/composer.json ```