diff --git a/.github/workflows/doc-build.yaml b/.github/workflows/doc-build.yaml new file mode 100644 index 00000000..c7afc717 --- /dev/null +++ b/.github/workflows/doc-build.yaml @@ -0,0 +1,69 @@ +name: Build pg_tde documentation +on: + push: + branches: + - main + - Docs + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + + steps: + #Pull the latest changes + - name: Chekout code + uses: actions/checkout@v3 + with: + fetch-depth: 0 + #Prepare the env + - name: Set up Python + uses: actions/setup-python@v3 + with: + python-version: '3.x' + + #Configure git + - name: Configure git + env: + ROBOT_TOKEN: ${{ secrets.ROBOT_TOKEN }} + run: | + git config --global url."https://percona-platform-robot:${ROBOT_TOKEN}@github.com".insteadOf "https://github.com" + git config user.name "GitHub Action" + git config user.email "github-action@users.noreply.github.com" + git config user.password "${ROBOT_TOKEN}" + echo "GIT_USER=percona-platform-robot:${ROBOT_TOKEN}" >> $GITHUB_ENV + + #Set up MkDocs + - name: Install MkDocs + run: | + cd documentation + python -m pip install --upgrade pip + pip install wheel + if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + + + + + # Deploy docs + - name: Deploy docs + run: | + cd documentation + mike deploy main -p + mike set-default main -p + + +# - name: Install Node.js 14.x +# uses: percona-platform/setup-node@v2 +# with: +# node-version: "14" +# +# - name: Spelling +# run: | +# npx markdown-spellcheck --report --en-us --ignore-acronyms --ignore-numbers "docs/**/*.md" || true + # Ignore errors, just inspect results +# - name: Grammar +# run: | +# npx write-good --no-passive docs/**/*.md || true +# # Ignore errors, just inspect results + + \ No newline at end of file diff --git a/README.md b/README.md index 56e2f941..29296f5a 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ This is an `experimental` encrypted access method for PostgreSQL 16. To download the latest build of the main branch, use the `HEAD` release from [releases](https://github.com/Percona-Lab/postgres-tde-ext/releases). Builds are available in a tar.gz format, containing only the required files, and as a deb package. -The deb package is built againts the pgdg16 release, but this dependency is not yet enforced in the package. +The deb package is built against the pgdg16 release, but this dependency is not yet enforced in the package. ## Installation steps diff --git a/documentation/docs/index.md b/documentation/docs/index.md index dc1a9960..9325f891 100644 --- a/documentation/docs/index.md +++ b/documentation/docs/index.md @@ -14,137 +14,16 @@ The encryption of indexes is planned for the next releases of `pg_tde`. -[Get started](installation.md){.md-button} +:material-alert: Warning: Note that introducing encryption/decryption affects performance. Our benchmark tests show appr. 10% performance overhead. + +[Get started](install.md){.md-button} ## Supported PostgreSQL versions `pg_tde` is currently supported for Percona Distribution for PostgreSQL 16 and PostgreSQL 16. -## Installation - -Install `pg_tde` using one of available installation methods: - -* [build from source](#build-from-source) -* [install from a package manually](#install-from-package). Currently only DEB packages are available. -* [run in Docker] - -### Build from source - -1. To build `pg_tde` from source code, you require the following on Ubuntu/Debian: - - ```sh - sudo apt install make gcc libjson-c-dev postgresql-server-dev-16 - ``` - -2. [Install Percona Distribution for PostgreSQL 16] or [upstream PostgreSQL 16] -3. If PostgreSQL is installed in a non standard directory, set the `PG_CONFIG` environment variable to point to the `pg_config` executable - -4. Clone the repository: - - ``` - git clone git://github.com/Percona-Lab/postgres-tde-ext - ``` - -5. Compile and install the extension - - ``` - cd postgres-tde-ext - make USE_PGXS=1 - sudo make USE_PGXS=1 install - ``` - -### Install from package - -Currently only DEB packages are available. If you are running RPM-based operating system, consider [building the extension from source](#build-from-source) or [running it in Docker](#run-in-docker) - -1. Download the latest [release package](https://github.com/Percona-Lab/postgres-tde-ext/releases) - - ``` sh - wget https://github.com/Percona-Lab/postgres-tde-ext/releases/download/latest/pgtde-pgdg16.deb - ``` - -2. Install the package - - ``` sh - sudo dpkg -i pgtde-pgdg16.deb - ``` - -### Run in Docker - -You can find Docker images built from the current main branch on [Docker Hub](https://hub.docker.com/r/perconalab/postgres-tde-ext). Images are built on top of [postgres:16](https://hub.docker.com/_/postgres) official image. - -To run `pg_tde` in Docker, use the following command: - -``` -docker run --name pg-tde -e POSTGRES_PASSWORD=mysecretpassword -d perconalab/postgres-tde-ext -``` - -It builds and adds `pg_tde` extension to PostgreSQL 16. Relevant `postgresql.conf` and `tde_conf.json` are created in `/etc/postgresql/` inside the container. This directory is exposed as a volume. - -See [Docker Docs](https://hub.docker.com/_/postgres) on usage. - -You can also build a Docker image manually with: - -``` -docker build . -f ./docker/Dockerfile -t your-image-name -``` - -## Setup - -1. Load the `pg_tde` at the start time. The extension requires additional shared memory; therefore, add the `pg_tde` value for the `shared_preload_libraries` parameter and restart the `postgresql` instance. - -2. Start or restart the `postgresql` instance to apply the changes. - - * On Debian and Ubuntu: - - ```sh - sudo systemctl restart postgresql.service - ``` - - * On RHEL and derivatives - - ```sh - sudo systemctl restart postgresql-16 - ``` - -3. Create the extension using the [CREATE EXTENSION](https://www.postgresql.org/docs/current/sql-createextension.html) command. Using this command requires the privileges of a superuser or a database owner. Connect to `psql` as a superuser for a database and run the following command: - - ```sql - CREATE EXTENSION pg_tde; - ``` - -4. Set the location of the keyring configuration file in postgresql.conf: `pg_tde.keyringConfigFile = '/where/to/put/the/keyring.json'` -5. Create the [keyring configuration file](#keyring-configuration) -6. Start or restart the `postgresql` instance to apply the changes. - - * On Debian and Ubuntu: - - ```sh - sudo systemctl restart postgresql.service - ``` - - * On RHEL and derivatives - - ```sh - sudo systemctl restart postgresql-16 - ``` - -### Keyring configuration - -```json -{ - 'provider': 'file', - 'datafile': '/tmp/pgkeyring', -} -``` - -Currently the keyring configuration only supports the file provider, with a single datafile parameter. - -This datafile is created and managed by PostgreSQL, the only requirement is that `postgres` should be able to write to the specified path. - -This setup is intended for developmenet, and stores the keys unencrypted in the specified data file. ## Useful links: -* [What is TDE](tde.md) +* [What is Transparent Data Encryption](tde.md) diff --git a/documentation/docs/tde.md b/documentation/docs/tde.md index f5cf4da5..fbc0a831 100644 --- a/documentation/docs/tde.md +++ b/documentation/docs/tde.md @@ -8,10 +8,14 @@ Using TDE has the following benefits: * For organizations: - - Ensure data safety when at rest and in motion - - Comply with security standards like HIPAA, PCI DSS, SOC 2, ISO 27001 + - Ensure data safety when at rest and in motion + - Comply with security standards like HIPAA, PCI DSS, SOC 2, ISO 27001 * For DBAs: - - Allows defining what to encrypt in the table and with what key - - Encryption on storage level is not a must to provide data safety. However, using TDE and storage-level encryption together adds another layer of data security \ No newline at end of file + - Allows defining what to encrypt in the table and with what key + - Encryption on storage level is not a must to provide data safety. However, using TDE and storage-level encryption together adds another layer of data security + +!!! admonition "See also" + + Percona Blog: [Transparent Data Encryption (TDE)](https://www.percona.com/blog/transparent-data-encryption-tde/) \ No newline at end of file diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 6183154a..1d3323f2 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -18,9 +18,9 @@ theme: name: material logo: _images/percona-logo.svg favicon: _images/percona-favicon.ico - custom_dir: _resource/overrides +# custom_dir: _resource/overrides font: - text: Poppins + text: Roboto palette: @@ -105,9 +105,9 @@ plugins: include_yaml: - 'variables.yml' # Use in markdown as '{{ VAR }}' -#extra: -# version: -# provider: mike +extra: + version: + provider: mike # homepage: https://docs.percona.com # consent: # title: Cookie consent diff --git a/documentation/requirements.txt b/documentation/requirements.txt new file mode 100644 index 00000000..f3e0361a --- /dev/null +++ b/documentation/requirements.txt @@ -0,0 +1,16 @@ + +Markdown +mkdocs +mkdocs-versioning +mkdocs-macros-plugin +mkdocs-exclude +markdown-include +mkdocs-material +mkdocs-with-pdf +mkdocs-git-revision-date-localized-plugin +mkdocs-material-extensions +mkdocs-bootstrap-tables-plugin +mkdocs-section-index +mkdocs-htmlproofer-plugin +mkdocs-meta-descriptions-plugin +mike