Merge pull request #167 from Percona-Lab/Doc-install-packages

Doc: Added install from packages instructions

documentation/docs/apt.md

@@ -0,0 +1,66 @@
+# Install `pg_tde` on Debian or Ubuntu
+
+In version Aplha1, `pg_tde` packages are available in the testing repository for Percona Distribution for PostgreSQL 16.2. Check the [list of supported platforms](install.md#__tabbed_1_2).
+
+This tutorial shows how to install `pg_tde` with [Percona Distribution for PostgreSQL](https://docs.percona.com/postgresql/latest/index.html).
+
+## Preconditions
+
+You need the `percona-release` repository management tool that enables the desired Percona repository for you.
+
+1. You need the following dependencies to install `percona-release`:
+
+    - `wget`
+    - `gnupg2`
+    - `curl`
+    - `lsb-release`
+
+    Install them with the following command:
+
+    ```bash
+    sudo apt-get install -y wget gnupg2 curl lsb-release
+    ```
+
+2. Fetch the `percona-release` package
+
+   ```bash
+   sudo wget https://repo.percona.com/apt/percona-release_latest.generic_all.deb
+   ```
+
+3. Install `percona-release`
+
+    ```bash
+    sudo dpkg -i percona-release_latest.generic_all.deb
+    ```
+
+4. Enable the Percona Distribution for PostgreSQL repository
+
+    ```bash
+    sudo percona-release enable-only ppg-16.2 testing
+    ```
+
+5. Update the local cache
+
+    ```bash
+    sudo apt-get update
+    ```
+
+## Install Percona Distribution for PostgreSQL
+
+To install Percona Distribution for PostgreSQL 16 and the required packages, run the following command:
+
+```bash
+sudo apt-get install -y percona-postgresql-16 percona-postgresql-contrib percona-postgresql-server-dev-all
+```
+
+## Install `pg_tde` packages
+
+To install `pg_tde` packages, run the following command:
+
+```bash
+sudo apt-get install percona-postgresql-16-pg-tde
+```
+
+## Next step 
+
+[Setup](setup.md){.md-button}

documentation/docs/css/design.css

@@ -81,7 +81,6 @@
     font-weight: bold;
 }
 .md-typeset h1 {
-    font-weight: normal;
     color: inherit;
 }
 .md-typeset h1 {
@@ -149,16 +148,20 @@
 .md-content .md-button {
     margin: 0 0.25em 0.5em 0;
 }
-.md-typeset .tabbed-labels>label {
+.md-typeset .tabbed-labels > label {
     font-size: 0.75rem;
     padding: 0.75em 1em;
 }
 .js .md-typeset .tabbed-labels:before {
     height: 4px;
+    background-color: var(--md-accent-fg-color);
 }
 .md-typeset [class*="moji"] {
     vertical-align: -0.25em;
 }
+.md-typeset .tabbed-set>input:first-child:checked~.tabbed-labels>:first-child, .md-typeset .tabbed-set>input:nth-child(10):checked~.tabbed-labels>:nth-child(10), .md-typeset .tabbed-set>input:nth-child(11):checked~.tabbed-labels>:nth-child(11), .md-typeset .tabbed-set>input:nth-child(12):checked~.tabbed-labels>:nth-child(12), .md-typeset .tabbed-set>input:nth-child(13):checked~.tabbed-labels>:nth-child(13), .md-typeset .tabbed-set>input:nth-child(14):checked~.tabbed-labels>:nth-child(14), .md-typeset .tabbed-set>input:nth-child(15):checked~.tabbed-labels>:nth-child(15), .md-typeset .tabbed-set>input:nth-child(16):checked~.tabbed-labels>:nth-child(16), .md-typeset .tabbed-set>input:nth-child(17):checked~.tabbed-labels>:nth-child(17), .md-typeset .tabbed-set>input:nth-child(18):checked~.tabbed-labels>:nth-child(18), .md-typeset .tabbed-set>input:nth-child(19):checked~.tabbed-labels>:nth-child(19), .md-typeset .tabbed-set>input:nth-child(2):checked~.tabbed-labels>:nth-child(2), .md-typeset .tabbed-set>input:nth-child(20):checked~.tabbed-labels>:nth-child(20), .md-typeset .tabbed-set>input:nth-child(3):checked~.tabbed-labels>:nth-child(3), .md-typeset .tabbed-set>input:nth-child(4):checked~.tabbed-labels>:nth-child(4), .md-typeset .tabbed-set>input:nth-child(5):checked~.tabbed-labels>:nth-child(5), .md-typeset .tabbed-set>input:nth-child(6):checked~.tabbed-labels>:nth-child(6), .md-typeset .tabbed-set>input:nth-child(7):checked~.tabbed-labels>:nth-child(7), .md-typeset .tabbed-set>input:nth-child(8):checked~.tabbed-labels>:nth-child(8), .md-typeset .tabbed-set>input:nth-child(9):checked~.tabbed-labels>:nth-child(9) {
+    color: var(--md-accent-fg-color);
+}
 .md-typeset .md-button [class*="moji"],
 .md-typeset .tabbed-set [class*="moji"] {
     height: 1.3333em;
@@ -175,11 +178,21 @@
     color: var(--md-default-fg-color--lighter);
 }
 .md-typeset hr {
+    margin: 3em 0;
     border-color: var(--md-default-fg-color--lighter)
 }
 .md-typeset .tabbed-labels {
     box-shadow: 0 -0.05rem var(--md-default-fg-color--lighter) inset;
 }
+.md-typeset .tabbed-button {
+    width: 1.25rem;
+    height: 1.25rem;
+    margin-top: 0.0625rem;
+}
+.md-typeset .tabbed-control {
+    width: 2.25rem;
+    height: 2.25rem;
+}
 
 /* Content re-styling */
 .md-typeset [type=checkbox]:checked + .task-list-indicator:before {
@@ -199,8 +212,8 @@
 .md-tabs__link {
     font-size: 0.67rem;
 }
-.md-tabs__link--active,
-.md-tabs__link--active a {
+.md-tabs__item--active .md-tabs__link,
+.md-tabs__item--active .md-tabs__link a {
     font-weight: bold;
     border-bottom: 0.15em solid currentColor;
 }
@@ -241,6 +254,12 @@
 [data-banner] a [class*="moji"] svg {
     width: 1.3333em;
 }
+[data-banner="logo"] > p:first-child {
+    margin-top: 0;
+}
+[data-banner="logo"] > p:first-child [class*="moji"] {
+    font-size: 4em;
+}
 [data-grid] {
     display: flex;
     flex-wrap: wrap;

documentation/docs/external-parameters.md

@@ -0,0 +1,34 @@
+# Use external reference to parameters
+
+To allow storing secrets or any other parameters in a more secure, external location, `pg_tde`
+allows users to specify an external reference instead of hardcoded parameters.
+
+In Alpha1 version, `pg_tde` supports the following external storage methods:
+
+* `file`, which just stores the data in a simple file specified by a `path`. The file should be
+readable to the postgres process.
+* `remote`, which uses a HTTP request to retrieve the parameter from the specified `url`.
+
+## Examples
+
+To use the file provider with a file location specified by the `remote` method,
+use the following command:
+
+```sql
+SELECT pg_tde_add_key_provider_file(
+    'file-provider', 
+    json_object( 'type' VALUE 'remote', 'url' VALUE 'http://localhost:8888/hello' )
+    );"
+```
+
+Or to use the `file` method, use the following command:
+
+```sql
+SELECT pg_tde_add_key_provider_file(
+    'file-provider', 
+    json_object( 'type' VALUE 'remote', 'path' VALUE '/tmp/datafile-location' )
+    );"
+```
+
+Any parameter specified to the `add_key_provider` function can be a `json_object` instead of the string, 
+similar to the above examples.

documentation/docs/functions.md

@@ -12,7 +12,7 @@ This function is intended for development, and stores the keys unencrypted in th
 SELECT pg_tde_add_key_provider_file('provider-name','/path/to/the/keyring/data.file');
 ```
 
-All parameters can be either strings, or JSON objects referencing remote parameters.
+All parameters can be either strings, or JSON objects [referencing remote parameters](external-parameters.md).
 
 ## pg_tde_add_key_provider_vault_v2
 
@@ -31,7 +31,7 @@ where:
 * `secret_token` is an access token with read and write access to the above mount point
 * [optional] `ca_path` is the path of the CA file used for SSL verification
 
-All parameters can be either strings, or JSON objects referencing remote parameters.
+All parameters can be either strings, or JSON objects [referencing remote parameters](external-parameters.md).
 
 ## pg_tde_set_master_key
 
@@ -47,23 +47,22 @@ SELECT pg_tde_set_master_key('name-of-the-master-key', 'provider-name');
 
 ## pg_tde_rotate_key
 
-Creates a new version of the specified master key, and updates the database so that it uses the new master key version.
+Creates a new version of the specified master key and updates the database so that it uses the new master key version.
 
-It can be used without any parameters, which will just create a new version of the current database
+When used without any parameters, the function will just create a new version of the current database
 master key, using the same provider:
 
 ```sql
 SELECT pg_tde_rotate_key();
 ```
 
-Or alternatively it can be used with two parameters, specifying both a new key name and a new provider
-name:
+Alternatively, you can pass two parameters to the function, specifying both a new key name and a new provider name:
 
 ```sql
 SELECT pg_tde_rotate_key('name-of-the-new-master-key', 'name-of-the-new-provider');
 ```
 
-In this case, both parameters support the `NULL` value, which means that parameter won't be changed:
+Both parameters support the `NULL` value, which means that the parameter won't be changed:
 
 ```sql
 -- creates  new master key on the same provider as before
@@ -82,35 +81,3 @@ SELECT pg_tde_is_encrypted('table_name');
 ```
 
 
-# JSON objects as remote parameters
-
-To allow storing secrets, or any other parameters in a more secure, external location, `pg_tde`
-allows users to specify an external reference instead of hardcoded parameters.
-
-Currently `pg_tde` supports two external storage methods:
-
-* `file`, which just stores the data in a simple file specified by a `path`. The file should be
-readable to the postgres process.
-* `remote`, which uses a HTTP request to retrieve the parameter from the specified `url`.
-
-As an example, to use the file provider with a file location specified by the `remote` method,
-use the following command:
-
-```sql
-SELECT pg_tde_add_key_provider_file(
-    'file-provider', 
-    json_object( 'type' VALUE 'remote', 'url' VALUE 'http://localhost:8888/hello' )
-    );"
-```
-
-Or to use the `file` method, use the following command:
-
-```sql
-SELECT pg_tde_add_key_provider_file(
-    'file-provider', 
-    json_object( 'type' VALUE 'remote', 'path' VALUE '/tmp/datafile-location' )
-    );"
-```
-
-Any parameter specified to the `add_key_provider` functions can be a json_object instead of the string,
-similar to the above examples.

documentation/docs/index.md

@@ -1,12 +1,10 @@
-# `pg_tde` documentation [Tech preview]
+# `pg_tde` documentation [Aplha1]
 
 `pg_tde` is the extension that brings in [Transparent Data Encryption (TDE)](tde.md) to PostgreSQL and enables users to keep sensitive data safe and secure. It enables users to configure encryption differently for each database, encrypting specific tables in some databases with different encryption keys, while keeping others non encrypted. 
 
 !!! important 
 
-    This is the tech preview version of the extension and is not meant for production use yet.
-
-[What's new](release-notes/tech-preview.md){.md-button}
+    This is the Alpha1 version of the extension and is not meant for production use yet.
 
 ## What's encrypted
 

documentation/docs/install.md

@@ -16,6 +16,23 @@ You can use the following options to manage encryption keys:
 
 Install `pg_tde` using one of available installation methods:
 
+
+=== "Package manager" 
+
+    Starting with Aplha1 version, you can install the extension as package from Percona repositories using the `percona-release` tool. The packages are available for the following operating systems:
+
+    - Red Hat Enterprise Linux and CentOS 7
+    - Red Hat Enterprise Linux 8 and compatible derivatives
+    - Red Hat Enterprise Linux 9 and compatible derivatives
+    - Ubuntu 20.04 (Focal Fossa)
+    - Ubuntu 22.04 (Jammy Jellyfish)
+    - Debian 10 (Buster)
+    - Debian 11 (Bullseye) 
+    - Debian 12 (Bookworm)
+
+    [Install on Debian or Ubuntu](apt.md){.md-button}
+    [Install on RHEL or derivatives](yum.md){.md-button}
+
 === "Build from source"
 
     1. To build `pg_tde` from source code, you require the following on Ubuntu/Debian:
@@ -43,22 +60,6 @@ Install `pg_tde` using one of available installation methods:
         sudo make USE_PGXS=1 install
         ```
 
-=== "Package manager" 
-
-    Currently only DEB packages for Ubuntu 22.04 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/pg_tde/releases)
-
-        ``` sh
-        wget https://github.com/Percona-Lab/pg_tde/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/pg_tde). Images are built on top of [postgres:16](https://hub.docker.com/_/postgres) official image.     

documentation/docs/setup.md

@@ -68,53 +68,12 @@ Load the `pg_tde` at the start time. The extension requires additional shared me
     ```sql
     SELECT pg_tde_set_master_key('name-of-the-master-key', 'provider-name');
     ```
-## Optional: use external parameters
 
-When configuring `pg_tde` with the steps described above, the provider configuration specified in
-step 4 is stored in the database catalog, in an unencrypted table. This is not secure to store
-sensitive parameters, such as vault secrets.
+   <i info>:material-information: Info:</i> The key provider configuration is stored in the database catalog in an unencrypted table. See [how to use external reference to parameters](external-parameters.md) to add an extra security layer to your setup.
 
-To allow storing secrets, or any other parameters in a more secure, external location, `pg_tde`
-allows users to specify an external reference instead of hardcoded parameters.
 
-Currently `pg_tde` supports two external storage methods:
-
-* `file`, which just stores the data in a simple file specified by a `path`. The file should be
-readable to the postgres process.
-* `remote`, which uses a HTTP request to retrieve the parameter from the specified `url`.
-
-As an example, to use the file provider with a file location specified by the `remote` method,
-use the following command:
-
-```sql
-SELECT pg_tde_add_key_provider_file(
-    'file-provider', 
-    json_object( 'type' VALUE 'remote', 'url' VALUE 'http://localhost:8888/hello' )
-    );"
-```
-
-Or to use the `file` method, use the following command:
-
-```sql
-SELECT pg_tde_add_key_provider_file(
-    'file-provider', 
-    json_object( 'type' VALUE 'remote', 'path' VALUE '/tmp/datafile-location' )
-    );"
-```
-
-Any parameter specified to the `add_key_provider` functions can be a json_object instead of the string,
-similar to the above examples.
-
-6. You are all set to create encrypted tables. For that, specify `USING pg_tde` in the `CREATE TABLE` statement.
-**For example**:
-```sql
-CREATE TABLE albums (
-    album_id INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-    artist_id INTEGER,
-    title TEXT NOT NULL,
-    released DATE NOT NULL
-) USING pg_tde;
 
 ## Next steps
 
 [Test TDE](test.md){.md-button}
+