1
0
mirror of https://github.com/pgbackrest/pgbackrest.git synced 2024-12-12 10:04:14 +02:00
pgbackrest/doc
David Steele fbd018cd56 Allow S3/Azure Docker images to be specified in user guide.
It is not uncommon for the S3/Azure emulators we use to introduce breaking changes without warning. If that happens the documentation can still be built by specifying a working version of the image. In general, it is better to let the version float so we know when things break.

Azurite has yet another breaking change coming up (see 096829b3, c38d6926, and Azurite issue 1039) so set azure-image at the current version until the breaking change has been released.
2021-10-20 08:22:37 -04:00
..
example JSON output from the info command is no longer pretty-printed. 2019-10-11 12:56:03 -04:00
lib/pgBackRestDoc Add br tags for HTML documentation rendering missed in def7d513. 2021-10-19 09:06:06 -04:00
resource Begin v2.36 development. 2021-08-23 07:03:40 -04:00
xml Allow S3/Azure Docker images to be specified in user guide. 2021-10-20 08:22:37 -04:00
.gitignore Fix .gitignore in doc directory. 2021-03-05 08:41:15 -05:00
doc.pl Migrate command-line help generation to C. 2021-09-08 18:16:06 -04:00
manifest.xml Migrate command-line help generation to C. 2021-09-08 18:16:06 -04:00
NEWS.md Add new instructions for PostgreSQL news and include a sample. 2021-05-03 09:34:22 -04:00
README.md Consolidate RHEL/CentOS user guide into a single document. 2021-05-24 16:03:15 -04:00
RELEASE.md Update documentation/links to main branch. 2021-10-13 12:01:53 -04:00
release.pl v2.35: Binary Protocol 2021-08-23 06:52:51 -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 rhel and debian. This will build the HTML user guide for RHEL/CentOS:

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

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=rhel --no-cache

Each os-type has a default container image that will be used as a base for creating hosts but it may be useful to change the image.

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

The following is a sample RHEL/CentOS 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

RHEL/CentOS 7:

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

RHEL/CentOS 8:

./doc.pl --out=html --include=user-guide --no-cache --var=os-type=rhel --var=os-image=centos:8 --var=package=test/package/pgbackrest-2.08-1.el8.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