The runkit is a collection of tools for running WebHare on desktops and servers and testing backup/restore procedures.

To get started immediately:

curl https://gitlab.com/webhare/runkit/-/raw/main/install.sh | bash

Which will clone the repository and install the runkit command in your bash shell. (If you're a different shell, run bash to get runkit shell integration to work)

You can also clone the repository using either of:

• git clone git@gitlab.com:webhare/runkit.git webhare-runkit
• git clone https://gitlab.com/webhare/runkit.git webhare-runkit

You can then add eval $(~/webhare-runkit/bin/runkit setupmyshell) to your shell to get bash integration, invoke webhare-runkit/bin/runkit manually or add it to your path. All examples below assume that runkit will invoke bin/runkit from this project.

Runkit will store its data in $HOME/whrunkit/ or /opt/runkit-data/ (if invoked as root) by default. You can override this directory by setting the WHRUNKIT_DATADIR environment variable.

There are currently two supported methods to build WebHare from source:

• Building on a Mac
• Building a container (Docker) image

You need to install Homebrew first. If you're seeing errors such as 'brew: command not found' or 'exec: node: not found' make sure Homebrew is properly installed and you've added eval "$(/opt/homebrew/bin/brew shellenv)" to your profile (or invoked manually)

### Building WebHare itself

```bash
runkit download-webhare-source
runkit create-server --default mywebhare
runkit wh make install

(wh make currently require a default server to exist - even if you don't plan on using it)

If you want to modify WebHare itself or develop on the supporting code (eg the VSCode module, proxy or language extensions) see Developing WebHare

After completing the above, try runkit wh console

runkit download-webhare-source
runkit create-server --default mywebhare
runkit wh buildcontainer

Before you can use runkit, you need to set up a new installation or add your existing installation:

• add-existing-server [--default] <servername> <path> - Add an already configured WebHare
• create-server [--default] <servername> - Set up a new installation with the given name

Examples:

# Sets up a new server (will be initialized by invoking 'runkit @mytest console')
runkit create-server mytest

# Adds ~/projects/whdata/myserver as your primary installation
runkit add-existing-server --default myserver ~/projects/whdata/myserver

The primary installation is the one with baseport '13679' and will be bound to the wh alias by runkit's setupmyshell. Other installs are bound to a wh-server alias eg wh-mytest. You can always target a server using runkit @<server> ....

# General help
runkit help
# List runkit managed servers
runkit list-servers
# Update server.
runkit @<servername> upgrade [image]
# The update is not effective until the server is restarted
runkit @<servername> run-webhare --as-service

Image references used in runkit upgrade (and in runkit create-server) are usually a release branch, eg release/5.6 to get the most recent 5.6.x release. It can also be a full container image reference (eg: docker.io/webhare/platform:release-5-6) or an explicit version (eg 5.6.7). If upgrade is invoked without an image reference it will upgrade inside the last selected branch.

Note that you must use run-webhare to apply the update - if you simply restart the unit or the server it will still use the last started image.

# Install a tagged version
runkit run-proxy --as-service --set-image 3.4.1
# Install the most recent development version
runkit run-proxy --as-service --set-image master

runkit can be used to manage a podman-based server.

runkit run-proxy --as-service

Most users will simply install the proxy container from the Docker registry. If you want to develop on the proxy itself you can run it outside a container.

# Ensure the proxy project is installed and linked into runkit:
runkit list-projects
# If proxy is missing:
runkit link-proxy ~/projects/proxy
# Use run-proxy to run it. It will use $WHRUNKIT_DATADIR/_proxy/data as its data dir
runkit run-proxy --nocontainer

A useful option in development is to set up a local CI WebHare server. This allows you to locally test your CI process on a “fresh” WebHare installation.

See the documentation for an example of how you could do this.

We've built runkit restore around borg backup repositories. You need to supply runkit with the proper credentials to access these backups. Request these credentials from whoever is hosting your backups. Either the *borgbase.borg or the *rsync.borg files can be used (if both available).

Paste these credentials into runkit set-borg-credentials <server> and test the credentials by entering runkit list-backups <server>.

If you keep a restored WebHare running you'll want to remove 'whdata/preparedbackup' and download directories as they only take up space once the restore is done

runkit restore-server will create a file webhare.restoremode in the whdata directory with details about which archive was restored. The presence of this file will cause WebHare to launch in 'restore mode'.

To exit restore mode, run wh exit-restore-mode. This will restart WebHare!

These recipes assume you are logged in to the server on which you will be restoring WebHare and that you have set CONTAINER to the server you're restoring (eg CONTAINER=demo)

List backups, restore a specific one and launch WebHare:

# Get a listing
runkit list-backups $CONTAINER
# Replace ARCHIVENAME with preferred archive
runkit restore-server --archive ARCHIVENAME $CONTAINER
# Install a proxy and WebHare (master branch) and start it
~/webhare-runkit/bin/startup-proxy-and-webhare.sh $CONTAINER
# Open a shell inside the WebHare container
~/webhare-runkit/bin/enter-webhare.sh $CONTAINER

Things you can do inside the container

# Get your bearings, verify WEBHARE_ISRESTORED is set
wh dirs
# Add a backend interface by IP. Look up the right IP address first. In chrome, bypass certwarning by typing "thisisunsafe"
wh webserver --addbackend https://159.223.25.195/
# Get an override token to use with the backend - keep in mind that you need to append the override token to an URL such as above
wh cli getoverride "Verifying restored server"

Eg. to locally debug an issue with a server. This assumes you have runkit and WebHare's source tree installed. In the example the container is still named demo and the demo.borg credentials file is present.

Use runkit restore-server to create a new 'restored from backup' server (don't use runkit create-server). You can add --nocontainer to restore-server and launch-webhare.sh to use your local WebHare source tree instead of containers. This will generally be faster if you've built a compatible version of WebHare for the data you're restoring.

You can add the --fast option to restore-server to skip the restoration of logs and output.

You can redo database extraction (sometimes useful when testing) with --skipdownload if you've succesfully downloaded the backup earlier

CONTAINER=demo
runkit restore-server $CONTAINER
runkit @$CONTAINER console

If borg gives you such as argument REPOSITORY_OR_ARCHIVE: Invalid location format: "" you need to open-backup.sh on the server first. This sets some environment variables that tell borg how to access the backup data.

To watch the logs for a running WebHare: ~/webhare-runkit/bin/watch-webhare.sh $CONTAINER

Keep in mind that if you run all this on a mac, WebHare's database will be running over a Docker volume mount and eg. index reconstruction after the restore can take quite some time, especially if this installation isn't using postgres yet.