1
0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2024-12-12 10:04:14 +02:00
pgbackrest/doc
2020-03-22 09:59:38 -04:00
..
example JSON output from the info command is no longer pretty-printed. 2019-10-11 12:56:03 -04:00
lib/pgBackRestDoc Do variable replacements for cmd-extra in documentation. 2020-03-22 09:59:38 -04:00
resource Begin v2.25 development. 2020-02-25 17:18:25 -05:00
xml Remove custom lcov build from contributing documentation. 2020-03-21 19:08:27 -04:00
.gitignore Updated vagrant to new version and image. 2017-03-14 22:05:17 -04:00
doc.pl Move pgBackRest::Version module to pgBackRestDoc::ProjectInfo. 2020-03-10 17:57:02 -04:00
FORMAT.md Note that next repo format should use UTC for backup labels. 2019-12-09 09:12:34 -05:00
manifest.xml Build contributing documentation on Travis CI. 2020-03-21 18:45:58 -04:00
README.md Add openssl-devel install to documentation build in 711b3e67. 2019-01-30 22:02:42 +02:00
RELEASE.md Add scripts required for host detection by src/configure. 2020-03-12 10:03:57 -04:00
release.pl Move pgBackRest::Version module to pgBackRestDoc::ProjectInfo. 2020-03-10 17:57:02 -04:00

pgBackRest
Building Documentation

General Builds

The pgBackRest documentation can output a variety of formats and target several platforms and PostgreSQL versions.

This will build all documentation with defaults:

./doc.pl

The user guide can be built for different platforms: centos6, centos7, and debian. This will build the HTML user guide for CentOS/RHEL 7:

./doc.pl --out=html --include=user-guide --var=os-type=centos7

Documentation generation will build a cache of all executed statements and use the cache to build the documentation quickly if no executed statements have changed. This makes proofing text-only edits very fast, but sometimes it is useful to do a full build without using the cache:

./doc.pl --out=html --include=user-guide --var=os-type=centos6 --no-cache

Each os-type has a default container image that will be used as a base for creating hosts. For centos6/centos7 these defaults are generally fine, but for debian it can be useful to change the image.

./doc.pl --out=html --include=user-guide --var=os-type=debian --var=os-image=debian:9

The following is a sample CentOS/RHEL 7 configuration that can be used for building the documentation.

# Install docker
sudo yum install -y yum-utils device-mapper-persistent-data lvm2
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce
sudo systemctl start docker

# Install tools
sudo yum install -y git wget

# Install latex (for building PDF)
sudo yum install -y texlive texlive-titlesec texlive-sectsty texlive-framed texlive-epstopdf ghostscript

# Install Perl modules that do not have CentOS packages via CPAN
sudo yum install -y yum cpanminus
sudo yum groupinstall -y "Development Tools" "Development Libraries"
sudo cpanm install --force XML::Checker::Parser

# Add documentation test user
sudo groupadd test
sudo adduser -gtest -n testdoc
sudo usermod -aG docker testdoc

Building with Packages

A user-specified package can be used when building the documentation. Since the documentation exercises most pgBackRest functionality this is a great way to smoke-test packages.

The package must be located within the pgBackRest repo and the specified path should be relative to the repository base. test/package is a good default path to use.

Ubuntu 16.04:

./doc.pl --out=html --include=user-guide --no-cache --var=os-type=debian --var=os-image=ubuntu:16.04 --var=package=test/package/pgbackrest_2.08-0_amd64.deb

CentOS/RHEL 6:

./doc.pl --out=html --include=user-guide --no-cache --var=os-type=centos6 --var=package=test/package/pgbackrest-2.08-1.el6.x86_64.rpm

CentOS/RHEL 7:

./doc.pl --out=html --include=user-guide --no-cache --var=os-type=centos7 --var=package=test/package/pgbackrest-2.08-1.el7.x86_64.rpm

Packages can be built with test.pl using the following configuration on top of the configuration given for building the documentation.

# Install recent git
sudo yum remove -y git
sudo yum install -y https://centos7.iuscommunity.org/ius-release.rpm
sudo yum install -y git2u-all

# Install Perl modules
sudo yum install -y perl-ExtUtils-ParseXS perl-ExtUtils-Embed perl-ExtUtils-MakeMaker perl-YAML-LibYAML

# Install dev libraries
sudo yum install -y libxml2-devel openssl-devel

# Add test user with sudo privileges
sudo adduser -gtest -n test
sudo usermod -aG docker test
sudo chmod 750 /home/test

sudo echo 'test ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/pgbackrest

# Add pgbackrest user required by tests
sudo adduser -gtest -n pgbackrest