You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
= Checklist to run your first {product} ({product-very-short}) instance in production.
5
+
6
+
With the default configuration, {product-short} runs with a minimal feature set that does not require secure connection to external services such as an identity provider, a Git provider, and external PostgreSQL and Redis databases.
7
+
8
+
Using critical features therefore requires following additional configuration:
9
+
10
+
For resiliency::
11
+
* Use an external PostgreSQL database.
12
+
* Enable high-availability.
13
+
14
+
For performance::
15
+
* Enable assets caching to an external Redis database.
16
+
17
+
For security::
18
+
* Use secure connections to your external services.
19
+
* Provision users and enable authentication.
20
+
* Enable role-based access control, and configure the permission policy by using the Web UI.
21
+
22
+
For adapting to your environment::
23
+
* Enable GitHub repository discovery.
24
+
* Customize {product-short} appearance with your logo.
= Configuring an {product-very-short} instance with a TLS connection in Kubernetes
5
5
6
6
You can configure a {product-very-short} instance with a Transport Layer Security (TLS) connection in a Kubernetes cluster, such as an Azure Red Hat OpenShift (ARO) cluster, any cluster from a supported cloud provider, or your own cluster with proper configuration. Transport Layer Security (TLS) ensures a secure connection for the {product-very-short} instance with other entities, such as third-party applications, or external databases. However, you must use a public Certificate Authority (CA)-signed certificate to configure your Kubernetes cluster.
{product-short} stores data in a PostgreSQL database.
11
+
Use an external database for resiliency and include it in your disaster recovery plan.
12
+
13
+
Redis cache::
14
+
For efficiency, {product-short} caches plugin and Techdocs assets when your provide a Redis cache server.
15
+
16
+
GitHub API access::
17
+
Provide credentials to a GitHub app to enable access to the GitHub API for repository discovery.
18
+
19
+
Connection to your identity provider::
20
+
Provide credentials to your identity provider to enable user provisioning and authentication.
21
+
22
+
.Procedure
23
+
* Get your external PostgreSQL database connection strings and certificates.
24
+
postgres-host::: Your PostgreSQL instance Domain Name System (DNS) or IP address.
25
+
postgres-port::: Your PostgreSQL instance port number, such as 5432.
26
+
postres-username::: The user name to connect to your PostgreSQL instance.
27
+
postgres-password::: The password to connect to your PostgreSQL instance.
28
+
postgres-ca.pem:::
29
+
postgres-key.key:::
30
+
postgres-crt.pem:::
31
+
For security, use TLS certificates to secure the connection to the database.
32
+
33
+
. Get your Redis cache server connection string, such as `rediss://user:[email protected]:6379`.
34
+
For security, consider using a `rediss` secure server connection.
35
+
36
+
. Create a GitHub App to allow {product-short} to access the GitHub API for repository.
37
+
Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, gain more control over which repositories the application can access, and use short-lived tokens.
38
+
39
+
.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration:
40
+
41
+
GitHub App name::
42
+
Enter a unique name identifying your GitHub App, such as `integrating-with-rhdh-__<GUID>__`.
43
+
44
+
Homepage URL::
45
+
Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`.
46
+
47
+
Authorization callback URL::
48
+
Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`.
49
+
50
+
Webhook::
51
+
Clear "Active", as this is not needed for authentication and catalog providers.
52
+
53
+
App permissions::
54
+
Select permissions to define the level of access for the app.
55
+
Adapt permissions to your needs:
56
+
57
+
Reading software components:::
58
+
59
+
Contents::::
60
+
`Read-only`
61
+
62
+
Commit statuses::::
63
+
`Read-only`
64
+
65
+
Reading organization data:::
66
+
67
+
Members::::
68
+
`Read-only`
69
+
70
+
Publishing software templates:::
71
+
Set permissions if you intend to use the same GitHub App for software templates.
72
+
73
+
Administration::::
74
+
`Read & write` (for creating repositories)
75
+
76
+
Contents::::
77
+
`Read & write`
78
+
79
+
Metadata::::
80
+
`Read-only`
81
+
82
+
Pull requests::::
83
+
`Read & write`
84
+
85
+
Issues::::
86
+
`Read & write`
87
+
88
+
Workflows::::
89
+
`Read & write` (if templates include GitHub workflows)
90
+
91
+
Variables::::
92
+
`Read & write` (if templates include GitHub Action Repository Variables)
93
+
94
+
Secrets::::
95
+
`Read & write` (if templates include GitHub Action Repository Secrets)
96
+
97
+
Environments::::
98
+
`Read & write` (if templates include GitHub Environments)
99
+
100
+
Organization permissions::
101
+
Members:::
102
+
`Read-only`
103
+
104
+
Where can this GitHub App be installed?::
105
+
Select `Only on this account`.
106
+
107
+
.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*.
108
+
109
+
.. In the *General* -> *Private keys* section, click *Generate a private key*.
110
+
111
+
.. In the *Install App* tab, choose an account to install your GitHub App on.
Copy file name to clipboardExpand all lines: modules/configuring/proc-provisioning-your-custom-configuration.adoc
+48-41Lines changed: 48 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,50 +14,48 @@ Your changes on this configuration might get reverted on {product-short} restart
14
14
.Prerequisites
15
15
* By using the {platform-cli-link}, you have access, with developer permissions, to the {platform-generic} cluster aimed at containing your {product-short} instance.
** To prepare a deployment with the {product} Operator on {platform}, you can start with an empty file.
30
-
31
-
** To prepare a deployment with the {product} Helm chart, or on Kubernetes, enter the {product-short} base URL in the relevant fields in your `{my-app-config-file}` file to ensure proper functionality of {product-short}.
32
-
The base URL is what a {product-short} user sees in their browser when accessing {product-short}.
33
-
The relevant fields are `baseUrl` in the `app` and `backend` sections, and `origin` in the `backend.cors` subsection:
43
+
. Author your custom `dynamic-plugins.yaml` file to enable plugins.
44
+
By default, {product-short} enables a minimal plugin set, and disables plugins that require configuration or secrets, such as the GitHub repository discovery plugin and the Role-based access control (RBAC) plugin.
34
45
+
35
-
.Configuring the `baseUrl` in `{my-app-config-file}`
36
-
====
37
-
[source,yaml,subs="+attributes,+quotes"]
46
+
Enable the GitHub repository discovery and the RBAC features:
. Provision your custom configuration files to your {platform} cluster.
63
61
@@ -68,21 +66,30 @@ backend:
68
66
$ oc create namespace {my-product-namespace}
69
67
----
70
68
71
-
.. Provision your `{my-app-config-file}` file to the `{my-app-config-config-map}`config map in the _<{my-product-namespace}>_ project.
69
+
.. Provision your `{my-app-config-file}` and `dynamic-plugins.yaml` files respectively to the `{my-app-config-config-map}`, and `dynamic-plugins-rhdh` config maps in the _<{my-product-namespace}>_ project.
link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nnodes-pods-configmap-create-from-console_configmaps[create the config maps by using the web console].
77
79
78
-
.. Provision your `_<my_product_secrets>_.txt` file to the `_<my_product_secrets>_` secret in the _<{my-product-namespace}>_ project.
80
+
.. Provision your `secrets.txt` file to the `{my-product-secrets}` secret in the _<{my-product-namespace}>_ project.
* To use an external PostgreSQL database, {configuring-book-link}configuring-external-postgresql-databases[provision your PostgreSQL database secrets].
87
-
* To enable dynamic plugins, {installing-and-viewing-plugins-book-link}[provision your dynamic plugins config map].
88
-
* To configure authorization by using external files, {authorization-book-link}#managing-authorizations-by-using-external-files[provision your RBAC policies config map].
86
+
+
87
+
Alternatively,
88
+
link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nodes-pods-secrets-creating-web-console-secrets_nodes-pods-secrets[create the secret by using the web console].
0 commit comments