diff --git a/.github/workflows/cratedb-ee-docs.yml b/.github/workflows/cratedb-ee-docs.yml new file mode 100644 index 0000000..5e88f5c --- /dev/null +++ b/.github/workflows/cratedb-ee-docs.yml @@ -0,0 +1,35 @@ +name: cratedb-ee-docs +on: + pull_request: ~ + push: + branches: + - main + + # Allow job to be triggered manually. + workflow_dispatch: + +# Cancel in-progress jobs when pushing to the same branch. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + documentation: + name: Build CrateDB EE docs on ubuntu-latest + runs-on: ubuntu-latest + + steps: + - name: Acquire sources + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.13" + cache: 'pip' + cache-dependency-path: | + cratedb-ee-docs/requirements.txt + + - name: Build CrateDB EE docs + run: | + cd cratedb-ee-docs && make check diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index feec5f4..537a638 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -15,7 +15,7 @@ concurrency: jobs: documentation: - name: Build docs on ubuntu-latest + name: Build Cloud docs on ubuntu-latest runs-on: ubuntu-latest steps: @@ -30,6 +30,6 @@ jobs: cache-dependency-path: | docs/requirements.txt - - name: Build docs + - name: Build Cloud docs run: | cd docs && make check diff --git a/.gitignore b/.gitignore index f9baf9e..d9e563e 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,5 @@ .env .idea *.lint +cratedb-ee-docs/.env +cratedb-ee-docs/_build diff --git a/cratedb-ee-docs/.readthedocs.yaml b/cratedb-ee-docs/.readthedocs.yaml new file mode 100644 index 0000000..6779fe8 --- /dev/null +++ b/cratedb-ee-docs/.readthedocs.yaml @@ -0,0 +1,15 @@ +build: + os: "ubuntu-22.04" + tools: + python: "3.11" + +sphinx: + builder: html + configuration: cratedb-ee-docs/conf.py + fail_on_warning: true + +python: + install: + - requirements: cratedb-ee-docs/requirements.txt + +version: 2 diff --git a/cratedb-ee-docs/Makefile b/cratedb-ee-docs/Makefile new file mode 100644 index 0000000..f73d760 --- /dev/null +++ b/cratedb-ee-docs/Makefile @@ -0,0 +1,159 @@ +# Licensed to Crate (https://crate.io) under one or more contributor license +# agreements. See the NOTICE file distributed with this work for additional +# information regarding copyright ownership. Crate licenses this file to you +# under the Apache License, Version 2.0 (the "License"); you may not use this +# file except in compliance with the License. You may obtain a copy of the +# License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations under +# the License. +# +# However, if you have executed another commercial license agreement with Crate +# these terms will supersede the license and you may use the software solely +# pursuant to the terms of the relevant commercial agreement. + + +# ============================================================================= +# Crate Docs +# ============================================================================= + +# The Crate Docs project provides a common set of tools for producing the +# Crate.io documentation. See for more +# information. + +# This file is taken from the demo Sphinx project available at +# . This demo docs project +# provides a reference implementation that should be copied for all Sphinx +# projects at Crate.io. + +# The Crate Docs build system works by centralizing its core components in the +# `crate-docs` repository. At build time, this Makefile creates a copy of the +# this project under the `.crate-docs` directory. This Makefile is an interface +# for those core components. + + +# Upgraded instructions +# ----------------------------------------------------------------------------- + +# You must pin your Sphinx project to a specific version of the Crate Docs +# project. You can do this by editing the `build.json` file. Change the JSON +# `message` value to the desired release number. A list of releases is +# available at . + +# Although care has been taken to restrict changes to the core components, you +# may occasionally need to update your project to match the reference +# implementation. Check the release notes for any special instructions. + + +# Project-specific customization +# ============================================================================= + +# If you want to customize the build system for your Sphinx project, add lines +# to this section. + + +# Build system integration +# ============================================================================= + +# This is a boilerplate section is required for integration with the Crate Docs +# build system. All Sphinx projects using a the same Crate Docs version +# should have exactly the same boilerplate. + +# IF YOU ARE EDITING THIS FILE IN A REAL SPHINX PROJECT, YOU SHOULD NOT MAKE +# ANY CHANGES TO THIS SECTION. + +# If you want to make changes to the boilerplate, please make a pull request on +# the demo Sphinx project in the Crate Docs repository available at +# . + +.EXPORT_ALL_VARIABLES: + +DOCS_DIR := cratedb-ee-docs +TOP_DIR := .. +BUILD_JSON := build.json +BUILD_REPO := https://github.com/crate/crate-docs.git +LATEST_BUILD := https://github.com/crate/crate-docs/releases/latest +CLONE_DIR := .crate-docs +SRC_DIR := $(CLONE_DIR)/common-build +SELF_SRC := $(TOP_DIR)/common-build +SELF_MAKEFILE := $(SELF_SRC)/rules.mk +SRC_MAKE := $(MAKE) -f $(SRC_DIR)/rules.mk + +# Parse the JSON file +BUILD_VERSION := $(shell cat $(BUILD_JSON) | \ + python3 -c 'import json, sys; print(json.load(sys.stdin)["message"])') + +ifeq ($(BUILD_VERSION),) +$(error No build version specified in `$(BUILD_JSON)`.) +endif + +# This is a non-essential check so we timeout after only two seconds so as not +# to frustrate the user when there are network issues +LATEST_VERSION := $(shell curl -sI --connect-timeout 2 '$(LATEST_BUILD)' | \ + grep -i 'Location:' | grep -Eoh '[^/]+$$') + +# Skip if no version could be determined (i.e., because of a network error) +ifneq ($(LATEST_VERSION),) +# Only issue a warning if there is a version mismatch +ifneq ($(BUILD_VERSION),$(LATEST_VERSION)) +define version_warning +You are using Crate Docs version $(BUILD_VERSION), however version \ +$(LATEST_VERSION) is available. You should consider upgrading. Follow the \ +instructions in `Makefile` and then run `make reset`. +endef +endif +endif + +# Default rule +.PHONY: help +help: $(CLONE_DIR) + @ $(MAKE) version-warn + @ $(SRC_MAKE) $@ + +.PHONY: version-warn +version-warn: + @ # Because version numbers may vary in length, we must wrap the warning + @ # message at run time to be sure of correct output + @ if test -n '$(version_warning)'; then \ + printf '\033[33m'; \ + echo '$(version_warning)' | fold -w 79 -s; \ + printf '\033[00m\n'; \ + fi + +ifneq ($(wildcard $(SELF_MAKEFILE)),) +# The project detects itself and fakes an install of its own core build rules +# so that it can test itself +$(CLONE_DIR): + @ printf '\033[1mInstalling the build system...\033[00m\n' + @ mkdir -p $@ + @ cp -R $(SELF_SRC) $(SRC_DIR) + @ printf 'Created: $(CLONE_DIR)\n' +else +# All other projects install a versioned copy of the core build rules +$(CLONE_DIR): + @ printf '\033[1mInstalling the build system...\033[00m\n' + @ git clone --depth=1 -c advice.detachedHead=false \ + --branch=$(BUILD_VERSION) $(BUILD_REPO) $(CLONE_DIR) + @ printf 'Created: $(CLONE_DIR)\n' +endif + +# Don't pass through this target +.PHONY: Makefile +Makefile: + +# By default, pass targets through to the core build rules +.PHONY: +%: $(CLONE_DIR) + @ $(MAKE) version-warn + @ $(SRC_MAKE) $@ + +.PHONY: reset +reset: + @ printf '\033[1mResetting the build system...\033[00m\n' + @ rm -rf $(CLONE_DIR) + @ printf 'Removed: $(CLONE_DIR)\n' diff --git a/cratedb-ee-docs/_assets b/cratedb-ee-docs/_assets new file mode 120000 index 0000000..170bb7d --- /dev/null +++ b/cratedb-ee-docs/_assets @@ -0,0 +1 @@ +../docs/_assets \ No newline at end of file diff --git a/cratedb-ee-docs/_extra/robots.txt b/cratedb-ee-docs/_extra/robots.txt new file mode 120000 index 0000000..a02df47 --- /dev/null +++ b/cratedb-ee-docs/_extra/robots.txt @@ -0,0 +1 @@ +../../docs/_extra/robots.txt \ No newline at end of file diff --git a/cratedb-ee-docs/build.json b/cratedb-ee-docs/build.json new file mode 100644 index 0000000..d736c53 --- /dev/null +++ b/cratedb-ee-docs/build.json @@ -0,0 +1,5 @@ +{ + "schemaVersion": 1, + "label": "docs build", + "message": "2.2.0" +} diff --git a/cratedb-ee-docs/conf.py b/cratedb-ee-docs/conf.py new file mode 100644 index 0000000..8787d6a --- /dev/null +++ b/cratedb-ee-docs/conf.py @@ -0,0 +1,28 @@ +from crate.theme.rtd.conf import * + +# Disable version chooser. +html_context.update({ + "display_version": False, + "current_version": None, + "versions": [], +}) + +project = "CrateDB Enterprise Edition" +html_title = project + +url_path = "docs/crate/enterprise" +html_baseurl = "https://cratedb.com/%s/" % url_path + +exclude_patterns += ["_build", "Thumbs.db", ".DS_Store"] + +source_suffix = ['.rst', '.md'] + +linkcheck_ignore = [ + # Example link only, not meant to exist + "http://iss_hostname:8080/api/v2/meta/jwk/", + # 403 for non-browser clients (bot protection) + "https://www.ibm.com/docs/", +] + + +linkcheck_timeout = 5 diff --git a/cratedb-ee-docs/features/automation.md b/cratedb-ee-docs/features/automation.md new file mode 120000 index 0000000..4fa6a52 --- /dev/null +++ b/cratedb-ee-docs/features/automation.md @@ -0,0 +1 @@ +../../docs/cluster/automation.md \ No newline at end of file diff --git a/cratedb-ee-docs/features/console.md b/cratedb-ee-docs/features/console.md new file mode 120000 index 0000000..2335e39 --- /dev/null +++ b/cratedb-ee-docs/features/console.md @@ -0,0 +1 @@ +../../docs/cluster/console.md \ No newline at end of file diff --git a/cratedb-ee-docs/features/index.rst b/cratedb-ee-docs/features/index.rst new file mode 100644 index 0000000..25163e7 --- /dev/null +++ b/cratedb-ee-docs/features/index.rst @@ -0,0 +1,17 @@ +======== +Features +======== + +To access the CrateDB EE Console, simply log in with any of your CrateDB users credentials. + +CrateDB EE Console provides an overview of your CrateDB cluster. +You can also explore your table schemas, check the users in your cluster and a monitoring +section where you can see the state of your CrateDB nodes and tables. + +In addition to that, the following you can also find the following features: + +.. toctree:: + :titlesonly: + + console + automation diff --git a/cratedb-ee-docs/index.rst b/cratedb-ee-docs/index.rst new file mode 100644 index 0000000..30a02c3 --- /dev/null +++ b/cratedb-ee-docs/index.rst @@ -0,0 +1,16 @@ +.. CrateDB Enterprise Edition documentation master file + +CrateDB Enterprise Edition +========================== + +CrateDB Enterprise Edition brings additional features to your on-premises CrateDB cluster. + +The CrateDB EE Console can be installed separately, allows you to log in with your own +CrateDB users and brings a web interface with many features like monitoring, a SQL +console, running queries periodically and more! + +.. toctree:: + :titlesonly: + + install/index + features/index diff --git a/cratedb-ee-docs/install/debian.rst b/cratedb-ee-docs/install/debian.rst new file mode 100644 index 0000000..b9de932 --- /dev/null +++ b/cratedb-ee-docs/install/debian.rst @@ -0,0 +1,90 @@ +======================================= +Installation on Debian and derivatives +======================================= + +.. include:: prerequisites.rst + +Supported platforms +-------------------- + +The following distributions are supported: + +- Debian 13 Trixie +- Ubuntu 24.04 LTS and newer + +Please note only the ``amd64`` architecture is currently supported. + +Installation guide +------------------- + +The installation is performed via a DEB package served from a private APT repository. + + +.. stepper:: + +Configure the private package repository +-------------------------------------------- + +The DEB package is installed from a private APT repository. Make sure ``curl`` is +available on the target machine, then configure the repository credentials and +signing key. + +.. code-block:: bash + + sudo apt update + sudo apt install curl + + +First, store the credentials provided to you by creating an auth file so that APT can +authenticate against the private repository: + +.. code-block:: bash + + sudo install -d -m 0755 /etc/apt/auth.conf.d + +Create ``/etc/apt/auth.conf.d/cratedb-ee.conf`` with the following content, replacing +``{username}`` and ``{token}`` with the credentials provided to you: + +.. code-block:: text + + machine cratedb-ee.git.onstackit.cloud + login {username} + password {token} + +Next, fetch the repository's signing key and add the repository itself using the following +commands: + +.. code-block:: bash + + sudo install -d -m 0755 /etc/apt/keyrings + + curl -fsSL --netrc-file /etc/apt/auth.conf.d/cratedb-ee.conf \ + https://cratedb-ee.git.onstackit.cloud/api/packages/cratedb/debian/repository.key \ + | sudo tee /etc/apt/keyrings/cratedb-ee.asc >/dev/null + + echo "deb [signed-by=/etc/apt/keyrings/cratedb-ee.asc] \ + https://cratedb-ee.git.onstackit.cloud/api/packages/cratedb/debian stable main" \ + | sudo tee /etc/apt/sources.list.d/cratedb-ee.list + + sudo apt update + +.. stepper:: + +Install CrateDB Enterprise Edition +-------------------------------------- + +To install the package, run the following command: + +.. code-block:: bash + + sudo apt install cratedb-ee-console + +Installing the package will also install its required dependencies, including ``podman``. + +Once the installation is complete, CrateDB EE console needs to be configured before it +can be used. +During the configuration step, user input will be required. + +.. include:: setup.rst + + diff --git a/cratedb-ee-docs/install/index.rst b/cratedb-ee-docs/install/index.rst new file mode 100644 index 0000000..f00dba2 --- /dev/null +++ b/cratedb-ee-docs/install/index.rst @@ -0,0 +1,13 @@ +Installation +============ + +CrateDB EE Console is available for the following platforms: + +* :doc:`Installation guide for Debian and Ubuntu and other Debian based distributions ` +* :doc:`Installation guide for Fedora and other Red Hat based distributions ` + +.. toctree:: + :hidden: + + debian + redhat diff --git a/cratedb-ee-docs/install/prerequisites.rst b/cratedb-ee-docs/install/prerequisites.rst new file mode 100644 index 0000000..35e78ad --- /dev/null +++ b/cratedb-ee-docs/install/prerequisites.rst @@ -0,0 +1,45 @@ +Prerequisites +------------- + +CrateDB EE console has the following requirements: + +- The CrateDB cluster must be running +- The CrateDB cluster must be reachable from the machine where CrateDB EE is to be installed. + This can be achieved either by having direct access to at least one of the CrateDB nodes or via a load balancer. + Access via a load balancer is preferred. + Connectivity will be established to any port via the HTTP protocol and to port 5432 via the PG protocol, the installation process will aid in the setup if needed. +- A CrateDB user that can authenticate via password from where the CrateDB EE Console will be installed. This user will be used during the setup. +- The CrateDB EE console machine must be reachable from the CrateDB nodes. Specifically, ports 9443 and 8080. +- The machine where the CrateDB EE console is to be installed must be able to reach the Internet to download the package. +- Requires being able to modify the configuration of all CrateDB nodes. +- Requires restarting all CrateDB nodes. + +Preparing the CrateDB cluster for the installation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The installation requires a CrateDB user that can authenticate from the machine where the +installation will take place. + +That user needs the privilege ``AL`` because it will create new users. + +For more information about privileges you can read the `CrateDB privileges documentation `_. +You will need to create a user if none is available yet. + +This can be done with the following SQL statement: + +.. code-block:: sql + + CREATE USER WITH (password = ''); + GRANT AL TO ; + +If your CrateDB configuration already has host based authentication you may need to add a new +configuration entry to be able to authenticate with the user from the target machine. +Here is an example configuration that allows: + +.. code-block:: yaml + + - -Cauth.host_based.enabled=true + - -Cssl.http.enabled=true + - -Cauth.host_based.config.05_setup.protocol=http + - -Cauth.host_based.config.05_setup.method=password + - -Cauth.host_based.config.05_setup.user= diff --git a/cratedb-ee-docs/install/redhat.rst b/cratedb-ee-docs/install/redhat.rst new file mode 100644 index 0000000..03e5593 --- /dev/null +++ b/cratedb-ee-docs/install/redhat.rst @@ -0,0 +1,91 @@ +======================================= +Installation on Red Hat and derivatives +======================================= + +.. include:: prerequisites.rst + +Supported platforms +-------------------- + +The following distributions are supported: + +- Fedora +- Red Hat +- Rocky Linux + +Please note only the ``amd64`` architecture is currently supported. + +Installation guide +------------------- + +The installation is performed via an RPM package that must be manually downloaded from a +generic repository. + + +.. stepper:: + +Download the CrateDB Enterprise Edition package +-------------------------------------------------- + +The installation is performed via an RPM package served from a private repository. + +The first step is to fetch the repository's and package signing keys and store it in the machine: + +.. code-block:: bash + + sudo curl -fsSL -u '{username}:{token}' \ + https://cratedb-ee.git.onstackit.cloud/api/packages/cratedb/rpm/repository.key \ + -o /etc/pki/rpm-gpg/RPM-GPG-KEY-cratedb-ee + + sudo curl -fsSL -u '{username}:{token}' \ + https://cratedb-ee.git.onstackit.cloud/api/packages/cratedb/generic/cloud-enterprise/0.0.10/cratedb-ee-console-0.0.10-1.x86_64.rpm.key.asc \ + -o /etc/pki/rpm-gpg/RPM-GPG-KEY-cratedb-ee-console + + +Next, import the downloaded keys: + +.. code-block:: bash + + sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-cratedb-ee + sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-cratedb-ee-console + + +Then, create a file named ``/etc/yum.repos.d/cratedb-ee.repo`` and add the following content: + +.. code-block:: text + + [cratedb-ee] + name=CrateDB Enterprise Edition RPM repository + baseurl=https://cratedb-ee.git.onstackit.cloud/api/packages/cratedb/rpm + enabled=1 + gpgcheck=1 + gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-cratedb-ee + username={username} + password={token} + +Replace ``{username}`` and ``{token}`` with the credentials provided to you. + + +.. stepper:: + +Install CrateDB Enterprise Edition +------------------------------------ + +To install the downloaded package, run the following command: + +.. code-block:: bash + + # on RedHat based distributions + sudo dnf install cratedb-ee-console + + # on SUSE based distributions + sudo zypper install cratedb-ee-console + +Installing the package will also install its required dependencies, including ``podman``. + +Once the installation is complete, CrateDB EE console needs to be configured before it +can be used. +During the configuration step, user input will be required. + + +.. include:: setup.rst diff --git a/cratedb-ee-docs/install/setup.rst b/cratedb-ee-docs/install/setup.rst new file mode 100644 index 0000000..164c01c --- /dev/null +++ b/cratedb-ee-docs/install/setup.rst @@ -0,0 +1,224 @@ +.. stepper:: + +Configure CrateDB Enterprise Edition +--------------------------------------- + +To launch the setup, simply run the following commands once the package has been installed: + +.. code-block:: bash + + cd /opt/crate/cratedb-ee-console + sudo installer/setup.sh + +The setup script will ask some questions to help identifying the right configuration. + +Connection to the CrateDB cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The URL to the cluster and a CrateDB user name and password will be asked. +Please note that the given CrateDB user credentials must be able to authenticate from this host. + +Configuration of a truststore +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +CrateDB Enterprise Console relies on the truststore in the CrateDB cluster for its own authentication purposes and this +step will help set it up. + +It is recommended you use the already present truststore, if available. If you want to override it, make sure you make a +backup of the existing truststore first. + +The setup script will first ask whether the CrateDB cluster already has a truststore set up. + +You can select one of the following paths: + +- Let the setup create a new ``CA`` certificate and a new truststore storing that certificate. +- Provide an already existing ``CA`` certificate and let the setup create a truststore that stores it. +- Provide a ``CA`` certificate stored in a truststore already installed in the CrateDB server. + +Please note the certificate used to serve the CrateDB Enterprise Console to the browser will be signed by the ``CA`` +certificate stored in the truststore. This means you will see a warning in the browser if it does not trust the +``CA`` certificate. + + +When a truststore is already set up on CrateDB +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If a trust store is already set up in the CrateDB cluster, the files ``ca.crt`` and ``ca.key`` contained in it will need +to be copied to the locations given by the setup script. This is necessary because CrateDB EE +uses certificate based authentication and the setup script will use these files to generate +the required certificates. + +Once the certificates have been generated, the ``ca.crt`` file is still needed for authorization purposes. + +When CrateDB does not have a truststore set up +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If a trust store is not configured in the CrateDB cluster, the setup script will generate one. +The script will first ask whether you already have a ``ca.crt`` you would like to use as the +certificate authority for the new truststore. Answering yes lets you supply your own ``CA``; +answering no makes the script generate a new self-signed ``CA`` to issue the certificates from. + +The script will then ask for a truststore password and a keystore password, used to protect +the generated ``truststore.p12`` and ``keystore.p12`` files, respectively. Please keep these passwords, as they are +needed again when configuring the CrateDB cluster below. + +Distribute the truststore to the CrateDB cluster +"""""""""""""""""""""""""""""""""""""""""""""""""" + +If a truststore has been generated by the script, you must copy its files to each CrateDB +node of your cluster. Before you do that please make sure you are not accidentally overriding +any truststore already present in the cluster. + +Once the setup script has finished, copy ``keystore.p12`` and ``truststore.p12`` from +``/etc/opt/crate/cratedb-ee-console/ca/`` to every CrateDB cluster node, for example: + +.. code-block:: bash + + scp /etc/opt/crate/cratedb-ee-console/ca/truststore.p12 @: + scp /etc/opt/crate/cratedb-ee-console/ca/keystore.p12 @: + +The official CrateDB container certificate path is ``/certs/``. + +Please note these commands assume the CrateDB EE Console machine can access via the default port SSH +all the CrateDB nodes. Depending on your system configuration this will not be the case. + +CrateDB must be able to read these files. The official CrateDB container image runs as +uid ``1000``, so once the files are in place on the node, make sure they are owned by, or +readable by, that user, for instance ``chown 1000:1000 truststore.p12 keystore.p12``. +A keystore that CrateDB cannot read will write to its logs a ``keystore password was incorrect`` +error. + +Apply the configuration to the CrateDB cluster +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A configuration stub to help configure the CrateDB nodes will be generated by the script +and can be found at ``/etc/opt/crate/cratedb-ee-console/cratedb-config.txt`` +It looks similar to: + +.. code-block:: yaml + + - -Cauth.host_based.enabled=true + - -Cauth.host_based.jwt.iss="https://:9443/api/v2/meta/jwk/" + - -Cssl.http.enabled=true + - -Cssl.psql.enabled=true + - -Cssl.keystore_filepath= + - -Cssl.keystore_password= + - -Cssl.keystore_key_password= + - -Cssl.truststore_filepath= + - -Cssl.truststore_password= + - -Cauth.host_based.config.10_ee_console.user=cratedb_ee + - -Cauth.host_based.config.10_ee_console.ssl=on + - -Cauth.host_based.config.10_ee_console.method=cert + - -Cauth.host_based.config.20_issuer.address=/32 + - -Cauth.host_based.config.20_issuer.protocol=http + - -Cauth.host_based.config.20_issuer.method=password + - -Cauth.host_based.config.30_users_jwt.protocol=http + - -Cauth.host_based.config.30_users_jwt.method=jwt + +Add these settings to each CrateDB node configuration (for example the ``command`` section +of CrateDB's ``docker-compose.yaml``, or ``crate.yml``), then restart every CrateDB node for the +new configuration and TLS certificates to take effect. + +Please make sure there are no name collisions with any existing host based authentication +configuration your CrateDB may already have (the ``30_users_jwt`` part, for instance). + +Reaching the CrateDB EE Console +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The setup script will ask for the host name or IP that will be used by end users to connect to the CrateDB EE. +This is required to properly generate the SSL certificate that will be served by the web server. + +In the case of users that are to access CrateDB EE via port forwarding into the machine, localhost is valid. + +Otherwise, the value must be the hostname or IP that the users will have to type in their browser to access CrateDB EE. + +Please note this may be different from the IP or domain of the machine, depending on your setup. + +Clean up +~~~~~~~~~ + +Once the setup script has completed, and the certificate files have been copied to every +CrateDB node and applied to the CrateDB configuration, delete the following files from the +CrateDB EE Console machine, as they are no longer needed there and contain sensitive key material: + +- ``ca.key`` +- ``keystore.p12`` (if present) +- ``truststore.p12`` (if present) + +These files live under ``/etc/opt/crate/cratedb-ee-console/ca/``. + + +.. stepper:: + +Start, stop and restart CrateDB Enterprise Edition +---------------------------------------------------- + +Once CrateDB has been configured and restarted with the settings above, start the +CrateDB EE services: + +.. code-block:: bash + + sudo systemctl start cratedb-ee-mgmt + +Use the following commands to stop and restart CrateDB Enterprise Edition: + +.. code-block:: bash + + sudo systemctl stop cratedb-ee-mgmt + sudo systemctl restart cratedb-ee-mgmt + + +Access CrateDB Enterprise Console +------------------------------------- + +CrateDB EE is now reachable at ``https://:9443``, using the hostname or IP +address given during setup. + + +Changing the CrateDB Enterprise Console configuration manually +---------------------------------------------------------------- + +The setup script will automatically generate a configuration that should work. +It is recommended to rely on the setup script. + +The file ``/etc/opt/crate/cratedb-ee-console/config.sh`` stores the configuration. + +The following variables can be changed: + +- CRATEDB_EE_FRONTDOOR: Full URL that points to the CrateDB Enterprise Console web app using SSL. +- CRATEDB_EE_FRONTDOOR_HTTP: Full URL that points to the CrateDB Enterprise Console web app using plain HTTPS. It will redirect to its SSL counterpart. +- CRATEDB_EE_CRATEDB_EXTERNAL_URL: Full URL that points to the CrateDB cluster (either a load balancer or one of its nodes). The protocol must be HTTPS. +- CRATEDB_EE_DNS: The hostname (or static IP) that represents the CrateDB cluster load balancer or one of its nodes. +- CRATEDB_EE_MINTER_ISS: Full URL with the structure http://iss_hostname:8080/api/v2/meta/jwk/ where iss_hostname is the container that mints the authentication tokens. + Please note this URL will be part of the token as the ISS field and must exactly match the ``auth.host_based.jwt.iss`` configuration parameter in the CrateDB cluster, otherwise login attempts will fail. +- CRATEDB_EE_ONPREM_CLUSTER_ID: The Cluster ID of the CrateDB cluster. + +To apply any change to the configuration, the following commands must be executed: + +.. code-block:: bash + + sudo systemctl stop cratedb-ee-mgmt + sudo /opt/crate/cratedb-ee-console/installer/install-images.sh + sudo systemctl start cratedb-ee-mgmt + + +Troubleshooting +----------------- + +Login failures +~~~~~~~~~~~~~~~~ + +The most common issues related to login failures are: + +- The ``CRATEDB_EE_MINTER_ISS`` not matching exactly (including the protocol) the ``auth.host_based.jwt.iss`` CrateDB authentication configuration. +- The ``CRATEDB_EE_ONPREM_CLUSTER_ID`` not matching the CrateDB cluster ID. Check your CrateDB cluster ID by executing the query ``SELECT id FROM sys.cluster``. +- A CrateDB authentication configuration rule is not correct. + +Look for login issues in the CrateDB logs. +Alternatively, look for login issues in the CrateDB Enterprise Console minter: + +.. code-block:: bash + + journalctl -u systemctl status minter + +Make sure the IP specified in the CrateDB configuration and the IP of the CrateDB Enterprise Console seen by the CrateDB cluster are the same. diff --git a/cratedb-ee-docs/requirements.txt b/cratedb-ee-docs/requirements.txt new file mode 100644 index 0000000..a775060 --- /dev/null +++ b/cratedb-ee-docs/requirements.txt @@ -0,0 +1,2 @@ +crate-docs-theme>=0.50.3 +myst-parser<5 diff --git a/docs/cluster/automation.md b/docs/cluster/automation.md index 6a2f957..d8849c0 100644 --- a/docs/cluster/automation.md +++ b/docs/cluster/automation.md @@ -1,17 +1,12 @@ (cluster-automation)= # Automation -Automation in CrateDB Cloud allows users to streamline and manage routine +Automation allows users to streamline and manage routine database operations efficiently. Two primary automation features available are the SQL Scheduler and Table Policies, both of which facilitate the maintenance and optimization of database tasks. -:::{important} -- Automation is available for all newly deployed clusters. -- For existing clusters, the feature can be enabled on demand. (Contact - [support](https://support.cratedb.com/) for activation.) - -Automation utilizes a dedicated database user `gc_admin` with full cluster +Automation utilizes a dedicated database user with full cluster privileges to execute scheduled tasks and persists data in the `gc` schema. ::: @@ -20,9 +15,8 @@ privileges to execute scheduled tasks and persists data in the `gc` schema. The SQL Scheduler is designed to automate routine database tasks by scheduling SQL queries to run at specific times, in UTC time. This feature supports creating job descriptions with valid [cron patterns](https://www.ibm.com/docs/en/db2-as-a-service?topic=task-unix-cron-format) -and SQL statements, enabling a wide range of tasks. Users can manage these jobs -through the Cloud UI, adding, removing, editing, activating, and deactivating -them as needed. +and SQL statements, enabling a wide range of tasks. Users can manage these jobs +by adding, removing, editing, activating, and deactivating them as needed. ### Use Cases @@ -137,7 +131,7 @@ A new policy can be created with the "Add New Policy" button. After naming the policy and selecting the table to be impacted, you must specify the time column. This column, which should be a timestamp used for partitioning, will determine the data affected by the policy. If you have multiple -partitioned tables you will need to setup a policy per table. +partitioned tables you will need to set up a policy per table. :::{note} The "Time Column" must be of type `TIMESTAMP`. diff --git a/docs/cluster/console.md b/docs/cluster/console.md index 61a5a69..495ae37 100644 --- a/docs/cluster/console.md +++ b/docs/cluster/console.md @@ -1,9 +1,8 @@ (cluster-console)= # Console -The Console in CrateDB Cloud allows users to execute SQL queries seamlessly -against their CrateDB cluster. The Console can be accessed by users having the -"Organization Admin" role in the left-hand navigation menu within a cluster. +The Console allows users to execute SQL queries seamlessly +against their CrateDB cluster. - **Table and Schema Tree View:** Easily navigate through your database structure. @@ -12,15 +11,6 @@ against their CrateDB cluster. The Console can be accessed by users having the - **Multiple Query Execution:** Run several queries in sequence. - **Query History:** Access and manage your past queries. -:::{important} -- The Console is available for all newly deployed clusters. -- For older clusters, this feature can be enabled on demand. Contact - [support](https://support.cratedb.com/) for activation. - -The Console currently utilizes a dedicated database user `gc_admin` with full -cluster privileges. -::: - :::{note} **Multi-Query Execution:** When running multiple queries at once, the Console executes them sequentially, @@ -30,7 +20,7 @@ between queries. ::: :::{note} -Each CrateDB Cloud cluster offers a dedicated {ref}`Admin UI `, +Each cluster offers a dedicated {ref}`Admin UI `, which can be used to explore data, schema metadata, and cluster status information. ::: diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 54e20d2..11c6a42 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -95,7 +95,7 @@ documentation is an entity that reads event data from an IoT hub. It is possible to use a consumer, such as Azure IoT Hub, with CrateDB Cloud: you can store the data processed by the consumer on the Cloud {ref}`cluster `. For a tutorial -on how to do this, see [documentation examples](https://cratedb.com/docs/crate/howtos/en/latest/reference-architectures/cratedb-azure-iot.html). +on how to do this, see [documentation examples](https://docs.cratedb.com/projects/guide/solution/industrial/azure-iot.html). Operations on consumers are registered in the {ref}`Audit Log `.