# Documentation - ledgersmb-installer

## Contents

1. Quickstart
2. Overview
3. Download
4. Commands
5. Options
6. Bugs and questions
7. Contributing
8. Detailed description

## Quickstart

To install the latest LedgerSMB release with all the default options, run:

`$ curl -s -o ledgersmb-installer -L https://get.ledgersmb.org/ledgersmb-installer
$ chmod +x ledgersmb-installer
$ ./ledgersmb-installer install`

You'll want to add a version number at the end to install a specific version; e.g., to install 1.12.1:

`$ ./ledgersmb-installer install 1.12.1`

## Overview

The installer supports installation of LedgerSMB on a wide range of operating systems and platforms. When the installer is allowed to install packages through the system package manager, it will do so to satisfy missing dependencies. The package managers of the following systems are supported at the moment:

- Debian (apt) and its derivatives
- Fedora (dnf) and its derivatives

Perl dependencies which can't be installed from the system's package repository will be installed from CPAN. This means that installation on a system with an unrecognized package manager, all modules will be installed from CPAN. OpenSUSE was used to test that the installer works on platforms without a supported package manager.

## Installer download

Download the installer and make it executable using these commands:

`$ curl -s -o ledgersmb-installer -L https://get.ledgersmb.org/ledgersmb-installer
$ chmod +x ledgersmb-installer`

Or, download the content of https://get.ledgersmb.org/ledgersmb-installer using your favorite browser.

## Commands

`ledgersmb-installer install [options] <version>`
  Installs the indicated LedgerSMB version, or the latest release if no version was specified, building on the host operating system provided packages -- when on a supported platforms.
`ledgersmb-installer help`
  Shows a short help message and the installer version.
`ledgersmb-installer compute [options] <version>`
  Computes the mapping of Perl module dependencies to their distribution package equivalents for the version specified. When no version is given, the latest release is used.
`ledgersmb-installer system-id [options]`
  Prints the identifier of the system. This identifier is used to name the file containing the mapping of the Perl modules to the system packages.

## Options

### General

Options applicable to all commands.

`--log-level=<level>`
  Default value: `info`
  Available values (in increasing verbosity): `fatal`, `error`, `warning`, `info`, `debug` and `trace`
`--[no-]prepare-env`
  Default value: (ask)
  Enables installation of system tools required for installation of Perl packages, such as `make` and `gcc`. Additional dependencies may apply based on `--compute-packages`. Installed dependencies are removed after installation. This may be prevented using `--no-uninstall-env`
`--target=<path>`
  Default value: `./ledgersmb/`
  The path to use to unpack the release tarball; used with the `install` and `compute` commands
`--[no-]verify-sig`
  Default value: `--no-verify-sig`
  Use `gpg` to verify the release signature of the downloaded tarball
`--[no-]uninstall-env`
  Default value: `--uninstall-env`
  Uninstalls packages that were installed to prepare the environment for computation of the "Perl distribution to system package" mapping and the installation of Perl distributions from CPAN.
`--yes`
  Automatically answer "yes" to installer questions, allowing non-interactive use. (Shorthand: `-y`)

### compute

There are no options specific to this command.

### install

`--yes`
  Automatically answers 'yes' to any yes/no questions the installer may ask the user. Especially practical for automation purposes.
`--[no-]compute-packages`
  Default value: `--compute-packages`
  Enables computing the mapping of Perl dependencies to system packages, if no mapping could be downloaded from the precomputed repository. This behaviour is only supported when a supported package manager could be detected.
`--local-lib=<path>`
  Default value: `local`
  The location to install modules from CPAN; relative values are expanded relative to the `target` path.
`--[no-]system-packages`
  Default value: `--system-packages` if running as a user with package installation rights (usually `root`).

### system-id

There are no options specific to this command.

## Bugs and general discussion

The project is hosted on GitHub, as part of the LedgerSMB organization. Please file any bugs you run into using the provided template.

For improvement ideas, general questions and other conversations, please use GitHub Discussions.

## Contributing

Contributions take many forms: reporting bugs, helping other users with their installation problems, describing enhancement ideas and finally, submitting code changes. All of these contributions are equally valued.

If you want to add support for your favorate platform, please check out Debian support which provides a great example to get started.

## Detailed description

The installer prepares a system for running LedgerSMB. This includes:

1. Installation of
   - PostgreSQL client library (libpq)
   - LaTeX and XeTeX
   - XML parsers (libxml2 and libexpat)
2. Download and installation of LedgerSMB
3. Download and installation of Perl modules from
   1. the operating system package repositories (when possible)
   2. CPAN as the fallback
4. Install system start-up configuration

In case the installed system Perl isn't new enough for the LedgerSMB version being installed, the installer can be instructed to compile and install a suitable Perl version using Perlbrew.

Installation of the system dependencies listed in step (1) requires support for the specific operating system or (linux) distribution. Current support is available Debian and Fedora and their derivatives (e.g., Ubuntu, Mint and RedHat). Installation on other platforms requires the dependencies to be available beforehand. If this condition is met, the process should succeed. Otherwise, the lacking dependencies will be reported as missing and the installation will be undone.

### Dependency installation

Modules that are not available as system packages will be installed from CPAN distributions. Platforms without package manager support (including non-system Perl installations) will install all dependencies from CPAN. This process depends on developer tools being available. On supported platforms the installer will temporarily add these tools (and remove them after the installation completes).

Some dependencies (most notably libpq [PostgreSQL client library]) cannot be installed by the installer on systems without package manager support. In such cases, the dependencies must exist on the system before starting installation. The same applies to the `latex` dependency; without it, it's impossible to install the `LaTeX::Driver` module from CPAN.