diff --git a/app/_how-tos/configure-datastore.md b/app/_how-tos/configure-datastore.md new file mode 100644 index 00000000..ce1744a5 --- /dev/null +++ b/app/_how-tos/configure-datastore.md @@ -0,0 +1,104 @@ +--- +title: Configure the {{site.base_gateway}} Datastore +content_type: how_to +related_resources: + - text: Enable RBAC + url: /gateway/entities/rbac/#enable-rbac + - text: Create a Super Admin + url: /how-to/create-a-super-admin/ + +products: + - gateway + +works_on: + - on-prem + +tldr: + q: How do you configure the datastore for {{site.base_gateway}}? + a: | + * Install and configure PostgreSQL. + * Configure `kong.conf` to interact with the database. + * Run a database migration. + +prereqs: + inline: + - title: Install {{site.base_gateway}} on Ubuntu + include_content: prereqs/install/ubuntu + - title: Install PostgreSQL + include_content: prereqs/postgres + icon_url: /assets/icons/key.svg + - title: Configure environment variables + content: | + Set the following variables so that `kong.conf` can interact with the datastore: + + ```sh + export KONG_DATABASE=postgres + export KONG_PG_HOST=127.0.0.1 + export KONG_PG_PORT=5432 + export KONG_PG_USER=kong + export KONG_PG_PASSWORD=super_secret + export KONG_PG_DATABASE=kong + ``` + + +min_version: + gateway: '3.4' + +tags: + - install +--- + + +## 1. Configure PostgreSQL + +1. Switch to the default PostgreSQL user: + + ```sh + sudo -i -u postgres + ``` +2. Start the PostgreSQL shell: + + ``` + psql + ``` +2. Create a `kong` user and password + + ``` + CREATE USER kong WITH PASSWORD 'super_secret'; + ``` +3. Create a database titled `kong` and assign the user as an owner. + + ``` + CREATE DATABASE kong OWNER kong; + ``` +4. Exit PostgreSQL, and exit the PostgreSQL shell + + ``` + exit + ``` + +## 2. Run a {{site.base_gateway}} migration + +`kong migrations` is used to configure the database for the first time. Running `bootstrap` forces {{site.base_gateway}} to bootstrap the database set up in the previous step and run all of the migrations. + +```sh +kong migrations bootstrap +``` + +This command must be run as the `root` user, for instructions on running {{site.base_gateway}} as a non-root read the [Running {{site.base_gateway}} as a non-root user](/how-to/non-root) documentation. + +## 3. Validate + +You can validate that the datastore was configured correctly by starting {{site.base_gateway}}. + +1. Start {{site.base_gateway}} + + ```sh + kong start + ``` +2. Verify the installation + + ```sh + curl -i http://localhost:8001 + ``` +If you receive a `200` status code {{site.base_gateway}} was configured correctly. \ No newline at end of file diff --git a/app/_how-tos/non-root.md b/app/_how-tos/non-root.md new file mode 100644 index 00000000..d26ea9fc --- /dev/null +++ b/app/_how-tos/non-root.md @@ -0,0 +1,51 @@ +--- +title: Run {{site.base_gateway}} as a non-root user. +content_type: how_to +related_resources: + - text: Enable RBAC + url: /gateway/entities/rbac/#enable-rbac + - text: Create a Super Admin + url: /how-to/create-a-super-admin/ + +products: + - gateway + +works_on: + - on-prem + +tldr: + q: How do you configure the datastore for {{site.base_gateway}}? + a: | + * Install and configure PostgreSQL. + * Configure `kong.conf` to interact with the database. + * Run a database migration. + +prereqs: + inline: + - title: Install {{site.base_gateway}} on Ubuntu + include_content: prereqs/install/ubuntu + - title: Install PostgreSQL + include_content: prereqs/postgres + icon_url: /assets/icons/key.svg + - title: Configure environment variables + content: | + Set the following variables so that `kong.conf` can interact with the datastore: + + ```sh + export KONG_DATABASE=postgres + export KONG_PG_HOST=127.0.0.1 + export KONG_PG_PORT=5432 + export KONG_PG_USER=kong + export KONG_PG_PASSWORD=super_secret + export KONG_PG_DATABASE=kong + ``` + + +min_version: + gateway: '3.4' + +tags: + - install +--- + +@TODO \ No newline at end of file diff --git a/app/_includes/prereqs/postgres.md b/app/_includes/prereqs/postgres.md new file mode 100644 index 00000000..e371e994 --- /dev/null +++ b/app/_includes/prereqs/postgres.md @@ -0,0 +1,16 @@ +Install PostgreSQL on Ubuntu using the following steps: + +1. Update the package list: +```sh +sudo apt update +``` + +2. Install PostgreSQL: +```sh +sudo apt install -y postgresql postgresql-contrib +``` + +3. Enable PostgreSQL to start on boot: +```sh +sudo systemctl enable postgresql +``` diff --git a/tools/track-docs-changes/config/sources.yml b/tools/track-docs-changes/config/sources.yml index 383c5e4b..33ff195c 100644 --- a/tools/track-docs-changes/config/sources.yml +++ b/tools/track-docs-changes/config/sources.yml @@ -158,10 +158,13 @@ app/_how-tos/verify-build-provenance-for-signed-images.md: - app/_src/gateway/kong-enterprise/provenance-verification.md app/_how-tos/proxy-tls-passthrough.md: - app/_src/gateway/how-kong-works/routing-traffic.md + +app/_how-tos/configure-datastore.md: + - app/_src/gateway/install/post-install/set-up-data-store.md + app/_how-tos/configure-fallback-route.md: - app/_src/gateway/how-kong-works/routing-traffic/ - # plugins app/_kong_plugins/ai-rate-limiting-advanced/index.md: - app/_hub/kong-inc/ai-rate-limiting-advanced/overview/_index.md