Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@tmberthold
tmberthold authored Feb 3, 2025
1 parent b33e9c3 commit cae2128
Showing 1 changed file with 28 additions and 28 deletions.
56 changes: 28 additions & 28 deletions docs/deployment-guide/goals/production/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
icon: square-dashed-circle-plus
---

Deploying the Authority Portal in Production
Deploying the Data Space Portal in Production
============

## About this Guide

This is a productive deployment guide for deploying the Authority Portal from scratch.
This is a productive deployment guide for deploying the Data Space Portal from scratch.

## Prerequisites

Expand Down Expand Up @@ -53,21 +53,21 @@ The respective compatible versions can be found in the [CHANGELOG.md](../../../.
| Keycloak Deployment | Version 24.0.4 or compatible version |
| OAuth2 Proxy | quay.io/oauth2-proxy/oauth2-proxy:7.5.0 |
| Caddy behind OAuth2 Proxy | caddy:2.7 |
| Authority Portal Backend | authority-portal-backend, see [CHANGELOG.md](../../../../CHANGELOG.md) for compatible versions. |
| Authority Portal Frontend | authority-portal-frontend, see [CHANGELOG.md](../../../../CHANGELOG.md) for compatible versions. |
| Data Space Portal Backend | authority-portal-backend, see [CHANGELOG.md](../../../../CHANGELOG.md) for compatible versions. |
| Data Space Portal Frontend | authority-portal-frontend, see [CHANGELOG.md](../../../../CHANGELOG.md) for compatible versions. |
| Catalog Crawler (one per environment) | authority-portal-crawler, see [CHANGELOG.md](../../../../CHANGELOG.md) for compatible versions. |
| Postgresql | Version 16 or compatible version |
### Configuration
#### Reverse Proxy / Ingress
- Authority Portal needs to be deployed with TLS/HTTPS.
- The domain under which the Authority Portal should be reachable on the internet will be referred to as `[AP_FQDN]` in this
- Data Space Portal needs to be deployed with TLS/HTTPS.
- The domain under which the Data Space Portal should be reachable on the internet will be referred to as `[DSPORTAL_FQDN]` in this
guide.
- Path mapping:
- Frontend: `https://[AP_FQDN]` -> `caddy:8080` -> `frontend:8080`
- Backend: `https://[AP_FQDN]/api` -> `caddy:8080` -> `oauth2-proxy:8080` -> `caddy:8081` -> `backend:8080/api`
- Frontend: `https://[DSPORTAL_FQDN]` -> `caddy:8080` -> `frontend:8080`
- Backend: `https://[DSPORTAL_FQDN]/api` -> `caddy:8080` -> `oauth2-proxy:8080` -> `caddy:8081` -> `backend:8080/api`
#### Keycloak IAM Deployment
Expand All @@ -82,7 +82,7 @@ The respective compatible versions can be found in the [CHANGELOG.md](../../../.
- Consider consulting Keycloak's [server administration guide](https://www.keycloak.org/docs/latest/server_admin/).
- You need to have a running Keycloak with the aforementioned compatible version.
- The domain under which the Keycloak should be reachable on the internet will be referred to as `[KC_FQDN]` in this
guide and should differ from the `[AP_FQDN]`.
guide and should differ from the `[DSPORTAL_FQDN]`.
- The steps to set up the realm are the following
- sovity theme
1. Copy [sovity-theme](../../../../authority-portal-keycloak/sovity-theme) directory to `{keycloakRoot}/themes/` directory
Expand All @@ -93,7 +93,7 @@ The respective compatible versions can be found in the [CHANGELOG.md](../../../.
- `Valid Redirect URIs`: (Relative) callback URL of auth proxy, e.g. `/oauth2/callback`
- `Valid post logout redirect URIs`: `/*`
4. Adjust settings for `authority-portal-client` client (Clients > `authority-portal-client` > Settings)
- `Root URL`: URL of the authority portal, e.g. `https://authority-portal.example.url`
- `Root URL`: URL of the Data Space Portal, e.g. `https://authority-portal.example.url`
- `Home URL`: (Most likely) same as `Root URL`
5. Regenerate client secrets for `oauth2-proxy` and `authority-portal-client` clients
- Clients > `[client]` > Credentials > Regenerate (Client secret)
Expand All @@ -112,7 +112,7 @@ The respective compatible versions can be found in the [CHANGELOG.md](../../../.
- `Valid Redirect URIs`: (Relative) callback URL of auth proxy, e.g. `/oauth2/callback`
- `Valid post logout redirect URIs`: `/*`
4. Adjust settings for `authority-portal-client` client (Clients > `authority-portal-client` > Settings)
- `Root URL`: URL of the authority portal, e.g. `https://authority-portal.example.url`
- `Root URL`: URL of the Data Space Portal, e.g. `https://authority-portal.example.url`
- `Home URL`: (Most likely) same as `Root URL`
5. Regenerate client secrets for `oauth2-proxy` and `authority-portal-client` clients
- Clients > `[client]` > Credentials > Regenerate (Client secret)
Expand All @@ -138,7 +138,7 @@ AUTH_PROXY_UPSTREAM_HOST: auth-proxy
#### OAuth2 Proxy
- The Authority Portal is meant to be deployed with an OAuth2 Proxy in front of the Portal Backend.
- The Data Space Portal is meant to be deployed with an OAuth2 Proxy in front of the Portal Backend.
- The OAuth2 Proxy should be configured to use the Keycloak (IAM) as OAuth2 Provider.
- Copy the contents from [resources](../../../../authority-portal-oauth2-proxy/resources) to a directory the OAuth2 proxy can access (`CUSTOM_TEMPLATES_DIR`)

Expand All @@ -159,15 +159,15 @@ OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:8080
OAUTH2_PROXY_PASS_ACCESS_TOKEN: "true"
OAUTH2_PROXY_SKIP_PROVIDER_BUTTON: "true"
OAUTH2_PROXY_SHOW_DEBUG_ON_ERROR: "true"
OAUTH2_PROXY_REDIRECT_URL: https://[AP_FQDN]/oauth2/callback
OAUTH2_PROXY_REDIRECT_URL: https://[DSPORTAL_FQDN]/oauth2/callback
OAUTH2_PROXY_SCOPE: openid profile
OAUTH2_PROXY_WHITELIST_DOMAINS: [KC_FQDN]
OAUTH2_PROXY_CUSTOM_TEMPLATES_DIR: [CUSTOM_TEMPLATES_DIR]
```

#### Keycloak DAPS Client Creation

The Authority Portal requires a client to register new connector certificates.
The Data Space Portal requires a client to register new connector certificates.
This client must have the following settings:

- Section `Authentication flow` (Tab `Settings`)
Expand All @@ -181,7 +181,7 @@ This client must have the following settings:
- `realm-management` > `view-clients` enabled
- `realm-management` > `query-clients` enabled

#### Authority Portal Backend
#### Data Space Portal Backend

- Image: `ghcr.io/sovity/authority-portal-backend`
- Set environment variables according to the following documentation (mandatory, except log level)
Expand All @@ -204,7 +204,7 @@ quarkus.keycloak.admin-client.realm: "[KC_REALM]"
# Keycloak Admin Client: Client ID
quarkus.keycloak.admin-client.client-id: "authority-portal-client"
# Keycloak Admin Client: Client secret
quarkus.keycloak.admin-client.client-secret: "[AP_CLIENT_SECRET]"
quarkus.keycloak.admin-client.client-secret: "[DSPORTAL_CLIENT_SECRET]"
# Keycloak Admin Client: Grant type
quarkus.keycloak.admin-client.grant-type: "CLIENT_CREDENTIALS"
Expand All @@ -226,16 +226,16 @@ authority-portal.caas.sovity.limit-per-organization: "1"
quarkus.oidc-client.sovity.client-enabled: true
# Must equal the root URL/home URl from the Keycloak configuration - see above)
authority-portal.base-url: "https://[AP_FQDN]"
authority-portal.base-url: "https://[DSPORTAL_FQDN]"
# API key to protect config endpoints, like /api/config/log-level
authority-portal.config.api-key: "[AP_CONFIG_API_KEY]"
authority-portal.config.api-key: "[DSPORTAL_CONFIG_API_KEY]"
# Invitation link expiration time in seconds. (Must equal the value in Keycloak configuration)
authority-portal.invitation.expiration: "43200"
# Environment Configuration
# - Each Authority Portal can be configured with multiple environments, e.g. test, staging, prod, etc.
# - Each Data Space Portal can be configured with multiple environments, e.g. test, staging, prod, etc.
# - Following is an example configuration of the "test" environment.
# - Please Note, that the environment "test" is mandatory
Expand Down Expand Up @@ -299,27 +299,27 @@ Example:
curl -X PUT 'https://authority-portal.example.com/api/config/log-level?level=DEBUG' --header 'x-api-key: uYtR_wNsvXU4EbV9GioACnj!NHML_HRX'
```

#### Authority Portal Frontend
#### Data Space Portal Frontend

- Image: `ghcr.io/sovity/authority-portal-frontend`
- Set environment variables according to the following table (mandatory)

```yaml
AUTHORITY_PORTAL_FRONTEND_BACKEND_URL: https://[AP_FQDN] # Authority Portal URL
AUTHORITY_PORTAL_FRONTEND_LOGIN_URL: https://[AP_FQDN]/oauth2/start?rd=https%3A%2F%2F[AP_FQDN] # Auth Proxy: Login URL (with redirect to the Authority Portal)
AUTHORITY_PORTAL_FRONTEND_BACKEND_URL: https://[DSPORTAL_FQDN] # Data Space Portal URL
AUTHORITY_PORTAL_FRONTEND_LOGIN_URL: https://[DSPORTAL_FQDN]/oauth2/start?rd=https%3A%2F%2F[DSPORTAL_FQDN] # Auth Proxy: Login URL (with redirect to the Data Space Portal)
# Following is the URL to signal the Auth Proxy to log out the user.
# Example: https://[AP_FQDN]/oauth2/sign_out?rd=https%3A%2F%2F[KC_FQDN]%2Frealms%2F[KC_REALM]l%2Fprotocol%2Fopenid-connect%2Flogout%3Fclient_id%3Doauth2-proxy%26post_logout_redirect_uri%3Dhttps%253A%252F%252F[AP_FQDN]
# Example: https://[DSPORTAL_FQDN]/oauth2/sign_out?rd=https%3A%2F%2F[KC_FQDN]%2Frealms%2F[KC_REALM]l%2Fprotocol%2Fopenid-connect%2Flogout%3Fclient_id%3Doauth2-proxy%26post_logout_redirect_uri%3Dhttps%253A%252F%252F[DSPORTAL_FQDN]
AUTHORITY_PORTAL_FRONTEND_LOGOUT_URL: (...) # Auth Proxy: Logout URL
AUTHORITY_PORTAL_FRONTEND_INVALIDATE_SESSION_COOKIES_URL: https://[AP_FQDN]/oauth2/sign_out # Auth Proxy: URL to invalidate sessions cookies
AUTHORITY_PORTAL_FRONTEND_INVALIDATE_SESSION_COOKIES_URL: https://[DSPORTAL_FQDN]/oauth2/sign_out # Auth Proxy: URL to invalidate sessions cookies
AUTHORITY_PORTAL_FRONTEND_LEGAL_NOTICE_URL: https://yourdataspace.com/legal-notice # Legal Notice URL
AUTHORITY_PORTAL_FRONTEND_PRIVACY_POLICY_URL: https://yourdataspace.com/privacy-policy # Privacy policy URL
AUTHORITY_PORTAL_FRONTEND_SUPPORT_URL: https://support.yourdataspace.com # Support page URL
AUTHORITY_PORTAL_FRONTEND_ACTIVE_PROFILE: sovity-open-source # UI Branding profile (sovity-open-source)
AUTHORITY_PORTAL_FRONTEND_DATASPACE_SHORT_NAME: ExDS # Short Dataspace name, used in some explanatory texts
AUTHORITY_PORTAL_FRONTEND_PORTAL_DISPLAY_NAME: "Authority Portal" # Portal name displayed in various texts
AUTHORITY_PORTAL_FRONTEND_PORTAL_DISPLAY_NAME: "Data Space Portal" # Portal name displayed in various texts
AUTHORITY_PORTAL_FRONTEND_ENABLE_DASHBOARD: true # Enables or disables the status uptime dashboard
# Direct URL to the UPDATE_PASSWORD required action in Keycloak
AUTHORITY_PORTAL_FRONTEND_UPDATE_PASSWORD_URL: https://[KC_FQDN]/realms/authority-portal/protocol/openid-connect/auth?response_type=code&client_id=oauth2-proxy&scope=openid&kc_action=UPDATE_PASSWORD&redirect_uri=https%3A%2F%2F[AP_FQDN]%2Foauth2%2Fcallback
AUTHORITY_PORTAL_FRONTEND_UPDATE_PASSWORD_URL: https://[KC_FQDN]/realms/authority-portal/protocol/openid-connect/auth?response_type=code&client_id=oauth2-proxy&scope=openid&kc_action=UPDATE_PASSWORD&redirect_uri=https%3A%2F%2F[DSPORTAL_FQDN]%2Foauth2%2Fcallback
```

Expand Down Expand Up @@ -351,10 +351,10 @@ Although it is discouraged to do so, the expected value `broker` could be overri
# Required: Fully Qualified Domain Name
MY_EDC_FQDN: "crawler.test.example.com"
# Required: Authority Portal Environment ID
# Required: Data Space Portal Environment ID
CRAWLER_ENVIRONMENT_ID: test
# Required: Authority Portal Postgresql DB Access
# Required: Data Space Portal Postgresql DB Access
CRAWLER_DB_JDBC_URL: jdbc:postgresql://authority-portal:5432/portal
CRAWLER_DB_JDBC_USER: portal
CRAWLER_DB_JDBC_PASSWORD: portal
Expand Down

0 comments on commit cae2128

Please sign in to comment.