Jump to content

Setting up a local Canasta dev copy

From notes

This guide explains how to set up a local development copy of the wiki farm using Canasta's gitops and backup features.

Overview

There are two complementary systems at play:

  • Backup (canasta backup) captures everything — databases, uploaded files, and configuration. A backup alone is sufficient to stand up a complete copy of the wiki farm.
  • Gitops (canasta gitops) tracks configuration only — settings files, extensions, skins, environment template, and wiki farm structure — in a version-controlled git repo with encrypted secrets. It does not include database content or uploaded files.

For local development, you need both: the backup provides the database and files, while gitops gives you the shared configuration repo so that changes you make locally can be pushed back and pulled onto the live server.

Steps

1. Back up the live wiki

On the live server (example.com): 

canasta backup create -t <tag>

Replace <tag> with whatever string you'd like this backup to be tagged with so you can find it in the listing.

2. Create a local Canasta instance

On your local machine: 

canasta create -i <instance> -w <wiki>

Replace <instance> with whatever you want to call your local wiki farm and <wiki> with whatever the wiki is called on the prod server.

3. Restore a database backup from the live wiki

You'll need the restic backup credentials from the example.com .env file — specifically RESTIC_REPOSITORY, RESTIC_PASSWORD, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY. Add those to your local instance's .env file.

Then find a snapshot to restore from. In the wiki farm instance directory: 

canasta backup list

Find the snapshot ID of the backup with your tag and restore it: 

canasta backup restore -s <snapshot-id>

This will restore all wikis in the backup. It will overwrite your empty dev wiki with the production data.

4. Join the gitops repo

First, edit config/wikis.yaml to change the wiki URLs to your local server (e.g., localhost). The backup restore set them to the production URLs, but you need local URLs for your dev instance.

Copy ~/gitops_keyfile from example.com to your local machine, then: 

canasta gitops join -n <yourname> --role both --repo git@github.com:organization/repo.git --key /path/to/gitops-keyfile

Replace <yourname> with whatever you want to call your local setup. This clones the repo into your installation, overlays the tracked config/extensions/skins, adds your host to hosts.yaml, captures your local wiki URLs and secrets into hosts/yourname/vars.yaml, and pushes the host entry. From this point on, config/wikis.yaml is rendered automatically from the shared template using your host's URLs — you won't need to edit it again.

I currently don't have it set to require pull requests, so it will push directly to the main branch, but we can change that if you think it is best.

Note: joining the gitops repo adds your dev host to hosts.yaml and creates hosts/yourname/vars.yaml. If you ever tear down the local instance and no longer need it, you can clean up by removing your host entry from hosts.yaml and deleting the hosts/yourname/ directory, then pushing that change.

5. Make changes, test, and push

Edit files, test locally, then: 

canasta gitops add config/settings/global/MyChange.php
canasta gitops push -m "Description of change"

6. Pull changes on the live server

Back on example.com, in the wiki farm directory: 

canasta gitops pull

This pulls the latest configuration, renders host-specific files (.env, config/wikis.yaml) from their templates, and reports whether a restart is needed.

Retrieved from "https://notes.amethyst-ck.com/w/index.php?title=Setting_up_a_local_Canasta_dev_copy&oldid=63"