Installing freva-deployment#

This section gives an overview over how to install the deployment software for freva.

The main work will be done by ansible, hence some level of familiarity with ansible is advantageous but not necessary. Since we are using ansible we can use this deployment routine from any workstation computer (like a Mac-book). You do not need to run the deployment on the machines where things get installed. The only requirement is you can establish ssh connections to the servers via openSSH.

Note

In most cases openSSH clients should be available on your local machine. Windows users may refer to the openSSH install page for setting up openSSH on windows.

There are different ways to install the deployment software:

1. Using pre-built binaries.#

You can download the pre-built binaries for your specific OS and architecture from the release page.

Available Binaries#

After downloading version 2507.3.0 file for your operating system and architecture, extract the binaries to a meaningful location such as ~/.local/deploy-freva:

tar xzf deploy-freva-v{{version}}-linux-x64.tar.gz -C ~/.local
ln -s ~/.local/deploy-freva/deploy-freva ~/.local/bin/

If you have ~/.local/bin in you PATH variable you can use the deploy-freva command.

2. Installation via pip.#

If you’re using Linux, OsX or a Windows subsystem for Linux (WSL) you can use pip to install the deployment software:

python3 -m pip install -U freva-deployment

This command installs ansible and all required python packages.

Warning

On CentOS python SELinux libraries need to be installed. You will need to install libselinux for your CentOS version.

python3 -m pip install libselinux-python3

3. Using docker#

A pre-built docker image is available to run the deployment

docker run -it -v /path/to/config:/opt/freva-deployment:z ghcr.io/freva-org/freva-deployment

The -it flags are important in order to interact with the program. To use and save existing configurations you can mount the directories of the config files into the container.

Commands after installation:#

The deployment software consists of three different sub-commands:

  • deploy-freva: Main deployment command via text user interface (tui).

  • deploy-freva cmd: Run already configured deployment.

  • deploy-freva migrate: Command line interface to manage project migration from old freva systems to new ones.

Main text user interface command#

deploy-freva  --help
Usage: deploy-freva [-h] [-v] [-V] [--cowsay] {cmd,config,compose,migrate} ...

Run the freva deployment

Positional Arguments:
  {cmd,config,compose,migrate}
    cmd                 Run deployment in batch mode.
    config              Create and inspect freva configuration.
    compose             Create a compose file.
    migrate             Utilities to handle migrations from old freva systems.

Options:
  -h, --help            show this help message and exit
  -v, --verbose         Verbosity level (default: 0)
  -V, --version         show program's version number and exit
  --cowsay              Let the cow speak! (default: False)

Command for running pre defined configs#

deploy-freva cmd --help
Usage: deploy-freva cmd [-h] [--config CONFIG]
                        [--steps {web,core,db,freva-rest,auto} [{web,core,db,freva-rest,auto} ...]]
                        [--ask-pass] [--ssh-port SSH_PORT] [-v] [-l] [-g]
                        [--skip-version-check] [-V]
                        [-t {core,db,cache,data-loader,freva-rest,mongodb,search-server,pre-web,web} [{core,db,cache,data-loader,freva-rest,mongodb,search-server,pre-web,web} ...]]
                        [--cowsay]

Run deployment in batch mode.

Options:
  -h, --help            show this help message and exit
  --config, -c CONFIG   Path to ansible inventory file. (default:
                        /home/runner/.config/freva/deployment/config/inventory
                        .toml)
  --steps, -s {web,core,db,freva-rest,auto} [{web,core,db,freva-rest,auto} ...]
                        The services/code stack to be deployed. Use auto to
                        only deploy outdated services (default: ['db',
                        'freva-rest', 'web', 'core'])
  --ask-pass            Connect to server via ssh passwd instead of public
                        key. (default: False)
  --ssh-port SSH_PORT   Set the ssh port, in 99.9% of the cases this should be
                        22 (default: 22)
  -v, --verbose         Verbosity level (default: 0)
  -l, --local           Deploy services on the local machine, debug purpose.
                        (default: False)
  -g, --gen-keys        Generate public and private web certs, use with
                        caution. (default: False)
  --skip-version-check  Skip the version check. Use with caution. (default:
                        False)
  -V, --version         show program's version number and exit
  -t, --tags {core,db,cache,data-loader,freva-rest,mongodb,search-server,pre-web,web} [{core,db,cache,data-loader,freva-rest,mongodb,search-server,pre-web,web} ...]
                        Fine grain deployment. Instead of using steps you can
                        set those ansible tasks (tags) to be deployed.
                        (default: None)
  --cowsay              Let the cow speak! (default: False)

Tip

Installing all services can take a considerable amount of time. If you wish to install only a specific microservice, the deploy-freva cmd subcommand provides the --tag flag to select which tasks should be executed.

Command for migrating old freva instances#

deploy-freva migrate --help
Usage: deploy-freva migrate [-h] [-v] [-V] {database} ...

Positional Arguments:
  {database}
    database     Use this command to migrate an existing freva database to a
                 recently set up system.

Options:
  -h, --help     show this help message and exit
  -v, --verbose  Verbosity level (default: 0)
  -V, --version  show program's version number and exit