Skip to content

Latest commit

 

History

History
202 lines (175 loc) · 9.83 KB

cli.md

File metadata and controls

202 lines (175 loc) · 9.83 KB
Raw

Canasta CLI

The Canasta command line interface, written in Go.

Pre-requisites

Before using the Canasta CLI, you must have both Docker Engine and Docker Compose installed.

Windows and macOS

Docker Compose is included in Docker Desktop for Windows and macOS.

Linux

Linux is the most-tested and preferred OS environment as the host for Canasta. Installing the requirements is fast and easy to do on common Linux distributions such as Debian, Ubuntu, Red Hat, and CentOS. While you can get up and running with all the Docker requirements by installing Docker Desktop on Linux, if you are using a 'server environment' (no GUI), the recommended way to install is to uninstall any distribution-specific software and install Docker software using the Docker respositories. (The link is the install guide for Docker Compose which will also install the Docker Engine.)

Example

Essentially, preparing your Linux server to be a Canasta host by installing the Docker suite of software includes something like sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin once you've added the Docker repositories to your system. A full example script for Ubuntu can be found at example-prepare-ubuntu-headless.sh

Installation

Then, run the following line to install the Canasta CLI (be sure you have write permissions in the current working directory):

curl -fsL https://raw.githubusercontent.com/CanastaWiki/Canasta-CLI/main/install.sh | bash

All available commands

This is the output of the Canasta CLI help printout:

A CLI tool to create, import, start, stop and backup multiple Canasta installations

Usage:
  canasta [flags]
  canasta [command]

Available Commands:
  add         Add a new wiki to a Canasta instance
  create      Create a Canasta installation
  delete      Delete a Canasta installation
  extension   Manage Canasta extensions
  help        Help about any command
  import      Import a wiki installation
  list        List all Canasta installations
  maintenance Use to run update and other maintenance scripts
  remove      remove a new wiki from a Canasta instance
  restart     Restart the Canasta installation
  restic      Use restic to backup and restore Canasta
  skin        Manage Canasta skins
  start       Start the Canasta installation
  stop        Shuts down the Canasta installation
  upgrade     Upgrade a Canasta installation to the latest version
  version     Show the Canasta version

Flags:
  -d, --docker-path string   path to docker
  -h, --help                 help for canasta
  -v, --verbose              Verbose output

Use "canasta [command] --help" for more information about a command.

Create a wiki

  • Run the following command to create a new Canasta installation with default configurations. This will create a folder named canastaId in the directory in which you're running this command.
sudo canasta create -i canastaId -n example.com -w Canasta Wiki -a admin -o compose
  • Visit your wiki at its URL; for the above command, it would be https://example.com. (if Canasta is installed locally or you did not specify any domain, it would be http://localhost.)
  • For more info on finishing up your installation, go to the after installation section.

Import an existing wiki

  • Place all the files mentioned below in the same directory for ease of use.
  • Create a .env file and customize as needed (more details on how to configure it at configuration, and for an example see .env.example).
  • Drop your database dump (in either a .sql or .sql.gz file).
  • Place your existing LocalSettings.php and change your database configuration to be the following:
    • Database host: db
    • Database user: root
    • Database password: mediawiki (by default; see Configuration)
  • Then run the following command:
sudo canasta import -i importWikiId -d ./backup.sql.gz -e ./.env -l ./LocalSettings.php
  • Visit your wiki at its URL (or http://localhost if installed locally or if you did not specify any domain).
  • For more info on finishing up your installation, visit after installation.

Create additional wikis (wiki farm)

You can create additional wikis on the same server by calling canasta create to create additional Canasta instances, but the generally much better approach is to call canasta add, which adds additional wikis to the same Canasta instance, thus turning the installation into what is known as a "wiki farm". A typical call on a server with the domain example.com might look like:

sudo canasta create -i canastaId -w soccerwiki -u soccer.example.com -s "Soccer Wiki" -a admin

There are various other flags for canasta add (10 in all); an important additional one is --database or -d, which lets you specify an existing database dump, thus providing an equivalent call to canasta import for a wiki farm setup.

There is no limit to how many wikis can be run within the same Canasta installation. As is typical for wiki farms, all wikis within the same installation will run on the same software, but using different databases and images directories.

To view all wikis within any installation, call canasta list; it will list all Canasta installations on the server, a well as all wikis contained within each installation.

To delete a specific wiki, but not the whole Canasta installation, call canasta delete; a typical call would look like:

sudo canasta remove -i canastaId -w soccerwiki

Enable/disable an extension

  • To list all Canasta extensions that can be enabled or disabled with the CLI, run the following command:
sudo canasta extension list -i canastaId
  • To enable a Canasta extension, run the following command:
sudo canasta extension enable Bootstrap -i canastaId
  • To disable a Canasta extension, run the following command:
sudo canasta extension disable VisualEditor -i canastaId
  • To enable/disable multiple Canasta extensions, separate the extensions with a ',':
sudo canasta extension enable VisualEditor,PluggableAuth -i canastaId
  • Note: The extension names are case-sensitive.

Enable/disable a skin

  • To list all Canasta skins that can be enabled or disabled with the CLI, run the following command:
sudo canasta skin list -i canastaId
  • To enable a Canasta skin, run the following command:
sudo canasta skin enable Vector -i canastaId
  • To disable a Canasta skin, run the following command:
sudo canasta skin disable Refreshed -i canastaId
  • To enable/disable multiple Canasta extensions, separate the extensions with a ',':
sudo canasta skin enable CologneBlue,Modern -i canastaId
  • Note: the skin names are case-sensitive.

Using restic

restic is a very useful utility for doing automated backups to a variety of different storage types; though Canasta's usage of restic is configured for using AWS S3-based repositories.

Canasta makes use of restic's dockerized binary.

How to get started

  1. Add these environment variables to your Canasta installation's .env file. Follow the steps at cli-configure-quickstart to obtain ACCESS_KEY_ID and SECRET_ACESS_KEY.
AWS_S3_API=s3.amazonaws.com
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_S3_BUCKET=
RESTIC_PASSWORD=
  1. When using restic for the first time in a Canasta installation, run the following command to initialize a restic repo in the AWS S3 bucket specified in the .env file:
sudo canata restic init -i canastaId

Now you should be able to use any of the available commands.

Available restic commands

check         Check restic snapshots
diff          Show difference between two snapshots
forget        Forget restic snapshots
init          Initialize a restic repo
list          List files in a snapshost
restore       Restore restic snapshot
take-snapshot Take restic snapshots
unlock        Remove locks other processes created
view          View restic snapshots

Use "sudo canasta restic [command] --help" for more information about a command.

/etc/canasta/conf.json

  • Canasta CLI maintains a list of installations that it manages. This information is stored at /etc/canasta/conf.json. Therefore the CLI would require permissions to read and write to the /etc/canasta/ folder.
  • The layout of the conf.json file is as follows:
{
	"Installations": {
		"wiki1": {
			"Id": "wiki1",
			"Path": "/home/user/wiki1",
			"Orchestrator": "compose"
		},
		"wiki2": {
			"Id": "wiki2",
			"Path": "/home/user/canasta/wiki2",
			"Orchestrator": "compose"
		}
	}
}
  • Inside the object Installations there is the list of installations that the CLI currently manages.
  • "Id": It is the Canasta ID of the installation, specified during the installation.
  • "Path": This is the directory where the configuration files for the Canasta installation is stored.
  • "Orchestrator": This is the orchestrator which runs the Canasta instance. (Currently Docker's compose plugin is the only orchestrator supported by the CLI)

Uninstall

  • To uninstall the CLI, delete the binary file from the installation folder (default: /usr/local/bin/canasta)
sudo rm /usr/local/bin/canasta && sudo rm /etc/canasta/conf.json
  • Note: The argument "-i canastaId" is not necessary for any command when the command is run from the Canasta installation directory.